Prisma ORM: How to Connect to Square Cloud's MySQL Database

Prisma ORM is one of the most popular tools for managing and interacting with databases in the Node.js ecosystem. On Square Cloud, connecting to the MySQL database requires an additional security layer based on SSL certificates. This validates the client's identity and ensures that all data exchange is encrypted and protected against interception.

1. Prerequisites

Before getting started, make sure you have the following items ready:

• Standard Plan or higher: Required to create and manage databases on the platform.
• OpenSSL installed: Essential for converting and unifying the security files. Windows users can use the Git Bash terminal.
• Square Cloud Certificate Files: Go to your MySQL database dashboard on Square Cloud and download the .pem, .key, and .crt files.

2. The .p12 Certificate Challenge

Prisma's internal engine (Query Engine) requires that client SSL authentication keys be in a specific container format to validate operations performed via the CLI — such as npx prisma migrate dev or npx prisma db pull. Unlike other ORMs that accept raw keys in textual format, with Prisma on MySQL, the .p12 (PKCS#12) file is indispensable.

How to Manually Generate the .p12 File

Open your terminal in the folder where you saved the certificates downloaded from Square Cloud and run the following OpenSSL command:

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

Attention: During the process, the terminal will prompt you to create an Export Password. Type a secure password and save it, as it will be declared directly in your connection string right after.

3. Connection String Configuration (DATABASE_URL)

For MySQL, Prisma extends the default connection string by adding specific parameters to read the .p12 file combined with the public .crt certificate. Open your .env file and configure the variable following the parameter table:

Mandatory Parameters:

URL Example in Your .env File:

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

(Make sure to replace USER, PASSWORD, HOST, PORT, and DATABASE with the actual credentials that appear on your MySQL dashboard).

4. Implementation in the Prisma Schema

Open your schema.prisma file and adjust the datasource block to ensure that the provider is correctly pointed to the mysql engine:

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

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

5. Best Practices and Security

• Repository Shielding (.gitignore): Never send your certificate files to GitHub or similar platforms. Add the client.p12, client.crt, client.key, and client.pem files to your .gitignore file. They grant full and direct access to your database.
• File Paths in Prisma: Since Prisma runs migration commands from within the /prisma directory, ensure that the paths defined in the DATABASE_URL can locate the files. A best practice is to leave the certificate files inside the project's prisma/ folder itself, making relative mapping easier (e.g., sslidentity=./client.p12).
• Deployment and Upload: Remember that when generating the .zip file to upload your application to Square Cloud, the client.p12 and client.crt files must be included in the package (as they cannot be left out on the hosting server), and the final connection string must be saved in the Environment Variables (ENV) tab of the dashboard.

Updated on: 05/21/2026