PrismaORM: cómo conectar a la base de datos PostgreSQL de Square Cloud

PrismaORM es una herramienta poderosa para la gestión y el modelado de bases de datos. En Square Cloud, por cuestiones de seguridad y aislamiento, la conexión con la base de datos PostgreSQL exige el uso de certificados que validan la identidad del cliente. Esto garantiza que todas tus migraciones y consultas sean totalmente cifradas.

1. Requisitos previos

Antes de iniciar la configuración, asegúrate de tener:

• Plan Standard o superior: Necesario para habilitar y alojar bases de datos en la plataforma.
• OpenSSL instalado: Lo necesitarás para generar el archivo de identidad unificado. Si estás en Windows, puedes utilizar Git Bash o instalar OpenSSL directamente.
• Archivos de certificado de Square Cloud: Accede al dashboard de tu base de datos en Square Cloud y descarga los archivos .pem, .key y .crt.

2. El desafío del certificado (.p12)

Para realizar operaciones de CLI cruciales, como npx prisma migrate dev o npx prisma db pull, el driver nativo de Postgres en Prisma exige que las credenciales de seguridad estén encapsuladas en un formato específico. A diferencia de otros ORMs que aceptan claves en bruto, aquí el uso de un archivo .p12 (PKCS#12) es obligatorio.

Cómo generar el archivo .p12 manualmente

Utiliza los archivos .key y .crt proporcionados por Square Cloud para generar el archivo .p12 unificado ejecutando el comando de abajo en tu terminal:

openssl pkcs12 -export -out client.p12 -inkey client.key -in client.crt

Atención: Durante la generación en la terminal, OpenSSL solicitará una contraseña (Export Password). Elige una contraseña segura y guárdala, pues deberá insertarse directamente en tu string de conexión.

3. Configuración de la string de conexión (DATABASE_URL)

Con el archivo client.p12 generado, debes configurar la variable de entorno en tu archivo .env. Prisma extiende la URL estándar de PostgreSQL aceptando parámetros específicos para la seguridad SSL.

Parámetros obligatorios:

Ejemplo de URL en tu archivo .env:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=./client.p12&sslpassword=SUA_SENHA_AQUI"

(Sustituye USER, PASSWORD, HOST, PORT y DATABASE por los datos reales proporcionados en el panel de tu Postgres de Square Cloud).

4. Implementación en el schema Prisma

En tu archivo schema.prisma, asegúrate de configurar el bloque datasource apuntando explícitamente el proveedor a postgresql:

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

generator client {
  provider = "prisma-client-js"
}

5. Buenas prácticas y seguridad

• Ignorando archivos sensibles: Añade los archivos client.p12, client.key, client.crt y client.pem directamente a tu archivo .gitignore. Controlan el acceso administrativo a tu base de datos y nunca deben exponerse en repositorios públicos.
• Rutas relativas en Prisma: Prisma ejecuta los comandos desde la ubicación del archivo schema.prisma. Si guardas el archivo client.p12 dentro de la carpeta prisma/, el parámetro en la URL deberá reflejarlo.
• Deploy en Square Cloud: Al realizar el deploy de tu aplicación en Square Cloud, recuerda subir el archivo client.p12 junto a tu proyecto (no debe ignorarse en el ZIP de upload para que el alojamiento funcione) y configura la DATABASE_URL en la pestaña de Variables de Entorno (ENV) del panel.

Actualizado el: 13/06/2026