> ## 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: como conectar ao PostgreSQL (.p12)

# PrismaORM: Como conectar no banco de dados PostgreSQL da Square Cloud

O PrismaORM é uma ferramenta poderosa para gerenciamento e modelagem de banco de dados. Na Square Cloud, por questões de segurança e isolamento, a conexão com o banco de dados PostgreSQL exige o uso de certificados que validam a identidade do cliente. Isso garante que todas as suas migrações e consultas sejam totalmente criptografadas.

---

## 1. Pré-requisitos

Antes de iniciar a configuração, certifique-se de possuir:

* **Plano Standard ou superior:** Necessário para habilitar e hospedar bancos de dados na plataforma.
* **OpenSSL instalado:** Você precisará dele para gerar o arquivo de identidade unificado. Caso esteja no Windows, você pode utilizar o Git Bash ou instalar o OpenSSL direto.
* **Arquivos de Certificado da Square Cloud:** Acesse o dashboard do seu banco de dados na Square Cloud e baixe os arquivos `.pem`, `.key` e `.crt`.

---

## 2. O Desafio do Certificado .p12

O Prisma possui um motor interno (Query Engine) escrito em Rust. Ao realizar operações de CLI cruciais, como o `npx prisma migrate dev` ou `npx prisma db pull`, o driver nativo do Postgres no Prisma exige que as credenciais de segurança estejam encapsuladas em um formato específico. Diferente de outros ORMs que aceitam chaves brutas, aqui o uso de um arquivo **`.p12` (PKCS#12)** é obrigatório.

### Como gerar o arquivo .p12 manualmente
Utilize os arquivos `.key` e `.crt` fornecidos pela Square Cloud para gerar o arquivo `.p12` unificado executando o comando abaixo no seu terminal:

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

> **Atenção:** Durante a geração no terminal, o OpenSSL solicitará uma **senha (Export Password)**. Escolha uma senha segura e guarde-a, pois ela deverá ser inserida diretamente na sua string de conexão.

---

## 3. Configuração da String de Conexão (DATABASE_URL)

Com o arquivo `client.p12` gerado, você deve configurar a variável de ambiente no seu arquivo `.env`. O Prisma estende a URL padrão do PostgreSQL aceitando parâmetros específicos para segurança SSL.

### Parâmetros Obrigatórios:

| Parâmetro | Descrição |
| ---- |
| **`sslidentity`** | Caminho relativo ou absoluto apontando para o seu arquivo `client.p12`. |
| **`sslpassword`** | A senha exata que você definiu durante a geração do arquivo `.p12`. |

### Exemplo de URL no seu arquivo `.env`:
```text
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=./client.p12&sslpassword=SUA_SENHA_AQUI"
```
*(Substitua `USER`, `PASSWORD`, `HOST`, `PORT` e `DATABASE` pelos dados reais fornecidos no painel do seu Postgres da Square Cloud).*

---

## 4. Implementação no Schema Prisma

No seu arquivo `schema.prisma`, certifique-se de configurar o bloco `datasource` apontando explicitamente o provedor para `postgresql`:

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

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

---

## 5. Boas Práticas e Segurança

* **Ignorando Arquivos Sensíveis:** Adicione os arquivos `client.p12`, `client.key`, `client.crt` e `client.pem` diretamente ao seu arquivo `.gitignore`. Eles controlam o acesso administrativo ao seu banco de dados e nunca devem ser expostos em repositórios públicos.
* **Caminhos Relativos no Prisma:** O Prisma executa comandos a partir da localização do arquivo `schema.prisma`. Se você salvar o arquivo `client.p12` dentro da pasta `prisma/`, o parâmetro na URL deverá refletir isso.
* **Deploy na Square Cloud:** Ao realizar o deploy da sua aplicação na Square Cloud, lembre-se de subir o arquivo `client.p12` junto ao seu projeto (ele não deve ser ignorado no ZIP de upload para a hospedagem funcionar) e configure a `DATABASE_URL` na aba de Variáveis de Ambiente (ENV) do painel.