PrismaORM: Como conectar no banco de dados MySQL da Square Cloud

O PrismaORM é uma das ferramentas mais populares para gerenciar e interagir com bancos de dados no ecossistema Node.js. Na Square Cloud, a conexão com o banco de dados MySQL exige uma camada adicional de segurança baseada em certificados SSL. Isso valida a identidade do cliente e garante que toda a troca de dados seja criptografada e protegida contra interceptações.

1. Pré-requisitos

Antes de colocar a mão na massa, verifique se você tem os seguintes itens prontos:

• Plano Standard ou superior: Necessário para criar e gerenciar bancos de dados na plataforma.
• OpenSSL instalado: Essencial para converter e unificar os arquivos de segurança. Usuários Windows podem utilizar o terminal do Git Bash.
• Arquivos de Certificado da Square Cloud: Vá até o painel do seu banco de dados MySQL na Square Cloud e baixe os arquivos .pem, .key e .crt.

2. O Desafio do Certificado .p12

O motor interno do Prisma (Query Engine) exige que as chaves de autenticação SSL do cliente estejam em um formato de contêiner específico para validar as operações feitas via CLI — como o npx prisma migrate dev ou npx prisma db pull. Diferente de outros ORMs que aceitam chaves puras no formato textual, com o Prisma no MySQL, o arquivo .p12 (PKCS#12) é indispensável.

Como gerar o arquivo .p12 manualmente

Abra o seu terminal na pasta onde você salvou os certificados baixados da Square Cloud e execute o seguinte comando OpenSSL:

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

Atenção: Durante o processo, o terminal solicitará que você crie uma senha de exportação (Export Password). Digite uma senha segura e anote-a, pois ela será declarada diretamente na sua string de conexão logo em seguida.

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

Para o MySQL, o Prisma estende a string de conexão padrão adicionando parâmetros específicos para ler o arquivo .p12 combinado com o certificado público .crt. Abra o seu arquivo .env e configure a variável seguindo a tabela de parâmetros:

Parâmetros Obrigatórios:

Exemplo de URL no seu arquivo .env:

DATABASE_URL="mysql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=./client.p12&sslpassword=SUA_SENHA_AQUI&sslcert=./client.crt"

(Certifique-se de substituir USER, PASSWORD, HOST, PORT e DATABASE pelas credenciais reais que aparecem no dashboard do seu MySQL).

4. Implementação no Schema Prisma

Abra o seu arquivo schema.prisma e ajuste o bloco de datasource para garantir que o provedor esteja apontado corretamente para o motor do mysql:

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

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

5. Boas Práticas e Segurança

• Blindagem do Repositório (.gitignore): Nunca envie seus arquivos de certificado para o GitHub ou plataformas similares. Adicione os arquivos client.p12, client.crt, client.key e client.pem ao seu arquivo .gitignore. Eles dão acesso total e direto ao seu banco de dados.
• Caminhos de Arquivo no Prisma: Como o Prisma roda os comandos de migração de dentro do diretório /prisma, garanta que os caminhos definidos na DATABASE_URL consigam localizar os arquivos. Uma boa prática é deixar os arquivos de certificado dentro da própria pasta prisma/ do projeto, facilitando o mapeamento relativo (ex: sslidentity=./client.p12).
• Deploy e Upload: Lembre-se de que, ao gerar o arquivo .zip para subir sua aplicação para a Square Cloud, o arquivo client.p12 e o client.crt precisam ser incluídos no pacote (já que eles não podem ficar de fora no servidor de hospedagem), e a string de conexão final deve ser salva na aba de Variáveis de Ambiente (ENV) do dashboard.

Atualizado em: 18/05/2026