Armazenar os dados da aplicação num local fiável é uma daquelas coisas que tem de ser resolvida logo no início de qualquer projeto Node.js a sério. O PostgreSQL é uma escolha comum para isso: já existe há imenso tempo, funciona bem com praticamente qualquer configuração do Node.js e não traz surpresas desagradáveis mais tarde.

O Node.js comunica com o Postgres através de um pacote chamado pg. Ele trata da ligação por ti, por isso tudo o que tens de fazer é escrever o teu SQL, executá-lo e receber os resultados como objetos JavaScript normais, para usares como quiseres.

Neste blog, vou explicar por que é que o Postgres combina bem com o Node.js, mostrar como é que os dois se ligam na prática e, depois, criar uma pequena aplicação para acompanhar a leitura de livros, para juntar tudo isto. Por fim, vou implementar tudo num servidor Cloudways ativo.

Por que é que o PostgreSQL funciona bem com o Node.js

Sinceramente, o que mais gosto no Postgres é o facto de ser tão fiável que chega a ser aborrecido. Já é utilizado em produção a sério há décadas. As consultas continuam rápidas mesmo quando se tornam complicadas, as relações entre as tabelas funcionam exatamente como esperas e quase nunca me aconteceu ele simplesmente… avariar.

No que diz respeito ao Node, o pacote pg é bem mantido e é usado praticamente em todo o lado. Instala-o, introduz as tuas credenciais e começa a executar consultas. É tão simples quanto isso.

O Postgres também tem uma funcionalidade útil que te permite inserir JSON diretamente numa coluna, caso alguns dos teus dados não se encaixem bem numa estrutura de tabela normal. Assim, tens a flexibilidade típica do NoSQL quando precisares, sem teres de mudar de base de dados.

O Stack também é popular, o que é mais importante do que as pessoas pensam. Quando, inevitavelmente, te deparares com algum caso extremo e estranho às 23h, tens uma década de tópicos do Stack Overflow à tua espera.

Como funciona, na prática, ligar o Node.js ao PostgreSQL

Em termos gerais, isto é bastante simples. A tua aplicação Node.js usa o pacote pg para abrir uma ligação ao Postgres, envia algumas consultas SQL e recebe as linhas de resposta. É basicamente isso.

A única coisa com que vale a pena ter cuidado é onde guardas as tuas credenciais. Codificar diretamente no código-fonte o host da base de dados, o nome de utilizador e a palavra-passe é um mau hábito, especialmente porque o mesmo código tem de funcionar tanto localmente como em produção com valores totalmente diferentes. As variáveis de ambiente resolvem este problema. Guardas as credenciais num ficheiro .env localmente e configuras-as separadamente no teu servidor de produção.

Outra coisa que o pg faz nos bastidores é a gestão de um conjunto de ligações. Em vez de abrir uma nova ligação à base de dados para cada pedido, mantém um pequeno conjunto de ligações e vai atribuindo-as conforme necessário. Não é algo em que tenhas de pensar muito, mas poupa-te muitas dores de cabeça quando a tua aplicação começar mesmo a receber tráfego a sério.

Como criar um gestor de livros com Node.js e PostgreSQL

Para te mostrar como isto funciona na prática, vou criar um mini-projeto: um pequeno gestor de livros onde posso adicionar livros a uma lista, marcá-los como lidos e apagar aqueles de que já não preciso.

O que vou usar

• Node.js
• PostgreSQL 17 (binário autónomo)
• VS Code
• Express, EJS e o cliente pg para o Postgres

Passo 1: Configurar o PostgreSQL localmente

Antes de escrever qualquer código, preciso de ter o Postgres instalado no meu computador.

Estou a trabalhar no portátil do escritório, que tem restrições de TI, por isso vou descarregar a versão binária independente em vez de executar um instalador. Vou ao site enterprisedb.com/download-postgresql-binaries, escolho a versão 17 para Windows x86-64 e faço o download.

Assim que estiver descarregado, vou descompactá-lo na minha pasta «Downloads».

Configurar o Prompt de Comando para o ficheiro binário do PostgreSQL

Depois, vou abrir o Prompt de Comandos e definir o diretório bin do Postgres como diretório de trabalho, para poder executar os comandos do Postgres:

define PATH=%PATH%;C:\Users\abdulrehman\Downloads\postgresql-17.10-2-windows-x64-binaries\pgsql\bin

Para ter a certeza de que está mesmo a funcionar, vou executar:

postgres --version

Se aparecer um número de versão, posso continuar.

A inicializar o diretório de dados

O Postgres precisa de uma pasta algures para guardar os seus dados. Vou criar uma e inicializá-la:

mkdir C:\Users\abdulrehman\pgdata
initdb -D C:\Users\abdulrehman\pgdata -U postgres

A parte -U postgres define «postgres» como o nome de utilizador de administrador. No Windows, o initdb cria este utilizador sem palavra-passe, por isso vou definir uma manualmente no próximo passo.

Iniciar o servidor PostgreSQL

Agora vou mesmo ligar o servidor:

pg_ctl -D C:\Users\abdulrehman\pgdata -l C:\Users\abdulrehman\pgdata\logfile start

Isto faz com que o programa fique a funcionar em segundo plano, por isso não preciso de manter um terminal aberto para isso.

Definir uma palavra-passe para o utilizador «postgres»

Com o servidor a funcionar, vou abrir o shell do Postgres e definir uma palavra-passe para o utilizador «postgres»:

psql -U postgres

Assim que estiver no shell, vou executar:

ALTER USER postgres WITH PASSWORD 'postgres';

Depois vou escrever \q para sair.

Vou usar «postgres» como palavra-passe, já que isto é só para desenvolvimento local.

Criar uma base de dados para o projeto

Por último, vou criar uma base de dados vazia para este projeto:

createdb -U postgres booktracker inform

Depois, para verificar se foi criada, vou listar todas as bases de dados:

psql -U postgres -l

Se vir o «booktracker» na lista, significa que o Postgres está configurado e pronto a ser utilizado pela aplicação.

Passo 2: Configurar o projeto Node.js

Agora, quanto à aplicação. Antes de poder fazer alguma coisa, preciso de ter o Node.js instalado no meu computador.

Tal como com o Postgres, vou descarregar a versão binária independente do Node.js do site nodejs.org, em vez de executar um instalador, e descompactá-la na minha pasta «Downloads».

Abrir a pasta do projeto no Prompt de Comandos

Vou criar uma pasta para este projeto no meu ambiente de trabalho e vou chamá-la simplesmente de node-postgres-book-tracker.

Depois, vou abrir o Prompt de Comandos e ir até à pasta do meu projeto:

cd C:\Users\abdulrehman\Desktop\node-postgres-book-tracker

Configurar o CMD para o ficheiro binário do Node

Como o meu Prompt de Comando não sabe onde fica a pasta do Node no meu computador, vou ter de lhe indicar manualmente. Para isso, vou executar este comando:

define PATH=%PATH%;C:\Users\abdulrehman\Downloads\node-v24.18.0-win-x64\node-v24.18.0-win-x64

Para verificar se está tudo configurado como deve ser, vou executar:

node -v
npm -v

Ambos os comandos estão a mostrar números de versão, por isso já posso seguir em frente.

Criar o projeto Node.js

Primeiro, vou criar um projeto simples em Node.js usando este comando:

npm init -y

Depois, vou instalar tudo o que este projeto realmente precisa: o Express para gerir o encaminhamento, o EJS para renderizar HTML, o pacote oficial do pg para ligar ao Postgres e o dotenv para gerir as minhas credenciais localmente.

npm install express ejs pg dotenv

Passo 3: Criar a aplicação «Book Tracker»

Agora vou abrir o meu projeto no VS Code. Para isso, vou clicar em Ficheiro > Abrir pasta e selecionar a minha pasta node-postgres-book-tracker.

Pronto, já tenho o meu projeto aberto no VS Code, por isso está na hora de começar mesmo a criar a aplicação.

Criar a tabela «books» localmente

Primeiro, preciso de uma tabela no Postgres para guardar os livros. Para isso, de volta ao Prompt de Comandos, vou abrir um shell interativo do Postgres:

psql -U postgres -d booktracker

Depois, vou colar o código SQL para criar a tabela:

CREATE TABLE livros (
  id SERIAL CHAVE PRIMÁRIA,
  título TEXTO NÃO NULO,
  autor TEXTO NÃO NULO,
  is_read BOOLEANO POR PREFUNÇÃO FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP informação
  );

Depois vou escrever \q para sair do shell.

A tabela tem campos de ID com autoincremento, título e autor, um valor booleano que indica se já li o livro e um registo de data e hora da data em que o adicionei.

Proteger as credenciais da base de dados

A seguir, quero guardar as minhas credenciais do Postgres num local seguro do projeto. Para isso, na raiz da pasta do meu projeto, vou criar um novo ficheiro chamado .env e colar o seguinte:

DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=booktracker

Estes são os valores locais que correspondem ao que configurei no Passo 1. Vou substituí-los pelos valores reais de produção mais tarde, quando fizer a implementação.

Agora, como estas são as minhas credenciais reais, não as quero no meu repositório público do GitHub. Para evitar isso, vou criar mais um ficheiro na raiz do meu projeto chamado .gitignore e colar o seguinte:

node_modules
.env

Isto diz ao Git para ignorar ambos sempre que eu fizer um push do meu projeto. O «node_modules» porque são só pacotes descarregados, não há motivo para os enviar. E o «.env» porque contém as minhas credenciais reais, por isso, ao deixá-lo de fora, elas nunca acabam por ficar num sítio público.

Configurar a ligação à base de dados

A seguir, preciso de algo que ligue mesmo a minha aplicação ao Postgres. Para isso, vou criar uma pasta chamada «db» na raiz do projeto e, dentro dela, um ficheiro chamado «index.js».

require('dotenv').config();
  const { Pool } = require('pg');
const pool = new Pool({
  utilizador: process.env.DB_USER,
  palavra-passe: process.env.DB_PASSWORD,
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  base de dados: process.env.DB_NAME,
  });
module.exports = pool;

Não há nada de especial aqui. É só um conjunto de ligações que se configura uma vez, para que qualquer ficheiro do projeto possa importá-lo e começar a fazer consultas.

Montar o servidor

É aqui que vou construir a aplicação propriamente dita: ela vai buscar os livros do Postgres, apresenta-os e trata da adição, atualização e eliminação.

Vou criar um ficheiro chamado server.js na raiz do meu projeto e colar isto lá dentro:

const express = require('express');
  const path = require('path');
  const pool = require('./db');
const app = express();
  const PORT = process.env.PORT || 3000;
app.set('view engine', 'ejs');
  app.set('views', path.join(__dirname, 'views'));
  app.use(express.static(path.join(__dirname, 'public')));
  app.use(express.urlencoded({ extended: true }));
app.get('/', async (req, res) => {
  try {
  const result = await pool.query('SELECT * FROM books ORDER BY created_at DESC');
  res.render('index', { books: result.rows });
  } catch (err) {
  console.error(err);
  res.status(500).send('Houve um problema ao carregar os livros.');
  }
  });
app.post('/add', async (req, res) => {
  const { title, author } = req.body;
  try {
  await pool.query('INSERT INTO books (title, author) VALUES ($1, $2)', [title, author]);
  res.redirect('/');
  } catch (err) {
  console.error(err);
  res.status(500).send('Houve um problema ao adicionar o livro.');
  }
  });
app.post('/toggle/:id', async (req, res) => {
  try {
  await pool.query('UPDATE books SET is_read = NOT is_read WHERE id = $1', [req.params.id]);
  res.redirect('/');
  } catch (err) {
  console.error(err);
  res.status(500).send('Houve um problema ao atualizar o livro.');
  }
  });
app.post('/delete/:id', async (req, res) => {
  try {
  await pool.query('DELETE FROM books WHERE id = $1', [req.params.id]);
  res.redirect('/');
  } catch (err) {
  console.error(err);
  res.status(500).send('Houve um problema ao apagar o livro.');
  }
  });
app.listen(PORT, () => {
  console.log(Servidor a funcionar na porta ${PORT});
  });

Então, as rotas tratam de tudo o que a aplicação precisa: listar os livros, adicionar um, alterar o estado de leitura e eliminar. Coloquei cada consulta dentro de um try-catch para que nada faça a aplicação toda falhar se uma consulta der errado.

Esse ficheiro server.js aponta para um modelo chamado «index» que ainda não existe, por isso, a seguir, vou criar a página de que ele precisa.

Criar a interface do utilizador

Vou criar uma pasta chamada «views» na raiz do meu projeto e, dentro dela, um ficheiro chamado «index.ejs». Vou colar isto lá dentro:

E, para terminar esta etapa, vou adicionar mais um ficheiro: uma pasta «public» com um ficheiro «style.css» lá dentro. Vou colar isto aqui:

* {
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
  fundo: linear-gradient(135deg, #4f46e5, #7c3aed);
  margin: 0;
  min-height: 100vh;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 20px;
}

main {
  largura: 100%;
  max-width: 600px;
}

.card {
  fundo: #ffffff;
  border-radius: 12px;
  padding: 40px;
  box-shadow: 0 20px 60px rgba(0, 0, 0, 0,2);
}

h1 {
  margin-top: 0;
  cor: #1f2937;
}

.add-form {
  display: flex;
  gap: 8px;
  margin: 20px 0;
}

.add-form input {
  flex: 1;
  padding: 10px 12px;
  border: 1px solid #d1d5db;
  border-radius: 6px;
  tamanho da fonte: 14px;
}

.add-form button {
  fundo: #4f46e5;
  cor: #ffffff;
  border: none;
  padding: 10px 18px;
  border-radius: 6px;
  cursor: ponteiro;
  tamanho da fonte: 14px;
}

.book-list {
  list-style: none;
  padding: 0;
  margin: 0;
}

.book-list li {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 14px;
  fundo: #f9fafb;
  border-radius: 8px;
  margin-bottom: 10px;
}

.book-list li.read {
  opacidade: 0,6;
  text-decoration: line-through;
}

.book-info {
  display: flex;
  flex-direction: coluna;
}

.book-info span {
  cor: #6b7280;
  tamanho da fonte: 13px;
}

.actions {
  display: flex;
  gap: 6px;
}

.botão de ações {
  padding: 6px 12px;
  border: none;
  border-radius: 5px;
  cursor: ponteiro;
  tamanho da fonte: 12px;
  fundo: #e5e7eb;
}

.actions .delete {
  fundo: #fee2e2;
  cor: #b91c1c;
}

A testar o que criámos

Está na hora de testar isto mesmo. Vou adicionar um script de arranque ao meu package.json para não ter de ficar sempre a escrever o comando completo do node:

"scripts": {
  "start": "node server.js",
  "test": "echo "Erro: não foi especificado nenhum teste" && exit 1"
  }

Depois, volto ao Prompt de Comando e executo:

npm start

E vou abrir http://localhost:3000 no navegador. Devo ver o «book tracker» com uma lista vazia. Vou adicionar um livro, clicar em «Ler» para o marcar como lido e, depois, clicar em «Apagar» para o remover.

Como está tudo a correr exatamente como eu quero, a ligação está a funcionar bem. Os dados estão a entrar no Postgres e a sair de lá para o HTML que este pequeno servidor Express está a gerar.

Passo 4: Enviar o projeto para o GitHub

Antes de implementar o meu projeto Node.js/PostgreSQL no Cloudways, quero primeiro fazer o push para o GitHub.

Vou dar uma vista de olhos no GitHub e criar um novo repositório chamado node-postgres-book-tracker.

Depois, de volta ao Prompt de Comando, vou executar estes comandos um de cada vez para carregar o meu projeto:

git init
git add .
git commit -m "Primeiro commit"
git branch -M main
git remote add origin https://github.com/abdulrehman293/node-postgres-book-tracker
git push -u origin main

Vou voltar ao repositório e atualizar a página, e sim, está tudo lá, tirando o ficheiro .env e o node_modules, que é exatamente como deve ser.

Passo 5: Implementação no Cloudways

Neste momento, o meu projeto está a funcionar na configuração local e também já foi enviado para o GitHub. Agora vou transferi-lo do ambiente local para um servidor ativo. Para isso, vou usar a hospedagem gerida Node.js da Cloudways, que já vem com uma base de dados PostgreSQL incluída, por isso não preciso de configurar nenhum serviço de base de dados externo.

No painel do Cloudways, vou clicar em «Node.js» no menu do lado esquerdo e, depois, clico em «Lançar agora».

A partir daqui, vou escolher um plano. Este projeto não precisa de muitos recursos, por isso o plano Starter é suficiente.

A seguir, no ecrã «Implementar a tua aplicação web Node.js», vou clicar em «Ligar via Git». Assim que o meu Git estiver ligado, vou selecionar o meu repositório «node-postgres-book-tracker» e continuar.

Passo 6: Configurar e colocar em funcionamento

Agora, vou indicar à Cloudways como executar o projeto. Para isso, vou definir a «Predefinição do Framework» para «Express». E, quanto à «Versão do Node», vou escolher o Node 24 (LTS). Quanto ao «Diretório Raiz», vou deixar a configuração por predefinição.

A seguir, vou clicar em «Alterar» na secção «Definições de compilação e saída» para a expandir, depois vou definir o «Gestor de pacotes» como «npm» e o «Ficheiro de entrada» como «server.js».

Agora, como o meu ficheiro .env nunca foi colocado no GitHub de propósito, preciso de voltar a adicionar manualmente os valores da base de dados aqui. Mas o problema é que a base de dados do Cloudways só vai ser criada depois de a própria aplicação estar criada. Por isso, nesta altura, ainda não tenho os valores reais.

Para contornar isto, vou fazer a implementação primeiro com valores provisórios e, depois, volto para os atualizar assim que a aplicação estiver a funcionar e as credenciais reais da base de dados estiverem disponíveis.

Vou a «Variáveis de ambiente» e clico em «Adicionar». Isso abre uma janela modal onde posso adicionar as minhas variáveis uma a uma.

Vou adicionar os cinco, usando espaços reservados por enquanto:

• DB_USER — define como marcador de lugar
• DB_PASSWORD — define como «placeholder»
• DB_HOST — define-se como localhost
• DB_PORT — define para 5432
• DB_NAME — define-se como um marcador de lugar

Assim que os cinco estiverem introduzidos, vou clicar em «Guardar» e, depois, em «Implementar agora».

Assim que clicar em «Deploy Now», o Cloudways vai começar a buscar o código diretamente do GitHub, instalar as dependências e iniciar a aplicação usando o ficheiro de entrada que eu indiquei.

Mas, depois de a implementação estar concluída, a própria aplicação vai arrancar sem problemas, mas quaisquer consultas à base de dados vão falhar por enquanto, o que é normal, já que as credenciais são placeholders.

Assim que a implementação estiver concluída, vou abrir o separador «Base de dados» e copiar o nome da base de dados, o nome de utilizador e a palavra-passe gerados automaticamente para esta aplicação.

Depois, vou voltar às Variáveis de Ambiente e atualizar o DB_USER, o DB_PASSWORD e o DB_NAME com os valores reais.

Por fim, o que vou fazer é uma reimplantação manual.

Passo 7: Criar a tabela «Books» no Cloudways

Nesta altura, a aplicação já está implementada e as credenciais da base de dados estão configuradas, mas a própria base de dados de produção ainda está completamente vazia. Ainda não tem a tabela «books», por isso, se abrires a URL ativa agora, vai dar erro ao tentar recuperar livros que não existem.

Para resolver isto, vou voltar à secção «Base de dados» no Cloudways e clicar em «Lançar Gestor de Bases de Dados».

Isto abre um cliente Postgres no navegador.

No pequeno painel à esquerda, vou clicar em «Comando SQL» e colar a mesma instrução CREATE TABLE que executei localmente:

CREATE TABLE livros (
  id CHAVE PRIMÁRIA SERIAL,
  título TEXTO NÃO NULO,
  autor TEXTO NÃO NULO,
  is_read BOOLEANO POR PREFUNÇÃO FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  );

Vou clicar em «Executar» e a tabela vai ser criada na base de dados de produção.

O momento da verdade

Agora, vou abrir o URL temporário do Cloudways para a minha aplicação.

O gestor de livros deve carregar vazio, tal como acontecia localmente. Vou adicionar um livro, marcá-lo como lido e, depois, apagá-lo.

Então, está tudo a funcionar na perfeição. Os dados estão a ser guardados na base de dados Postgres gerida pela Cloudways. Qualquer livro que eu adicionar a partir de agora fica guardado enquanto a aplicação estiver a funcionar.

Conclusão

E pronto. O Postgres está configurado localmente, criámos uma pequena aplicação para acompanhar livros e implementámos tudo num servidor ativo.

O projeto final está no meu GitHub, caso queiras cloná-lo e experimentar o código por ti próprio.

E se estás a pensar alojar uma aplicação Node.js tua algures, vale a pena saberes que o nosso Alojamento Node.js Gerido já vem com o PostgreSQL incluído de fábrica. Assim, podes passar diretamente do teu repositório Git para uma versão ativa, sem precisares de configurar primeiro um serviço de base de dados externo.

Abdul Rehman

O Abdul é um profissional de marketing experiente em tecnologia, movido a café e criativo, que adora manter-se a par das últimas actualizações de software e gadgets tecnológicos. É também um escritor técnico competente que consegue explicar conceitos complexos de forma simples para um público alargado. Abdul gosta de partilhar os seus conhecimentos sobre a indústria da nuvem através de manuais de utilizador, documentação e publicações em blogues.

Get Connected on: Twitter Community Forum