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

PrismaORM es una de las herramientas más populares para gestionar e interactuar con bases de datos en el ecosistema Node.js. En Square Cloud, la conexión con la base de datos MySQL exige una capa adicional de seguridad basada en certificados SSL. Esto valida la identidad del cliente y garantiza que todo el intercambio de datos sea cifrado y protegido contra interceptaciones.

1. Requisitos previos

Antes de poner manos a la obra, verifica que tengas los siguientes elementos listos:

• Plan Standard o superior: Necesario para crear y gestionar bases de datos en la plataforma.
• OpenSSL instalado: Esencial para convertir y unificar los archivos de seguridad. Los usuarios de Windows pueden utilizar la terminal de Git Bash.
• Archivos de certificado de Square Cloud: Ve al panel de tu base de datos MySQL en Square Cloud y descarga los archivos .pem, .key y .crt.

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

Prisma exige que los certificados de conexión SSL del cliente estén en un formato de contenedor específico para validar las operaciones hechas vía CLI — como npx prisma migrate dev o npx prisma db pull. A diferencia de otros ORMs que aceptan claves puras en formato textual, con Prisma en MySQL el archivo .p12 (PKCS#12) es indispensable.

Cómo generar el archivo .p12 manualmente

Abre tu terminal en la carpeta donde guardaste los certificados descargados de Square Cloud y ejecuta el siguiente comando OpenSSL:

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

Atención: Durante el proceso, la terminal te solicitará crear una contraseña de exportación (Export Password). Escribe una contraseña segura y anótala, pues será declarada directamente en tu string de conexión a continuación.

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

Para MySQL, Prisma extiende la string de conexión estándar añadiendo parámetros específicos para leer el archivo .p12 combinado con el certificado público .crt. Abre tu archivo .env y configura la variable siguiendo la tabla de parámetros obligatorios:

Ejemplo de URL en tu archivo .env:

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

(Asegúrate de sustituir USER, PASSWORD, HOST, PORT y DATABASE por las credenciales reales que aparecen en el dashboard de tu MySQL).

4. Implementación en el schema Prisma

Abre tu archivo schema.prisma y ajusta el bloque de datasource para garantizar que el proveedor esté apuntado correctamente al motor de mysql:

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

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

5. Buenas prácticas y seguridad

• Blindaje del repositorio (.gitignore): Nunca envíes tus archivos de certificado a GitHub o plataformas similares. Añade los archivos client.p12, client.crt, client.key y client.pem a tu archivo .gitignore. Dan acceso total y directo a tu base de datos.
• Rutas de archivo en Prisma: Como Prisma ejecuta los comandos de migración desde dentro del directorio /prisma, garantiza que las rutas definidas en la DATABASE_URL consigan localizar los archivos. Una buena práctica es dejar los archivos de certificado dentro de la propia carpeta prisma/ del proyecto, facilitando el mapeo relativo (ej.: sslidentity=./client.p12).
• Deploy y upload: Recuerda que, al generar el archivo .zip para subir tu aplicación a Square Cloud, los archivos client.p12 y client.crt deben incluirse en el paquete (ya que no pueden quedar fuera en el servidor de alojamiento), y la string de conexión final debe guardarse en la pestaña de Variables de Entorno (ENV) del dashboard.

Actualizado el: 13/06/2026