Noções Básicas de Banco de Dados

8 exemplos para você começar com bancos de dados para backends Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

npm install pg
npm install -D typescript@5.6 tsx @types/pg

Para ajuste de pool e trade-offs de ORM, veja node-postgres (pg) e Prisma.

Exemplos Básicos

1. SQL vs Documento - Quando Escolher Cada Um

• A maioria das APIs B2B usa Postgres por padrão com pg ou Drizzle/Prisma
• Armazenamentos de documentos se encaixam em blobs de catálogo, logs de eventos e rápida mudança de esquema
• Híbrido é comum: Postgres para dinheiro, Redis para cache, S3 para arquivos

Relacionado: Driver MongoDB - padrões de documento

2. String de Conexão Orientada por Ambiente

// src/config.ts
import { z } from "zod";
 
const env = z.object({
  DATABASE_URL: z.string().url(),
}).parse(process.env);
 
export const databaseUrl = env.DATABASE_URL;

• Nunca codifique credenciais diretamente no código fonte
• Formato DATABASE_URL: postgres://user:pass@host:5432/dbname
• Valide na inicialização para que o processo falhe antes de aceitar tráfego

3. Pool pg Mínimo

import pg from "pg";
 
const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,
  idleTimeoutMillis: 30_000,
});
 
export async function getUser(id: string) {
  const { rows } = await pool.query(
    "SELECT id, email FROM users WHERE id = $1",
    [id]
  );
  return rows[0] ?? null;
}

• Sempre use placeholders $1, $2 - nunca concatenação de strings
• max deve corresponder às consultas concorrentes esperadas, não apenas ao número de CPUs
• Exporte um pool por processo; não crie pools por requisição

Relacionado: Ajuste de Pool de Conexão - matemática de dimensionamento

4. Desligamento Gracioso do Pool

import pg from "pg";
 
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
 
process.on("SIGTERM", async () => {
  await pool.end();
  process.exit(0);
});

• pool.end() espera que os clientes em uso retornem
• Emparelhe com close() do servidor HTTP em manipuladores de desligamento gracioso
• Falta de desligamento vaza conexões até que o Postgres mate sessões ociosas

5. Wrapper Simples de Transação

import type pg from "pg";
 
export async function withTransaction<T>(
  pool: pg.Pool,
  fn: (client: pg.PoolClient) => Promise<T>
): Promise<T> {
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    const result = await fn(client);
    await client.query("COMMIT");
    return result;
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
}

• Use um único cliente para toda a transação
• Mantenha transações curtas - sem HTTP de saída dentro de BEGIN/COMMIT
• Chaves de idempotência ajudam quando retentativas reproduzem após rollback

6. Consulta de Verificação de Integridade

import type { Pool } from "pg";
 
export async function checkDatabase(pool: Pool): Promise<boolean> {
  try {
    await pool.query("SELECT 1");
    return true;
  } catch {
    return false;
  }
}

• Sondas de prontidão devem verificar a conectividade do DB, não apenas se o processo está ativo
• Use uma consulta leve; evite escanear tabelas grandes
• Registre totalCount e idleCount do pool em falhas repetidas

Exemplos Intermediários

7. Limite do Repositório (Porta)

// src/domain/user.ts
export type User = { id: string; email: string };
 
export interface UserRepository {
  findById(id: string): Promise<User | null>;
  create(email: string): Promise<User>;
}
 
// src/infrastructure/pg-user-repo.ts
import type { Pool } from "pg";
import type { User, UserRepository } from "../domain/user";
 
export function createPgUserRepo(pool: Pool): UserRepository {
  return {
    async findById(id) {
      const { rows } = await pool.query(
        "SELECT id, email FROM users WHERE id = $1",
        [id]
      );
      return rows[0] ?? null;
    },
    async create(email) {
      const { rows } = await pool.query(
        "INSERT INTO users (email) VALUES ($1) RETURNING id, email",
        [email]
      );
      return rows[0];
    },
  };
}

• Rotas chamam repositórios ou casos de uso, não SQL bruto inline
• Troque Postgres por um repositório em memória em testes unitários
• ORMs ainda ficam atrás desse limite

Relacionado: Casos de Uso e Serviços - camada de orquestração

8. Escolhendo Driver vs ORM

• APIs tipadas em projetos novos: Drizzle ou Prisma aceleram a entrega
• SQL pesado para relatórios: pg ou Drizzle com consultas brutas
• Um ORM por serviço - evite misturar Prisma e Drizzle no mesmo módulo

FAQs

Relacionados

• node-postgres (pg) - pool e transações
• Prisma - ORM com esquema primeiro
• Drizzle ORM - tipagem com SQL primeiro
• Ajuste de Pool de Conexão - max e PgBouncer
• Boas Práticas de Banco de Dados - checklist da equipe

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.