Métodos da biblioteca

Use os métodos estáticos de DatabaseService para a conexão padrão. Para escolher outra conexão ou base, chame connection(nome) ou database(nome); o DatabaseClient retornado oferece os mesmos métodos select e execute. Importe as classes de io.mindqa.database. O tipo de banco e as credenciais vêm da configuração.

Método	Função	Retorno
select(sql, params...)	Consulta dados.	List<Map<String, Object>>
execute(sql, params...)	Executa INSERT, UPDATE ou DELETE.	Quantidade de linhas afetadas (int)
connection(nome)	Seleciona uma conexão configurada; disponível em DatabaseService.	DatabaseClient
database(nome)	Seleciona outra base; disponível em DatabaseService e DatabaseClient.	Novo DatabaseClient
clearConfigurationCache()	Descarta o cache de configuração; disponível em DatabaseService.	void
closePools()	Fecha os pools; disponível em DatabaseService.	void

DatabaseService.database(nome) usa a conexão padrão. Após DatabaseService.connection(nome), a chamada database(nome) preserva a conexão selecionada e troca apenas a base. O exemplo pressupõe as conexões e bases configuradas, com o registro cliente-1 preparado em cada destino.

import io.mindqa.database.DatabaseClient;
import io.mindqa.database.DatabaseService;

import java.util.List;
import java.util.Map;

import static org.junit.jupiter.api.Assertions.assertEquals;

String id = "cliente-1";
List<Map<String, Object>> clientes = DatabaseService.select(
        "SELECT nome FROM clientes WHERE id = ?", id);
assertEquals(1, clientes.size());

DatabaseClient financeiro = DatabaseService.connection("financeiro");
List<Map<String, Object>> clientesFinanceiro = financeiro.select(
        "SELECT nome FROM clientes WHERE id = ?", id);
assertEquals(1, clientesFinanceiro.size());

List<Map<String, Object>> auditoria = financeiro.database("qa_auditoria")
        .select("SELECT nome FROM clientes WHERE id = ?", id);
assertEquals(1, auditoria.size());

List<Map<String, Object>> clientesEmOutraBase = DatabaseService.database("qa_clientes")
        .select("SELECT nome FROM clientes WHERE id = ?", id);
assertEquals(1, clientesEmOutraBase.size());

int removidos = financeiro.database("qa_auditoria")
        .execute("DELETE FROM clientes WHERE id = ?", id);
assertEquals(1, removidos);

connection(nome) aceita letras ASCII e números, começa com uma letra e ignora maiúsculas e espaços nas extremidades. O nome precisa corresponder a uma conexão configurada; o tipo do banco não é um parâmetro da query. Os clientes retornados são imutáveis e podem ser reutilizados. No Oracle, o nome da base é um service name. Em qualquer motor, database(null) ou um nome em branco mantém a base definida na configuração.

Passe os valores na ordem dos placeholders ?. Para um único valor SQL NULL, use (Object) null. Placeholders substituem valores, não nomes de tabelas, colunas ou bases. O SQL deve respeitar o dialeto do banco escolhido.

select devolve uma lista vazia quando não há resultados. Cada mapa representa uma linha, indexada pelo nome ou alias das colunas, com os tipos retornados pelo JDBC. execute devolve a quantidade de linhas afetadas, não um ID gerado.

Como a biblioteca requer Java 17, variáveis locais também podem usar var:

var clientes = DatabaseService.select(
        "SELECT nome, email FROM clientes WHERE id = ?", id);

Os exemplos usam List<Map<String, Object>> explicitamente para deixar visível o tipo retornado por select(). var não pode ser usado em atributos, parâmetros ou retornos de métodos.

SQL nulo ou em branco, array de parâmetros nulo e nome de conexão inválido geram IllegalArgumentException. Configuração ausente ou ambígua e arquivo ilegível geram IllegalStateException. Falhas JDBC lançam DatabaseException, cuja mensagem vem do driver e cuja SQLException original fica disponível em getCause() e getSQLException().

Cada operação usa sua própria conexão em auto-commit e a fecha automaticamente; com pool habilitado, o fechamento a devolve ao pool. Não há transação compartilhada entre chamadas. Consulte Erros e solução de problemas para configurar o pool e o cache.