Todos os artigos
Tecnologia19 de novembro de 2026

Como criar uma API REST com Node JS e banco PostgreSQL: do zero ao código funcional

Aprenda a construir uma API REST robusta usando Node.js e banco de dados PostgreSQL com foco em performance e organização de código. O guia traz um passo a passo prático para configurar rotas, conexões seguras e operações completas de CRUD.

Capa do artigo Como criar uma API REST com Node JS e banco PostgreSQL: do zero ao código funcional

Construir sistemas que respondem rápido e não caem na primeira oscilação de tráfego é o sonho de qualquer equipe de engenharia de software. Quando você decide criar uma API REST com Node JS e banco PostgreSQL, escolhe uma das combinações mais testadas e confiáveis do ecossistema de desenvolvimento web. O Node.js entrega velocidade com seu modelo não bloqueante orientado a eventos, enquanto o PostgreSQL garante consistência matemática aos dados, suportando regras de negócio complexas sem engasgar.

Muitos tutoriais na internet entregam códigos simplistas que funcionam apenas na máquina local. Quando a aplicação sobe para um servidor de produção, os problemas com conexões abertas acumuladas e falta de validações começam a aparecer. Neste guia, vamos montar um serviço backend organizado, desde a estrutura de pastas até a escrita de consultas seguras com pool de conexões, pensando na rotina de quem precisa entregar software comercial com prazo e qualidade.

---

Por que utilizar a combinação de Node.js e PostgreSQL?

A escolha de tecnologias para o backend não deve ser orientada por modismos de redes sociais, mas sim pelas características da carga de trabalho que a aplicação vai atender. O JavaScript no servidor reduziu o atrito no desenvolvimento ao permitir que o time use a mesma linguagem em todas as frentes da aplicação, mantendo o ecossistema coeso.

Aliar essa flexibilidade à robustez do PostgreSQL equilibra a agilidade de entrega com a segurança de dados estruturados. Em vez de inventar a roda, você utiliza ferramentas que gigantes da tecnologia sustentam há décadas em ambientes de missão crítica.

A velocidade do event loop em operações assíncronas

O Node.js brilha em aplicações que realizam muitas operações de entrada e saída (I/O), como consultas a banco de dados, leitura de arquivos e chamadas para serviços externos. Por padrão, enquanto uma consulta ao PostgreSQL está sendo processada no servidor do banco, o processo do Node.js não fica travado esperando a resposta.

Ele continua atendendo novas requisições de outros usuários. Isso permite que uma máquina modesta aguente centenas de conexões simultâneas por segundo, contanto que o código seja escrito de forma assíncrona com `async/await` e sem rotinas computacionais pesadas bloqueando a thread principal.

A solidez e confiabilidade do PostgreSQL para dados relacionais

O PostgreSQL é muito mais do que um simples banco relacional tradicional. Ele implementa o padrão ACID com rigor implacável, possui suporte nativo maduro a tipos JSON e JSONB, oferece índices parciais e recursos analíticos avançados.

Se o seu sistema processa pagamentos, emite notas fiscais ou gerencia estoques em que uma quantidade negativa quebra o fluxo financeiro, você precisa de um banco transacional confiável. Ele impede que falhas elétricas ou falhas no aplicativo corrompam tabelas inteiras.

---

Preparando o ambiente de desenvolvimento da API

Antes de abrir o editor de código, você precisa garantir que possui os utilitários fundamentais instalados na sua máquina. Precisamos da versão LTS mais recente do Node.js instalada e de uma instância acessível do PostgreSQL rodando localmente ou dentro de um contêiner Docker.

Para iniciar o projeto, crie uma pasta no terminal e rode os comandos básicos de inicialização do ecossistema Node:

mkdir api-node-postgres

cd api-node-postgres

npm init -y

Agora, instalamos os pacotes necessários para fazer o servidor web responder e comunicar com a base de dados:

npm install express pg dotenv

npm install -D nodemon

O `express` será o framework de roteamento HTTP, o pacote `pg` (conhecido como node-postgres) é o cliente oficial para falar diretamente com o banco relacional, e o `dotenv` cuida de puxar as credenciais do ambiente de forma segura. A dependência de desenvolvimento `nodemon` serve apenas para reiniciar a aplicação a cada alteração salva no código.

---

Estrutura de pastas pensada para crescimento sustentável

Projetos pequenos têm o péssimo hábito de concentrar centenas de linhas de código em um único arquivo chamado `index.js` ou `server.js`. Essa prática cria um pesadelo de manutenção logo nas primeiras semanas de vida do produto. Separar papéis facilita testes unitários e colaboração entre desenvolvedores.

Adote uma estrutura modular e direta, comum em projetos de empresas brasileiras:

* src/config/: abriga as configurações centrais, como a conexão com o banco de dados e leituras de variáveis de ambiente.

* src/controllers/: recebe as requisições HTTP, extrai parâmetros, valida entradas e envia as respostas com os códigos de status adequados.

* src/models/ ou src/repositories/: concentra a execução das instruções SQL e o contato direto com a base de dados.

* src/routes/: mapeia os endpoints (URLs) para os seus respectivos métodos nos controllers.

* src/server.js: arquivo raiz que apenas inicializa o servidor Express e escuta uma porta de rede.

Essa segregação simples garante que se você precisar mudar uma consulta SQL amanhã, não precisará mexer nas rotas ou na lógica de formatação de JSON da resposta HTTP.

---

Como criar uma API REST com Node JS e banco PostgreSQL na prática

Com as dependências prontas e as pastas criadas, iniciamos a configuração do banco. Crie um banco de dados no PostgreSQL chamado `loja_virtual` e uma tabela simples para testar:

CREATE TABLE produtos (

id SERIAL PRIMARY KEY,

nome VARCHAR(100) NOT NULL,

preco NUMERIC(10, 2) NOT NULL,

criado_em TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);

Configurando o Pool de conexões

Abrir e fechar conexões com o PostgreSQL a cada clique de usuário consome muita memória e processador do servidor. Por isso, usamos o conceito de Connection Pool. Crie o arquivo `src/config/database.js`:

const { Pool } = require('pg');

require('dotenv').config();

const pool = new Pool({

user: process.env.DB_USER,

host: process.env.DB_HOST,

database: process.env.DB_NAME,

password: process.env.DB_PASSWORD,

port: process.env.DB_PORT,

max: 10,

idleTimeoutMillis: 30000,

});

module.exports = {

query: (text, params) => pool.query(text, params),

};

Esse módulo gerencia uma fila de conexões reutilizáveis, melhorando o rendimento da máquina e evitando esgotar os recursos do banco quando houver picos de acessos.

Construindo as operações de CRUD completas

No arquivo `src/controllers/produtoController.js`, implementamos a leitura e a escrita usando async/await:

const db = require('../config/database');

exports.listarProdutos = async (req, res) => {

try {

const resultado = await db.query('SELECT * FROM produtos ORDER BY id ASC');

return res.status(200).json(resultado.rows);

} catch (erro) {

return res.status(500).json({ erro: 'Falha ao buscar produtos no banco' });

}

};

exports.criarProduto = async (req, res) => {

const { nome, preco } = req.body;

if (!nome || !preco) {

return res.status(400).json({ erro: 'Nome e preco sao obrigatorios' });

}

try {

const textoQuery = 'INSERT INTO produtos (nome, preco) VALUES ($1, $2) RETURNING *';

const valores = [nome, preco];

const resultado = await db.query(textoQuery, valores);

return res.status(201).json(resultado.rows[0]);

} catch (erro) {

return res.status(500).json({ erro: 'Falha ao inserir registro' });

}

};

Definindo rotas e subindo a API REST

Agora conecte os controllers ao roteador criando o arquivo `src/routes/produtosRoutes.js`:

const express = require('express');

const router = express.Router();

const controller = require('../controllers/produtoController');

router.get('/produtos', controller.listarProdutos);

router.post('/produtos', controller.criarProduto);

module.exports = router;

Por fim, inicialize o Express no `src/server.js`:

const express = require('express');

require('dotenv').config();

const rotasProdutos = require('./routes/produtosRoutes');

const app = express();

app.use(express.json());

app.use('/api', rotasProdutos);

const PORTA = process.env.PORT || 3000;

app.listen(PORTA, () => {

console.log(`Servidor rodando na porta ${PORTA}`);

});

Ao rodar `npm run dev` com o nodemon configurado no seu `package.json`, você pode disparar chamadas HTTP POST e GET para `http://localhost:3000/api/produtos` utilizando o Postman, Insomnia ou curl.

---

Boas práticas de segurança e tratamento de erros no backend

A diferença entre um código amador e um projeto profissional está na forma como o sistema lida com imprevistos e protege os dados dos usuários. Criar endpoints funcionais é fácil; mantê-los seguros e estáveis exige disciplina.

Prevenção contra SQL Injection com queries parametrizadas

Nunca concatene variáveis de entrada diretamente em strings SQL. Fazer algo como `db.query('SELECT * FROM produtos WHERE nome = ' + req.body.nome)` abre as portas para ataques que podem apagar suas tabelas ou roubar dados confidenciais.

Utilize sempre os marcadores de posição do PostgreSQL (`$1`, `$2`, `$3`). A biblioteca `node-postgres` faz a sanitização e o escape correto dos caracteres antes de enviar o comando ao interpretador do banco de dados, neutralizando qualquer tentativa de injeção maliciosa.

Variáveis de ambiente e segredos protegidos

Credenciais de bancos de produção jamais devem ser colocadas com valor fixo no repositório Git. Crie um arquivo `.env` para abrigar suas senhas e adicione esse arquivo imediatamente ao seu `.gitignore`.

Além disso, forneça um `.env.example` preenchido apenas com os nomes das chaves para que outros desenvolvedores da equipe saibam exatamente quais parâmetros de ambiente precisam preencher quando clonarem o projeto.

---

Perguntas frequentes

Vale a pena usar ORMs como Prisma em vez do driver pg puro?

Depende do escopo do projeto. ORMs agilizam o início do desenvolvimento e entregam tipagem forte se você usar TypeScript. Contudo, em consultas analíticas complexas ou sistemas que exigem altíssima taxa de transferências por segundo, o driver puro com SQL nativo entrega melhor desempenho e controle total sobre cada query executada.

Como funciona o gerenciamento de transações no PostgreSQL com Node?

Para agrupar várias ações que precisam ser executadas com sucesso ou todas revertidas, você requisita uma conexão exclusiva do pool com `const client = await pool.connect()`. Em seguida, executa `await client.query('BEGIN')`, roda as instruções necessárias e confirma com `COMMIT` dentro de um bloco try. No bloco catch, executa `ROLLBACK` e finaliza liberando a conexão com `client.release()`.

É melhor rodar o PostgreSQL localmente via instalador ou Docker?

O Docker é a opção mais recomendada. Com uma linha de comando ou um arquivo `docker-compose.yml`, você sobe o banco de dados em segundos, padroniza a versão exata entre todos os membros do time e evita poluir o seu sistema operacional com serviços rodando em segundo plano.

---

Aprender como criar uma API REST com Node JS e banco PostgreSQL é um investimento certeiro para sua carreira de desenvolvedor. Você não fica dependente de camadas mágicas de abstração e passa a entender exatamente como os dados transitam entre o protocolo HTTP e o disco rígido do servidor. Domine esses fundamentos, estruture bem as suas camadas de software e a sua aplicação estará pronta para escalar com confiança.