> ## 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: cómo conectar a PostgreSQL (.p12)

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

PrismaORM es una herramienta poderosa para la gestión y el modelado de bases de datos. En Square Cloud, por cuestiones de seguridad y aislamiento, la conexión con la base de datos PostgreSQL exige el uso de certificados que validan la identidad del cliente. Esto garantiza que todas tus migraciones y consultas sean totalmente cifradas.

---

## 1. Requisitos previos

Antes de iniciar la configuración, asegúrate de tener:

* **Plan Standard o superior:** Necesario para habilitar y alojar bases de datos en la plataforma.
* **OpenSSL instalado:** Lo necesitarás para generar el archivo de identidad unificado. Si estás en Windows, puedes utilizar Git Bash o instalar OpenSSL directamente.
* **Archivos de certificado de Square Cloud:** Accede al dashboard de tu base de datos en Square Cloud y descarga los archivos `.pem`, `.key` y `.crt`.

---

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

Para realizar operaciones de CLI cruciales, como `npx prisma migrate dev` o `npx prisma db pull`, el driver nativo de Postgres en Prisma exige que las credenciales de seguridad estén encapsuladas en un formato específico. A diferencia de otros ORMs que aceptan claves en bruto, aquí el uso de un archivo **`.p12` (PKCS#12)** es obligatorio.

### Cómo generar el archivo .p12 manualmente
Utiliza los archivos `.key` y `.crt` proporcionados por Square Cloud para generar el archivo `.p12` unificado ejecutando el comando de abajo en tu terminal:

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

> **Atención:** Durante la generación en la terminal, OpenSSL solicitará una **contraseña (Export Password)**. Elige una contraseña segura y guárdala, pues deberá insertarse directamente en tu string de conexión.

---

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

Con el archivo `client.p12` generado, debes configurar la variable de entorno en tu archivo `.env`. Prisma extiende la URL estándar de PostgreSQL aceptando parámetros específicos para la seguridad SSL.

### Parámetros obligatorios:

| Parámetro | Descripción |
| ---- |
| **`sslidentity`** | Ruta relativa o absoluta apuntando a tu archivo `client.p12`. |
| **`sslpassword`** | La contraseña exacta que definiste durante la generación del archivo `.p12`. |

### Ejemplo de URL en tu archivo `.env`:
```text
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=./client.p12&sslpassword=SUA_SENHA_AQUI"
```
*(Sustituye `USER`, `PASSWORD`, `HOST`, `PORT` y `DATABASE` por los datos reales proporcionados en el panel de tu Postgres de Square Cloud).*

---

## 4. Implementación en el schema Prisma

En tu archivo `schema.prisma`, asegúrate de configurar el bloque `datasource` apuntando explícitamente el proveedor a `postgresql`:

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

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

---

## 5. Buenas prácticas y seguridad

* **Ignorando archivos sensibles:** Añade los archivos `client.p12`, `client.key`, `client.crt` y `client.pem` directamente a tu archivo `.gitignore`. Controlan el acceso administrativo a tu base de datos y nunca deben exponerse en repositorios públicos.
* **Rutas relativas en Prisma:** Prisma ejecuta los comandos desde la ubicación del archivo `schema.prisma`. Si guardas el archivo `client.p12` dentro de la carpeta `prisma/`, el parámetro en la URL deberá reflejarlo.
* **Deploy en Square Cloud:** Al realizar el deploy de tu aplicación en Square Cloud, recuerda subir el archivo `client.p12` junto a tu proyecto (no debe ignorarse en el ZIP de upload para que el alojamiento funcione) y configura la `DATABASE_URL` en la pestaña de Variables de Entorno (ENV) del panel.