Conceptos Básicos de Bases de Datos

8 ejemplos para empezar con bases de datos para backends de Node.js - 6 básicos y 2 intermedios.

Prerrequisitos

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

Para la optimización de pools y las compensaciones de ORM, consulta node-postgres (pg) y Prisma.

Ejemplos Básicos

1. SQL vs Documento - Cuándo Elegir Cada Uno

• La mayoría de las APIs B2B usan Postgres con pg o Drizzle/Prisma por defecto
• Los almacenes de documentos se ajustan a blobs de catálogo, registros de eventos y cambios rápidos de esquema
• El híbrido es común: Postgres para dinero, Redis para caché, S3 para archivos

Relacionado: Controlador de MongoDB - patrones de documentos

2. Cadena de Conexión Impulsada por el Entorno

// 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 codifiques credenciales directamente en el código fuente
• Formato de DATABASE_URL: postgres://usuario:contraseña@host:5432/nombre_db
• Valida al inicio para que el proceso falle antes de aceptar tráfico

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;
}

• Siempre usa los marcadores de posición $1, $2 - nunca concatenes cadenas
• max debe coincidir con las consultas concurrentes esperadas, no solo con el número de CPU
• Exporta un pool por proceso; no crees pools por solicitud

Relacionado: Optimización de Pool de Conexiones - cálculos de tamaño

4. Apagado Elegante del 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 a que los clientes prestados regresen
• Combínalo con close() del servidor HTTP en manejadores de apagado elegante
• La falta de apagado filtra conexiones hasta que Postgres cierra las sesiones inactivas

5. Envoltorio de Transacción Simple

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();
  }
}

• Usa un cliente para toda la transacción
• Mantén las transacciones cortas - no hagas HTTP saliente dentro de BEGIN/COMMIT
• Las claves de idempotencia ayudan cuando los reintentos se reproducen después de un rollback

6. Consulta de Verificación de Salud

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

• Las pruebas de preparación deben verificar la conectividad de la base de datos, no solo que el proceso esté activo
• Usa una consulta ligera; evita escanear tablas grandes
• Registra totalCount e idleCount del pool en caso de fallos repetidos

Ejemplos Intermedios

7. Límite del Repositorio (Puerto)

// 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];
    },
  };
}

• Las rutas llaman a repositorios o casos de uso, no a SQL sin procesar en línea
• Intercambia Postgres por un repositorio en memoria en pruebas unitarias
• Los ORM aún se encuentran detrás de este límite

Relacionado: Casos de Uso y Servicios - capa de orquestación

8. Elección entre Controlador y ORM

• APIs tipadas nuevas: Drizzle o Prisma aceleran la entrega
• SQL de informes pesados: pg o Drizzle con consultas puras
• Un ORM por servicio - evita mezclar Prisma y Drizzle en el mismo módulo

Preguntas Frecuentes

Relacionado

• node-postgres (pg) - pool y transacciones
• Prisma - ORM schema-first
• Drizzle ORM - tipado SQL-first
• Optimización de Pool de Conexiones - max y PgBouncer
• Mejores Prácticas de Bases de Datos - lista de verificación para equipos

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.