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 sentenciaCREATE DATABASEen 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) paradrizzle-kit. Las migraciones ejecutan DDL, pueden prolongarse durante mucho tiempo y pueden depender del estado de la sesión, comoSET 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.
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 controladornode-postgres (pg) y drizzle-kit:
Configurar la conexión
Mueva el certificado de CA que descargó al directorio del proyecto y cámbiele el nombre aca-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:
.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
Creesrc/db/schema.ts:
src/db/schema.ts
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: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 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
Creesrc/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
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:PATCH devuelve la fila actualizada:
http://localhost:3101/todos en tu navegador para ver las tareas pendientes. La respuesta será similar a la siguiente:
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
- Conexión: cadenas de conexión, PgBouncer y TLS
- Configuración: parámetros de Postgres y PgBouncer, como
max_connections - Réplicas de lectura: escale las lecturas con
withReplicasde Drizzle - Seguridad: listas de acceso por IP y redes privadas