Referência de configuração - raialmeida/mindqa-db-commons GitHub Wiki

Referência de configuração

Configure as chaves em src/test/resources/database.properties, em outro arquivo selecionado com db.config ou como variáveis de ambiente. As variáveis de ambiente têm prioridade sobre o arquivo, inclusive quando vazias. O arquivo padrão é carregado do classpath; consulte Configuração por ambiente para as opções de seleção. A biblioteca não interpola ${VAR} dentro do arquivo.

Formatos de conexão

Formato Exemplo Seleção
Simples DB_TYPE=postgres, DB_HOST=localhost Chamadas estáticas usam esta configuração quando não há DB_DEFAULT_CONNECTION; DB_TYPE ausente usa SQL Server.
Por motor POSTGRESQL_HOST=localhost connection("postgresql"); o tipo é inferido do prefixo.
Nomeada DB_CONNECTIONS_PRINCIPAL_TYPE=postgres, DB_CONNECTIONS_PRINCIPAL_HOST=localhost connection("principal").
Nomeada por motor POSTGRESQL_PRINCIPAL_HOST=localhost connection("principal"); o tipo é inferido do prefixo.

Os prefixos por motor são SQLSERVER_, POSTGRESQL_, ORACLE_ e MYSQL_. Para DatabaseService.select, execute ou database, a escolha segue esta ordem:

  1. DB_DEFAULT_CONNECTION, quando preenchido, seleciona o nome configurado.
  2. Sem esse seletor, a presença de campos de conexão simples DB_* seleciona essa configuração, mesmo que incompleta.
  3. Sem campos simples, uma única conexão nomeada é selecionada automaticamente.
  4. Com várias conexões nomeadas e sem configuração simples, é necessário definir DB_DEFAULT_CONNECTION.

connection(nome) sempre escolhe o destino explicitamente e não depende do padrão. O nome pode ser, por exemplo, principal ou postgresBase.

Conexões nomeadas não herdam credenciais nem opções da configuração simples. No formato DB_CONNECTIONS_<NOME>_*, TYPE ausente também usa SQL Server; para outro motor, informe TYPE ou use um prefixo que permita inferir o tipo.

Variáveis por conexão

Use as chaves DB_* para configurar uma conexão no formato simples. Para os demais formatos, aplique o prefixo correspondente; por exemplo, DB_HOST pode ser representado por POSTGRESQL_HOST, DB_CONNECTIONS_PRINCIPAL_HOST ou POSTGRESQL_PRINCIPAL_HOST.

Chave no formato simples Obrigatória Função
DB_TYPE Não sqlserver, postgres/postgresql, oracle ou mysql; padrão: sqlserver.
DB_HOST Sim Host, IPv4 ou IPv6, sem porta ou URL.
DB_PORT Não Porta de 1 a 65535; usa a porta padrão do motor quando omitida.
DB_USER Sim Usuário da conexão.
DB_PASS Sim Senha; um valor vazio é preservado.
DB_NAME Condicional Base ou service name Oracle; dispensável ao usar database(nome).
DB_QUERY_TIMEOUT_SECONDS Não Limite para o statement em segundos; padrão 0 (sem limite da biblioteca).
DB_LOGIN_TIMEOUT_SECONDS Não Limite de conexão em segundos; padrão 0 (driver).
DB_ENCRYPT Não SQL Server: true, false ou strict; padrão false.
DB_TRUST_SERVER_CERTIFICATE Não SQL Server: true ou false; padrão false.
DB_DRIVER_PROPERTIES Não Opções adicionais do driver, em chave=valor&outra=valor.
DB_POOL_ENABLED Não Reutilização de conexões físicas; padrão false.
DB_POOL_MAX_SIZE Não Máximo de conexões físicas por pool; padrão 5.
DB_POOL_CONNECTION_TIMEOUT_MS Não Espera por conexão livre; padrão 30000 ms.

DB_CONFIG_CACHE_ENABLED é global e não recebe prefixo. Seu padrão é false. Consulte Erros e solução de problemas para o ciclo de vida do pool e do cache.

Motor Porta padrão URL JDBC gerada
SQL Server 1433 jdbc:sqlserver://HOST:PORT;databaseName=DB;encrypt=false;trustServerCertificate=false;
PostgreSQL 5432 jdbc:postgresql://HOST:PORT/DB
Oracle 1521 jdbc:oracle:thin:@//HOST:PORT/SERVICE_NAME
MySQL 3306 jdbc:mysql://HOST:PORT/DB

No Oracle, DB_NAME e database(nome) representam o service name, não o SID ou o schema. Para consultar outro schema, qualifique a tabela no SQL. IPv6 pode ser escrito como ::1 ou [::1]. Os nomes de base são escapados na URL.

Arquivos e precedência

Arquivos usam UTF-8 e sintaxe Java Properties, inclusive as regras de escape para senhas; BOM é aceito. No arquivo, também são aceitas chaves com pontos e minúsculas, como db.host e oracle.pass. Variáveis de ambiente usam as chaves em maiúsculas. O caminho no classpath começa após src/test/resources/.

mvn test -Ddb.config=classpath:ambientes/qa.properties
mvn test -Ddb.config=file:./config/qa.properties
mvn test -Ddb.config=/opt/automacao/config/hml.properties

Sem classpath: ou file:, a biblioteca busca primeiro no classpath e depois no sistema de arquivos. Um arquivo explicitamente selecionado e ausente ou ilegível gera erro, mesmo quando as credenciais estão no ambiente. Arquivos .env não são lidos automaticamente; use export no shell ou configure o ambiente do runner.

Timeouts e opções do driver

DB_QUERY_TIMEOUT_SECONDS aceita 0 a 2147483647; DB_LOGIN_TIMEOUT_SECONDS aceita 0 a 65535. O limite de query cobre a execução do statement, não toda a chamada. O timeout de conexão é encaminhado ao driver por loginTimeout no SQL Server e PostgreSQL, oracle.jdbc.loginTimeout no Oracle e connectTimeout em milissegundos no MySQL. Não altera o timeout global do DriverManager.

DB_DRIVER_PROPERTIES pode passar opções específicas para o driver:

POSTGRESQL_DRIVER_PROPERTIES=ApplicationName=qa-automation&sslmode=require
SQLSERVER_ENCRYPT=true
SQLSERVER_TRUST_SERVER_CERTIFICATE=false

Use codificação percentual para &, = e espaços em nomes ou valores, por exemplo applicationName=qa%20automation. Credenciais, host, porta, base, timeouts, encrypt e trustServerCertificate devem usar suas chaves próprias; não podem ser redefinidos em DRIVER_PROPERTIES. As opções de driver não informadas seguem os padrões de cada driver.

⚠️ **GitHub.com Fallback** ⚠️