> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# PrismaORM: how to connect to PostgreSQL (.p12)

# 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:

```bash
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:

| Parameter | Description |
| ---- |
| **`sslidentity`** | Relative or absolute path pointing to your `client.p12` file. |
| **`sslpassword`** | The exact password you defined during the `.p12` file generation. |

### URL Example in your `.env` file:
```text
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`:

```prisma
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.