<\> Casa do Dev
Notícias abrir
Ferramentas abrir
Vagas abrir
Aprender abrir
Comunidade abrir
Guia de Compras abrir

Como conectar Node.js ao PostgreSQL com pg: pool, .env e erros comuns

DA

8 min

Como conectar Node.js ao PostgreSQL com pg: pool, .env e erros comuns

Aprenda como conectar Node.js ao PostgreSQL com a lib pg: string de conexão, variáveis de ambiente, pool de conexões, tratamento de erros e quando partir para um ORM.

Neste artigo

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.

AspectoDetalhe
Driver usadopg (node-postgres), o cliente PostgreSQL padrão no ecossistema Node
Pré-requisitosNode.js LTS instalado e um servidor PostgreSQL acessível (local, Docker ou gerenciado)
DificuldadeIntermediário: assume noção de async/await e de SQL básico
CustoZero: pg, dotenv, Sequelize e TypeORM são open source
Tempo estimado20 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 dotenv

Esse 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_base

Com 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.

  • timeout na query: banco sobrecarregado ou connectionTimeoutMillis baixo demais.

  • too many connections: pool maior que o max_connections do 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ériopg (SQL puro)Sequelize / TypeORM
Curva de aprendizadoBaixa, é SQL mesmoMédia/alta, abstrações próprias
Controle da queryTotalParcial, queries geradas
MigrationsManual (ou ferramenta à parte)Nativo e versionado
Produtividade em CRUDBaixa, tudo na mãoAlta
Indicado paraAPIs enxutas, queries críticasDomí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.js

Minha 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, .env no .gitignore, nenhum segredo no repositório.

  • Um único Pool compartilhado pela aplicação, com max coerente com o limite do servidor.

  • Todas as queries parametrizadas com $1, $2, sem concatenação de string.

  • Transações usando pool.connect() com client.release() garantido em finally.

  • 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.

O que você achou deste artigo?

Responda a Pergunta do Dia Teste seu conhecimento e mantenha sua streak. Crie seu Dev Card público Perfil dev compartilhável em um único link.

Depois dessa formação...

Veja vagas em tecnologia →

Vagas relacionadas

Ver todas as vagas →
DA

Escrito por

Dagmar

Publicado em

Ver perfil do autor

COMPARTILHAR