> ## 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 MySQL (SSL/.p12)

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

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

| Parameter | Description |
| ---- |
| **`sslidentity`** | Absolute or relative path pointing to your generated `client.p12` file. |
| **`sslpassword`** | The password you defined in the terminal when generating the `.p12` file. |
| **`sslcert`** | Path pointing to the public `client.crt` certificate provided by Square Cloud. |

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

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