Neste artigo
- O que você precisa para conectar Node.js ao PostgreSQL?
- Como configurar a string de conexão e as variáveis de ambiente
- Pool de conexões com pg: configuração e consultas assíncronas
- Tratamento de erros e reconexão automática
- Quando trocar pg por um ORM como Sequelize ou TypeORM
- Checklist final antes de ir para produção
- Como configurar um pool de conexões pg no Node.js?
- Onde guardar as credenciais do banco com segurança?
- Preciso fechar a conexão depois de cada query?
- pg, Sequelize ou TypeORM: qual escolher?
Conectar Node.js ao PostgreSQL se resume a instalar o driver pg (node-postgres), montar uma string de conexão com host, porta, banco, usuário e senha, e executar queries por meio de um pool de conexões. Com meia dúzia de linhas você já faz um SELECT funcionando; o resto do trabalho é configurar direito para não vazar conexão em produção.
Já vi muito projeto ir pro ar com new Client() por request e senha hardcoded no código. Funciona na máquina local e quebra no primeiro pico de acesso. Este guia existe pra você pular essa fase.
| Aspecto | Detalhe |
|---|---|
| Driver usado | pg (node-postgres), o cliente PostgreSQL padrão no ecossistema Node |
| Pré-requisitos | Node.js LTS instalado e um servidor PostgreSQL acessível (local, Docker ou gerenciado) |
| Dificuldade | Intermediário: assume noção de async/await e de SQL básico |
| Custo | Zero: pg, dotenv, Sequelize e TypeORM são open source |
| Tempo estimado | 20 a 40 minutos para ter conexão estável com pool e .env |
O que você precisa para conectar Node.js ao PostgreSQL?
Você precisa de três coisas: Node.js (versão LTS) instalado, um PostgreSQL rodando e acessível, e o pacote pg instalado via npm. A conexão em si é feita passando ao driver uma string de conexão no formato postgresql://usuario:senha@host:porta/banco ou um objeto de configuração equivalente.
Se o PostgreSQL ainda não existe na sua máquina, o caminho mais rápido é subir um container (caso use Docker) ou instalar o pacote oficial do seu sistema. Anote usuário, senha, porta e nome do banco: são os quatro dados que você vai usar em todas as etapas seguintes.
npm install pg dotenvEsse comando instala o driver e o dotenv, que usaremos para carregar credenciais de um arquivo .env sem colocar senha no código.
Curso analista ciberseguranca junior cisco
Como configurar a string de conexão e as variáveis de ambiente
A forma recomendada de guardar a string de conexão é em variáveis de ambiente, carregadas com dotenv de um arquivo .env que fica fora do versionamento. Senha de banco commitada no Git é um dos vazamentos mais comuns e mais evitáveis que existem: repositório público com credencial é encontrado por bots em minutos.
# .env
DB_HOST=localhost
DB_PORT=5432
DB_USER=meu_usuario
DB_PASSWORD=minha_senha
DB_NAME=minha_baseCom as variáveis definidas, crie um módulo central de conexão. Centralizar importa: qualquer ajuste de configuração passa a ser em um lugar só.
// db.js
require('dotenv').config();
const { Pool } = require('pg');
const pool = new Pool({
host: process.env.DB_HOST,
port: Number(process.env.DB_PORT),
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
});
module.exports = pool;Alternativamente, o pg aceita connectionString única. E lembre do essencial: adicione .env ao .gitignore antes do primeiro commit.
Atenção:em produção (PaaS, containers), prefira variáveis de ambiente injetadas pela plataforma em vez de arquivo .env. É o padrão esperado por serviços como Heroku, Railway e afins.
Cursos google ciee gratuitos certificado
Pool de conexões com pg: configuração e consultas assíncronas
Um pool de conexões mantém um conjunto de conexões abertas e reutilizáveis, em vez de abrir e fechar uma conexão TCP a cada query. No pg, você cria um Pool uma vez na aplicação e chama pool.query() nas rotas; o driver pega um client livre, executa e devolve ao pool automaticamente.
const pool = require('./db');
async function listarUsuarios() {
const resultado = await pool.query(
'SELECT id, nome, email FROM usuarios WHERE ativo = $1',
[true]
);
return resultado.rows;
}Três pontos que salvam produção aqui. Primeiro: sempre parâmetros posicionais ($1, $2), nunca concatenação de string, para eliminar SQL injection. Segundo: ajuste max (padrão 10) conforme o limite de conexões do seu PostgreSQL; pool maior que o suportado pelo banco derruba tudo junto. Terceiro: defina idleTimeoutMillis para reciclar conexões paradas e connectionTimeoutMillis para falhar rápido quando o banco não responde.
Se precisar de transação, pegue um client dedicado com const client = await pool.connect() e, ao final, chame client.release() dentro de um finally. Esquecer o release é a causa número um de pool esgotado e aplicação travada esperando conexão livre. Quando sua camada de dados começar a alimentar relatórios e dashboards para o time de negócio, vale olhar também o plano de carreira de analista de dados com Power BI para entender como esses dados serão consumidos do outro lado.
Tratamento de erros e reconexão automática
O pool do pg trata reconexão de forma transparente na maioria dos casos: se uma conexão cai, ela é descartada e outra é criada na próxima query. O que você precisa fazer é ouvir o evento error do pool para logar falhas em clients ociosos e envolver suas queries em try/catch para responder erro HTTP decente em vez de derrubar o processo.
Databricks cursos gratuitos portugues
pool.on('error', (err) => {
console.error('Erro inesperado em client ocioso do pool', err);
});Erros que você vai encontrar cedo ou tarde:
ECONNREFUSED: PostgreSQL fora do ar ou host/porta errados. Confira se o serviço está de pé.Erro de autenticação (
password authentication failed): usuário ou senha incorretos no .env, ou pg_hba.conf bloqueando o host.timeoutna query: banco sobrecarregado ouconnectionTimeoutMillisbaixo demais.too many connections: pool maior que omax_connectionsdo servidor.
Dica:para retry em falhas transitórias (deploy do banco, restart), enfileire a query e tente de novo com espera crescente (backoff exponencial) em vez de retry imediato em loop, que só aumenta a carga num banco já sofrendo.
Quando trocar pg por um ORM como Sequelize ou TypeORM
Use o pg puro quando o projeto é pequeno, as queries são críticas em performance ou você quer controle total do SQL. Parta para um ORM como Sequelize ou TypeORM quando o domínio cresce, o time precisa de produtividade com CRUDs repetitivos e migrations versionadas passam a ser requisito, e não luxo.
| Critério | pg (SQL puro) | Sequelize / TypeORM |
|---|---|---|
| Curva de aprendizado | Baixa, é SQL mesmo | Média/alta, abstrações próprias |
| Controle da query | Total | Parcial, queries geradas |
| Migrations | Manual (ou ferramenta à parte) | Nativo e versionado |
| Produtividade em CRUD | Baixa, tudo na mão | Alta |
| Indicado para | APIs enxutas, queries críticas | Domínios grandes, times maiores |
No TypeORM, depois de configurar o DataSource (que usa o pg por baixo), as migrations rodam pela CLI:
Curso gratuito analise de dados dashboards google looker studio senai
npx typeorm migration:run -d src/data-source.jsMinha recomendação direta: comece com pg. Você aprende o que o ORM esconde de você, e o dia que migrar para TypeORM vai entender exatamente o que está acontecendo embaixo do capô. ORM sem saber SQL é pedir pra debugar query gerada às 2h da manhã sem saber por onde começar.
E se o seu objetivo é se aprofundar em dados de forma mais ampla (bancos, pipelines, análise), os cursos gratuitos do Google de programação, JavaScript e dados são um bom complemento ao que você praticou aqui.
Checklist final antes de ir para produção
Credenciais em variáveis de ambiente,
.envno.gitignore, nenhum segredo no repositório.Um único
Poolcompartilhado pela aplicação, commaxcoerente com o limite do servidor.Todas as queries parametrizadas com
$1,$2, sem concatenação de string.Transações usando
pool.connect()comclient.release()garantido emfinally.Listener de
pool.on('error')e try/catch em toda rota que toca o banco.Teste de falha real: derrube o PostgreSQL local e veja sua API responder erro tratado, e não crashar.
Documentação para aprofundar: documentação oficial do node-postgres (pg) e a documentação oficial do PostgreSQL.
Perguntas frequentes
Como configurar um pool de conexões pg no Node.js?
Crie uma instância única de Pool com as credenciais (de preferência via variáveis de ambiente) e exporte esse módulo. Use pool.query() nas rotas e ajuste max, idleTimeoutMillis e connectionTimeoutMillis conforme a capacidade do seu PostgreSQL.
Curso gratuito microsoft analise de dados power bi certificado
Onde guardar as credenciais do banco com segurança?
Em variáveis de ambiente carregadas com dotenv em desenvolvimento, e injetadas pela plataforma em produção. O arquivo .env deve estar no .gitignore desde o primeiro commit, e nenhuma senha deve aparecer no código versionado.
Preciso fechar a conexão depois de cada query?
Não, quando você usa o pool: o pool.query() libera o client automaticamente ao terminar. Você só precisa chamar client.release() manualmente quando pega um client dedicado com pool.connect(), como em transações.
pg, Sequelize ou TypeORM: qual escolher?
Para projetos pequenos ou queries críticas de performance, o pg com SQL puro dá controle total e menos abstração. Para domínios grandes com muitos CRUDs e necessidade de migrations versionadas, Sequelize ou TypeORM aumentam a produtividade do time.