Skip to main content
Prisma ORM es un ORM para TypeScript que ofrece un esquema declarativo, una herramienta de migraciones (Prisma Migrate) y un Client generado con tipado seguro. En esta guía, conectará Prisma a ClickHouse Managed Postgres, creará una tabla mediante una migración y la consultará desde un script y desde un pequeño endpoint HTTP. Esta guía utiliza Prisma ORM 7 (probado con 7.10.0), la versión estable actual.

Requisitos previos

  • Node.js 20.19, 22.12 o 24 y posteriores
  • Un servicio de ClickHouse Managed Postgres
  • psql, para crear la base de datos. También puede ejecutar la sentencia CREATE DATABASE en la consola SQL.
  • En macOS: Docker, para ejecutar Prisma Migrate (consulte Ejecutar la migración)

Crear un servicio de ClickHouse Managed Postgres

En la consola de ClickHouse Cloud, haga clic en New service y seleccione Postgres. La instancia estará lista en unos minutos. Consulte la guía de inicio rápido para ver el proceso paso a paso.

Obtenga los detalles de conexión

Haga clic en Conectar en la barra lateral izquierda de su servicio. El cuadro de diálogo muestra su nombre de usuario, contraseña, servidor y puerto, además de cadenas de conexión listas para usar. Esta guía utiliza dos conexiones, ya que Prisma tiene dos componentes que se comunican con la base de datos:
  • Su aplicación (Prisma Client) se conecta a través de PgBouncer en el puerto 6432. PgBouncer agrupa las conexiones, de modo que muchos procesos de la aplicación o instancias sin servidor pueden compartir un número reducido de backends de Postgres.
  • La CLI de Prisma (Prisma Migrate) se conecta directamente en el puerto 5432. Mientras se ejecuta, Prisma Migrate adquiere un bloqueo consultivo a nivel de sesión. En el modo de agrupación por transacción de PgBouncer, ese bloqueo puede quedar retenido en un backend del grupo que después atiende a otros Clients, lo que deja bloqueadas las migraciones posteriores.
En la parte superior del cuadro de diálogo, alterne entre Directly y via PgBouncer para ver el puerto de cada una. El servidor y las credenciales son los mismos para ambas conexiones; solo cambia el puerto. Con via PgBouncer seleccionado, haga clic en Download CA certificate. Con Directly seleccionado, active primero Use SSL para que aparezca el botón. El archivo se llama <service-name>-ca-certificate.pem. También lo encontrará en Settings → CA Certificate. El certificado es exclusivo de su instancia y sirve para conectarse con sslmode=verify-full, que comprueba que realmente se está comunicando con su propio servidor.

Configurar el proyecto

Cree un proyecto de TypeScript e instale la CLI de Prisma, Prisma Client, el adaptador de controlador node-postgres y dotenv:
Instale prisma@7 y @prisma/client@7 de forma explícita. En el momento de redactar esta guía, la etiqueta latest de prisma en npm apunta a una versión candidata de Prisma 8, cuya configuración difiere de la que se describe aquí.
Cree un archivo tsconfig.json:
¿Va a añadirlo a una aplicación existente?Omita mkdir, npm init y el archivo tsconfig.json. En su proyecto, ejecute npm install tsx @types/pg prisma@7 --save-dev y npm install @prisma/client@7 @prisma/adapter-pg pg dotenv y, a continuación, siga con Inicializar Prisma.

Inicializar Prisma

1

Ejecutar prisma init

Esto crea prisma/schema.prisma y el archivo de configuración de Prisma prisma7.config.ts, añade un marcador de posición para DATABASE_URL en .env y el Client generado en .gitignore (y crea cualquiera de estos archivos si no existe), además de añadir skills de Prisma para agentes de programación con IA. A partir de Prisma 7.10, el archivo de configuración se llama prisma7.config.ts para evitar conflictos con el formato de Prisma 8.
2

Añadir el certificado de la CA

Mueva el certificado de la CA que descargó a la raíz del proyecto y cámbiele el nombre a ca-certificate.pem:
Las rutas relativas de los certificados se resuelven a partir del directorio desde el que se ejecutan los comandos, así que ejecute todos los comandos de esta guía desde la raíz del proyecto.

Configurar la conexión

1

Crear una base de datos

Cree una base de datos para la aplicación. Sustituya <PASSWORD> y el host por los valores del cuadro de diálogo Conectar:
2

Configurar las URL de conexión

En .env, sustituya el marcador de posición DATABASE_URL que añadió prisma init por estas dos URL de conexión, ambas apuntando a la base de datos guide_prisma. Use la contraseña del cuadro de diálogo Conectar:
Las dos URL usan parámetros de TLS distintos porque las leen controladores diferentes:
  • DATABASE_URL la lee node-postgres a través de @prisma/adapter-pg. Admite los parámetros estándar sslmode=verify-full&sslrootcert=..., los mismos que aparecen en el cuadro de diálogo Conectar.
  • DIRECT_URL la lee el motor de esquemas de la CLI de Prisma, que tiene sus propios parámetros: sslcert es la ruta al certificado de la CA y sslaccept=strict activa la verificación del certificado y del nombre del host.
No use sslmode=verify-full&sslrootcert=... en la URL de la CLI de Prisma. El motor de esquemas ignora sslrootcert y, sin sslaccept=strict, no verifica en absoluto el certificado del servidor, por lo que la conexión queda cifrada pero no autenticada.
3

Apuntar la CLI de Prisma a la conexión directa

Sustituya el contenido de prisma7.config.ts:
En Prisma 7, la URL del archivo de configuración solo la usa la CLI. Prisma Client obtiene su conexión del adaptador del controlador, que se configura en Consultar la base de datos.

Definir el esquema y ejecutar la migración

1

Agregar un modelo

Agregue un modelo Todo al final de prisma/schema.prisma:
2

Ejecutar la migración

En Linux, ejecute Prisma Migrate directamente:
En macOS, ejecute el mismo comando en un contenedor de Linux:
ClickHouse Managed Postgres solo acepta TLS 1.3. En macOS, el motor de esquemas de la CLI de Prisma utiliza la biblioteca TLS del sistema, que no puede establecer la conexión con esta configuración. El error que se produce es P1011: Error opening a TLS connection: One or more parameters passed to a function were not valid, o bien bad protocol version si elimina sslcert (prisma/orm#29600). Esto solo afecta a los comandos de la CLI que se conectan a la base de datos, como prisma migrate y prisma db pull. Prisma Client no se ve afectado, ya que se conecta a través de node-postgres. Para evitar el problema, ejecute la CLI en un contenedor de Linux o en su canalización de CI basada en Linux.
Prisma crea la migración SQL en prisma/migrations/ y la aplica:
3

Generar Prisma Client

El Client se genera en generated/prisma. Este comando no se conecta a la base de datos, por lo que puede ejecutarlo en cualquier plataforma.

Consultar la base de datos

1

Crear el Prisma Client

Cree lib/prisma.ts. El adaptador PrismaPg se conecta mediante DATABASE_URL, a través de PgBouncer:
No se requiere ninguna configuración de PgBouncer@prisma/adapter-pg envía cada consulta como una sentencia preparada sin nombre y nunca ejecuta DEALLOCATE, por lo que es compatible con el modo de agrupación por transacción de PgBouncer. Admite sin errores cientos de consultas distintas ejecutándose de forma concurrente en backends agrupados. El parámetro de URL pgbouncer=true de versiones anteriores de Prisma no es necesario y no tiene ningún efecto con el adaptador de controlador.
2

Ejecutar consultas CRUD

Cree script.ts:
Ejecútelo:
3

Servir los datos mediante HTTP

Cree server.ts, un servidor HTTP mínimo que crea tareas con POST /todos y las devuelve en cualquier solicitud GET:
Inicie el servidor:
En otra terminal, añada dos tareas:
Abra http://localhost:3000/todos en el navegador para verlas. La respuesta será similar a esta:

Verificar en la consola SQL

En la consola de ClickHouse Cloud, abra consola SQL en su servicio, expanda su base de datos y el esquema public, y seleccione la tabla Todo. También verá la tabla _prisma_migrations, donde Prisma Migrate registra las migraciones aplicadas. La tabla Todo contiene las dos filas que agregó mediante el endpoint HTTP:

Solución de problemas

Próximos pasos