Skip to main content
Drizzle ORM es un ORM para TypeScript con un generador de consultas de sintaxis similar a SQL, y drizzle-kit es la CLI que lo acompaña para generar y ejecutar migraciones. En esta guía, definirá una tabla todos en TypeScript, la creará mediante una migración de drizzle-kit y atenderá consultas de creación, lectura, actualización y eliminación desde un pequeño servidor HTTP en Node.js. Todas las conexiones usan TLS con verificación completa de certificados.

Requisitos previos

  • Node.js 20 o una versión posterior
  • Una cuenta de ClickHouse Cloud
  • psql, para crear la base de datos. También puede ejecutar la sentencia CREATE DATABASE en la consola SQL.

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 seguir el proceso paso a paso.

Obtener los detalles de conexión

Haga clic en Conectar en la barra lateral izquierda de su servicio. La ventana modal muestra su nombre de usuario, contraseña, servidor y puerto, e incluye un toggle Directly / via PgBouncer. Esta guía utiliza dos cadenas de conexión:
  • Directa (puerto 5432) para drizzle-kit. Las migraciones ejecutan DDL, pueden prolongarse durante mucho tiempo y pueden depender del estado de la sesión, como SET lock_timeout, por lo que deben conectarse directamente a Postgres.
  • PgBouncer (puerto 6432) para la aplicación. El PgBouncer incluido funciona en modo de agrupación por transacción y permite que muchas instancias de la aplicación, incluidas las funciones sin servidor, compartan un número reducido de conexiones a Postgres.
Si ejecuta un único servidor Node.js de larga duración, node-postgres ya mantiene su propio grupo de conexiones, por lo que también puede apuntar la aplicación a la conexión directa. Utilice la conexión de PgBouncer cuando escale horizontalmente a muchos procesos o trabaje en plataformas sin servidor.
Con Directly seleccionado, active Use SSL. La URL de conexión de la pestaña url termina ahora en sslmode=verify-full&sslrootcert=<service-name>-ca-certificate.pem, y el puerto es 5432. Seleccione via PgBouncer para ver los detalles de la conexión agrupada: el puerto cambia a 6432 y la URL siempre incluye sslmode=verify-full. En la ventana modal, haga clic en Download CA certificate. También puede descargarlo desde Settings → CA Certificate. El certificado es exclusivo de su instancia, de modo que el controlador puede usarlo para verificar que se está comunicando con su servidor.

Configurar el proyecto

Cree un proyecto e instale Drizzle ORM, el controlador node-postgres (pg) y drizzle-kit:
¿Va a añadirlo a una aplicación existente?Omita los comandos mkdir, npm init y npm pkg set type=module. En su proyecto, ejecute npm install drizzle-orm pg dotenv y npm install -D drizzle-kit tsx @types/pg y, a continuación, siga con Configurar la conexión.

Configurar la conexión

Mueva el certificado de CA que descargó al directorio del proyecto y cámbiele el nombre a ca-certificate.pem. Cree una base de datos para la aplicación. Sustituya <PASSWORD> y el host por los valores que aparecen en el cuadro de diálogo Conectar:
Añada ambas cadenas de conexión a un archivo .env en la raíz del proyecto o a su archivo .env existente. Solo difieren en el puerto y ambas apuntan a la base de datos guide_drizzle:
.env
node-postgres lee sslmode=verify-full y sslrootcert de la URL. Carga el archivo de la CA y verifica tanto la cadena de certificados como el nombre del host, por lo que no necesita código TLS adicional. La ruta de sslrootcert se resuelve en relación con el directorio desde el que ejecuta los comandos. No incluya .env en el control de versiones.
Si falta la CA o es incorrecta, la conexión falla con unable to verify the first certificate. Si el nombre del host no coincide con el certificado, falla con ERR_TLS_CERT_ALTNAME_INVALID. Si su contraseña contiene caracteres especiales como @, / o #, aplíqueles codificación URL.

Definir el esquema

Cree src/db/schema.ts:
src/db/schema.ts
Cree drizzle.config.ts en la raíz del proyecto. Este archivo indica a drizzle-kit dónde se encuentran el esquema y la conexión directa:
drizzle.config.ts

Ejecutar migraciones

Genera una migración SQL a partir del esquema:
El archivo generado drizzle/0000_init.sql contiene la sentencia CREATE TABLE. Revísalo y haz commit de la carpeta drizzle junto con tu código. A continuación, aplícalo:
drizzle-kit migrate registra las migraciones aplicadas en la tabla drizzle.__drizzle_migrations y, en ejecuciones posteriores, solo ejecuta las nuevas. Cada vez que modifique schema.ts, vuelva a ejecutar generate y, a continuación, migrate.
drizzle-kit migrate finaliza con estado 1 y sin ningún mensaje de error cuando no puede conectarse, por ejemplo, cuando la ruta de sslrootcert o la contraseña son incorrectas. Si esto ocurre, compruebe primero DIRECT_DATABASE_URL con psql.
drizzle-kit push aplica los cambios de esquema sin archivos de migración. Resulta práctico para crear prototipos, pero generate y migrate le proporcionan archivos SQL que se pueden revisar y un historial para producción.

Consultar la base de datos

Cree src/db/index.ts. Este archivo crea el client de Drizzle sobre un grupo de node-postgres mediante la conexión de PgBouncer:
src/db/index.ts
Cree src/server.ts, un pequeño servidor HTTP que ejecuta una consulta de Drizzle por ruta. En una aplicación existente, puede llamar a las mismas consultas db desde sus propios handlers de ruta:
src/server.ts
PgBouncer no requiere ninguna configuración del controlador. De forma predeterminada, las consultas de Drizzle usan sentencias sin nombre, y el PgBouncer incluido también admite sentencias preparadas con nombre, como las creadas con .prepare de Drizzle, en el modo de agrupación por transacción. Las funcionalidades a nivel de sesión, como LISTEN y los bloqueos consultivos de sesión, no funcionan a través de PgBouncer. Consulte las preguntas frecuentes.

Ejecutar y verificar

Inicie el servidor:
En una segunda terminal, cree dos tareas, marque la primera como completada y elimine la segunda:
La solicitud PATCH devuelve la fila actualizada:
Abre http://localhost:3101/todos en tu navegador para ver las tareas pendientes. La respuesta será similar a la siguiente:
Para ver los datos en la consola, abra consola SQL en la barra lateral izquierda de su servicio, expanda guide_drizzle y, a continuación, public, y haga clic en la tabla todos. El esquema drizzle contiene la tabla del historial de migraciones. La tabla contiene la fila restante:

Próximos pasos

Última modificación el 14 de octubre de 2026