Introducción a Prisma con Node.js y PostgreSQL

Introducción

Prisma es una opción práctica de ORM para servicios en Node y TypeScript que necesitan acceso a la base de datos con tipos definidos. La guía a continuación muestra un camino rápido desde un proyecto básico en Node hasta la creación de migraciones, un cliente generado y algunas consultas de lectura/escritura contra PostgreSQL. Prisma se sitúa entre el código en TypeScript de la aplicación y PostgreSQL: el archivo de esquema funciona como contrato, las migraciones modifican la base de datos y el cliente generado proporciona métodos con tipos definidos para cada modelo. Omitir alguno de estos tres elementos suele causar errores SQL en tiempo de ejecución o problemas en TypeScript al no poder acceder a los campos ya existentes en la base de datos.

Asegúrese primero de tener listo un proyecto en Node; si ese es el lenguaje del proyecto, también necesitará TypeScript.

Configuremos Prisma

Paso 1: Instalar Prisma y el Cliente de Prisma

Instale ambos paquetes en el directorio del proyecto:

npm install prisma @prisma/client

• prisma es la CLI para trabajar con esquemas, migraciones y generación de clientes.
• @prisma/client es la biblioteca cuyos códigos de aplicación se importan para consultar la base de datos.

Paso 2: Inicializar Prisma

Inicialícelo con PostgreSQL y una ruta de salida personalizada para el cliente:

npx prisma init --datasource-provider postgresql --output ../generated/prisma

Qué hace este comando:

• Crea una carpeta prisma que contiene schema.prisma con los parámetros de conexión y los modelos.
• Establece la fuente de datos en PostgreSQL.
• Crea un archivo raíz .env para almacenar datos confidenciales como la URL de la base de datos.
• --output ../generated/prisma redirige la salida del cliente generado fuera de la ubicación predeterminada.

Nota: prisma init utiliza PostgreSQL por defecto. Para otro motor, o cuando se omitió --datasource-provider, edite el bloque datasource en schema.prisma.

Ejemplo con PostgreSQL:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Ponga la cadena de conexión en .env:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA"

Sustituya USER, PASSWORD, HOST, PORT, DATABASE y SCHEMA por valores reales antes de modelar o migrar.

Paso 3: Agregar el esquema de Prisma y ejecutar migraciones

Use Prisma Migrate para crear tablas. Añada un modelo inicial a prisma/schema.prisma:

model Post {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  title     String   @db.VarChar(255)
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
}

model Profile {
  id     Int     @id @default(autoincrement())
  bio    String?
  user   User    @relation(fields: [userId], references: [id])
  userId Int     @unique
}

model User {
  id      Int      @id @default(autoincrement())
  email   String   @unique
  name    String?
  posts   Post[]
  profile Profile?
}

Para obtener orientación más detallada sobre el modelado, consulte la documentación oficial del modelo de datos. Para este camino de configuración, el modelo de ejemplo es suficiente para ejecutar la primera migración.

Cree y aplique la migración:

npx prisma migrate dev --name init

Esto hará:

• generar SQL a partir del esquema
• aplicarlo a la base de datos
• actualizar el cliente para que los modelos sean utilizables en el código

--name init es solo una etiqueta. Nombres útiles en el futuro podrían ser add-post-model o add-user-profile.

Paso 4: Generar el cliente Prisma

Genere el cliente después de la instalación:

npx prisma generate

La generación lee schema.prisma y escribe los tipos de TypeScript y los métodos de consulta en generated/prisma (o en la ruta de salida configurada). Importe el constructor y cree una instancia:

import { PrismaClient } from './generated/prisma'

const prisma = new PrismaClient()

Esa instancia puede leer y escribir a través de modelos como User, Post y Profile.

Información útil:

Cuando se ejecuta prisma generate, genera código adaptado al esquema actual. Después de realizar cambios en el esquema, regénerelo. Mantener la base de datos alineada generalmente implica usar prisma migrate dev o prisma db push; estos comandos también regeneran el cliente en segundo plano.

Paso 5: Consultar la base de datos con TypeScript y PostgreSQL

Con un cliente generado, comience con un script sencillo.

1. Cree un archivo nuevo llamado index.ts:

import { PrismaClient } from './generated/prisma'

const prisma = new PrismaClient()

async function main() {
  // ... you will write your Prisma Client queries here
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

2. Lectura de datos — liste los usuarios dentro de main:

async function main() {
  // ... you will write your Prisma Client queries here
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}

3. Escritura de datos — cree registros relacionados:

async function main() {
  await prisma.user.create({
    data: {
      name: 'Alice',
      email: 'alice@prisma.io',
      posts: {
        create: { title: 'Hello World' },
      },
      profile: {
        create: { bio: 'I like turtles' },
      },
    },
  })

  const allUsers = await prisma.user.findMany({
    include: {
      posts: true,
      profile: true,
    },
  })
  console.dir(allUsers, { depth: null })
}

• prisma.user.create inserta un usuario junto con los datos relacionados de publicaciones y perfil.
• findMany con include carga las publicaciones y el perfil relacionados.

console.dir, con profundidad total, muestra claramente los objetos anidados.

Considere la generación como parte del bucle de edición, y no como un proceso inicial único. Los cambios en el esquema sin regeneración hacen que el código de la aplicación hable con tipos obsoletos. Las migraciones sin un cliente correspondiente desincronizan las vistas en tiempo de ejecución y en tiempo de compilación de la base de datos. Un hábito sencillo: migrar (o enviar los cambios) y luego confirmar que la salida del cliente se ha actualizado, evita una gran cantidad de situaciones como “¿por qué TypeScript no conoce este campo?”.

Para el desarrollo local, mantenga .env fuera del control de versiones y documente la estructura esperada de DATABASE_URL en el README. Para CI, inyecte la misma variable desde los datos confidenciales y ejecute migrate deploy (o un paso equivalente) antes de las pruebas de integración que interactúen con la base de datos. La configuración anterior es suficiente para aprender a usar el cliente; el reforzamiento para producción incluye pooling de conexiones, un singleton de cliente compartido y desconexión explícita al cerrar el proceso.

¿Qué sigue?

Eso abarca una configuración de TypeScript con Node y Prisma: instalación, inicialización, migraciones, generación y ejecución de operaciones básicas de lectura y escritura. El siguiente nivel de profundidad es el modelado de datos: relaciones, restricciones y características avanzadas del esquema que mantienen la capa de base de datos expresiva a medida que la aplicación crece.

Lecturas relacionadas

• Prisma para desarrolladores de Spring Boot: Mapeo de hábitos JPA a Node.js — Una guía para desarrolladores de Java y JPA que pasan a Node.js: cómo los modelos, relaciones, migraciones y tipos de Prisma se corresponden con conceptos familiares, y qué les queda por hacer.
• Configuración de Prisma 7 con PostgreSQL en un proyecto TypeScript Node.js — Solución de los errores comunes al configurar Prisma 7 en TypeScript, desde URLs inválidas o indefinidas hasta problemas con rootDir, y conexión de PostgreSQL mediante el adaptador del controlador pg.
• Configuración de Prisma 7 con Accelerate URLs — Análisis detallado de prisma.config.ts, argumentos del constructor, protocolos accelerateURL y configuración dual de DATABASE_URL en Prisma 7.

Prisma 7 con NestJS y adaptadores de controlador de MySQL — Configure el cliente en TypeScript de Prisma 7, prisma.config.ts, y el adaptador de MariaDB dentro de un módulo global de NestJS.

Prisma vs consultas SQL personalizadas en PostgreSQL — Utilice Prisma para obtener velocidad en operaciones CRUD tipadas y recurre a SQL parametrizado cuando las uniones, agregaciones o características de Postgres requieran mayor control.