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:

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:

Exemplo de URL no seu arquivo .env:

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:

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.

Atualizado em: 18/05/2026