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

Prisma ORM is a powerful tool for database management and modeling. On Square Cloud, for security and isolation reasons, connecting to the PostgreSQL database requires using certificates that validate the client's identity. This ensures that all your migrations and queries are fully encrypted.

1. Prerequisites

Before starting the configuration, make sure you have:

• Standard Plan or higher: Required to enable and host databases on the platform.
• OpenSSL installed: You will need it to generate the unified identity file. If you are on Windows, you can use Git Bash or install OpenSSL directly.
• Square Cloud Certificate Files: Access your database dashboard on Square Cloud and download the .pem, .key, and .crt files.

2. The .p12 Certificate Challenge

Prisma has an internal engine (Query Engine) written in Rust. When performing crucial CLI operations, such as npx prisma migrate dev or npx prisma db pull, Prisma's native Postgres driver requires that security credentials be encapsulated in a specific format. Unlike other ORMs that accept raw keys, here the use of a .p12 (PKCS#12) file is mandatory.

How to manually generate the .p12 file

Use the .key and .crt files provided by Square Cloud to generate the unified .p12 file by running the command below in your terminal:

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

Attention: During generation in the terminal, OpenSSL will prompt you for an Export Password. Choose a secure password and save it, as it must be entered directly into your connection string.

3. Connection String Configuration (DATABASE_URL)

With the client.p12 file generated, you must configure the environment variable in your .env file. Prisma extends the default PostgreSQL URL by accepting specific parameters for SSL security.

Mandatory Parameters:

URL Example in your .env file:

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

(Replace USER, PASSWORD, HOST, PORT, and DATABASE with the actual data provided in your Square Cloud Postgres panel).

4. Implementation in the Prisma Schema

In your schema.prisma file, make sure to configure the datasource block explicitly pointing the provider to postgresql:

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

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

5. Best Practices and Security

• Ignoring Sensitive Files: Add the client.p12, client.key, client.crt, and client.pem files directly to your .gitignore file. They control administrative access to your database and must never be exposed in public repositories.
• Relative Paths in Prisma: Prisma executes commands from the location of the schema.prisma file. If you save the client.p12 file inside the prisma/ folder, the parameter in the URL must reflect that.
• Deploying on Square Cloud: When deploying your application on Square Cloud, remember to upload the client.p12 file along with your project (it should not be ignored in the upload ZIP for the hosting to work correctly) and configure the DATABASE_URL in the Environment Variables (ENV) tab of the dashboard.

Updated on: 05/21/2026