ps-conecta-firebird

Biblioteca para conexão simples com o banco de dados Firebird, com API baseada em Promises sobre o node-firebird. Escrita em TypeScript, com tipos incluídos.

Instalação

npm install ps-conecta-firebird

Requer Node.js 14 ou superior.

Uso básico

import { FirebirdConnection, Config } from "ps-conecta-firebird";

const config: Config = {
  host: "localhost",
  port: 3050,
  database: "/dados/base.fdb",
  user: "SYSDBA",
  password: "masterkey",
};

const conexao = new FirebirdConnection(config);

// Consulta com parâmetros (sempre prefira parâmetros a concatenar SQL)
const clientes = await conexao.queryExecute<{ ID: number; NOME: string }>(
  "SELECT ID, NOME FROM CLIENTES WHERE CIDADE = ?",
  ["São Paulo"]
);

Cada chamada a queryExecute abre uma conexão, executa a query dentro de uma transaction, faz commit e desconecta. Em caso de erro, a transaction sofre rollback e a Promise é rejeitada com o erro original.

Pool de conexões

Para aplicações com volume de queries, use FirebirdPool — mesma API, mas as conexões são reaproveitadas em vez de abertas a cada chamada:

import { FirebirdPool } from "ps-conecta-firebird";

const pool = new FirebirdPool({ ...config, maxConnections: 10 });

const clientes = await pool.queryExecute("SELECT * FROM CLIENTES");

// ao encerrar a aplicação:
await pool.destroy();

Múltiplas queries na mesma transaction

runInTransaction executa um bloco atômico: commit se a função resolver, rollback se rejeitar. Disponível em FirebirdConnection e FirebirdPool:

await pool.runInTransaction(async (tx) => {
  await tx.query("UPDATE CONTAS SET SALDO = SALDO - ? WHERE ID = ?", [100, 1]);
  await tx.query("UPDATE CONTAS SET SALDO = SALDO + ? WHERE ID = ?", [100, 2]);
});

Configuração

| Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | host | string | sim | Endereço do servidor Firebird | | port | number | sim | Porta do servidor (padrão do Firebird: 3050) | | database | string | sim | Caminho ou alias do arquivo .fdb | | user | string | sim | Usuário do banco | | password | string | sim | Senha do usuário | | lowercase_keys | boolean | não | Retorna os nomes das colunas em minúsculas | | role | string | não | Role de conexão | | pageSize | number | não | Page size usado ao criar bancos | | retryConnectionInterval | number | não | Intervalo (ms) entre tentativas de reconexão | | isolation | Isolation | não | Nível de isolamento das transactions (padrão: READ COMMITTED) | | encoding | SupportedCharacterSet | não | Charset da conexão, ex.: 'UTF8', 'WIN1252', 'ISO8859_1', 'NONE' | | maxConnections | number | não | Somente FirebirdPool: máximo de conexões simultâneas (padrão: 10) |

Para alterar o isolamento, use as constantes do node-firebird:

import { ISOLATION_SERIALIZABLE } from "node-firebird";

const conexao = new FirebirdConnection({ ...config, isolation: ISOLATION_SERIALIZABLE });

Charset da conexão

Sem encoding, a conexão usa UTF-8 e o Firebird translitera os textos automaticamente. Para bases legadas (charset NONE ou WIN1252) em que a transliteração falha com caracteres acentuados, informe o charset diretamente:

const conexao = new FirebirdConnection({
  ...config,
  encoding: "WIN1252", // ou 'UTF8', 'ISO8859_1', 'NONE', ...
});

O campo é tipado com o SupportedCharacterSet do node-firebird, então o editor sugere os valores válidos.

Testabilidade

Consumidores podem depender da interface QueryExecutor (apenas queryExecute) em vez das classes concretas, facilitando mocks em testes. Também é possível injetar um FirebirdDriver alternativo no segundo parâmetro dos construtores — é assim que os testes da própria biblioteca funcionam, sem precisar de um servidor Firebird.

import { QueryExecutor } from "ps-conecta-firebird";

class RepositorioClientes {
  constructor(private readonly db: QueryExecutor) {}
}

Desenvolvimento

npm install       # instala dependências
npm run build     # compila o TypeScript para dist/
npm test          # roda os testes (vitest)

O CI (GitHub Actions) roda build e testes em cada push e pull request.

Publicação

npm version patch # ou minor/major — atualiza a versão
npm publish       # o build roda automaticamente (prepublishOnly)

Licença

ISC