Banco de Dados

A Zenifra oferece bancos de dados gerenciados para quem quer operar PostgreSQL, MariaDB ou Chave‑Valor com Valkey sem administrar a infraestrutura manualmente.

Permissões necessárias

owner tem acesso completo na sessão de usuário. assistant, member e API Keys da organização precisam dos grants específicos.

Bancos suportados

Chave‑Valor com Valkey

Use este produto para sessões, estado compartilhado, contadores, locks e operações atômicas. Ele é persistente, usa os planos db-* e não é um banco relacional: consultas ad hoc, joins e relatórios devem continuar no sistema apropriado. A conexão usa VALKEY_URL, o usuário default, TLS e uma senha revelada uma única vez durante a criação ou rotação.

Veja o guia completo de Banco de Dados Chave‑Valor com Valkey e o guia compartilhado de conexão.

O que a plataforma oferece

Vídeo: criação de um banco PostgreSQL no plano DB-Free, do formulário à página do banco rodando.

• replicação conforme a topologia suportada por cada engine
• failover automático quando há mais de uma instância (PostgreSQL com 2 ou 3 instâncias; MariaDB sempre)
• senha gerada pela plataforma, exibida apenas na criação ou após uma rotação
• host, porta, usuário, banco e URI de conexão no console
• TLS obrigatório nas conexões
• storage persistente

Para Chave‑Valor, o console exibe hostname, porta, usuário default, TLS e a URI valkeys://; a senha completa não é recuperada pela leitura mascarada.

Dados de conexão

No console, você pode consultar:

• host: no formato postgresql-<id-do-projeto>.managed.zenifra.com ou mariadb-<id-do-projeto>.managed.zenifra.com
• porta
• username: app
• database name: app
• URI de conexão pronta para copiar

A senha é gerada pela plataforma e aparece somente uma vez: na tela de conclusão da criação ou depois de uma rotação de senha. Nas consultas posteriores, a URI aparece com a senha mascarada. Se você perder a senha, gere uma nova na edição do projeto.

Nota: a porta é definida pela plataforma. Copie os valores do console em vez de tratá-los como fixos.

Host e porta são públicos por padrão e aceitam conexões com TLS. Se o acesso público estiver desligado, o card de conexão mostra o aviso Acesso público desligado e o banco só aceita conexões pela rede privada da organização.

No PostgreSQL com 2 ou 3 instâncias, o console mostra também uma URI somente leitura, que direciona as consultas às réplicas. No MariaDB, a conexão disponibilizada aponta para a instância primária.

Acesso público

PostgreSQL, MariaDB, ClickHouse e Valkey (Chave‑Valor, Cache e Filas) aceitam conexões pelo host e pela porta públicos por padrão. Quando o banco só precisa atender aplicações da própria organização, você pode desligar o acesso público e usar apenas as conexões privadas entre aplicações.

• Religar devolve o mesmo host e a mesma porta. A URI de conexão externa continua igual, então não é preciso reconfigurar clientes externos.
• Conexões privadas entre aplicações continuam funcionando nos dois estados.
• Renovação de senha ou de credencial continua disponível com o acesso público desligado.
• A alteração é feita no card Acesso público, na edição do banco ou do Valkey, e pede confirmação. O banco precisa estar em execução e sem outra operação em andamento.
• owner tem a permissão. assistant, member e API Keys da organização precisam de grant explícito: database.exposure.update para PostgreSQL, MariaDB e ClickHouse, e managed_service.exposure.update para Valkey.

Atenção: ao desligar, clientes fora da Zenifra, como ferramentas de administração, scripts locais e aplicações hospedadas em outro lugar, deixam de conseguir conectar pelo endereço público. Antes de desligar, crie as conexões privadas das aplicações que usam o banco e atualize a variável de conexão delas para o endereço interno.

Os passos no console estão em Alterar configurações do PostgreSQL e do MariaDB. Pela API, use PATCH /v1/project/:id/database/exposure (Bancos de dados — API) ou, para Valkey, PATCH /v1/managed-services/:id/exposure (Serviços gerenciados — API).

Como conectar sua aplicação

A Zenifra não injeta automaticamente DATABASE_URL em projetos HTTP.

O fluxo correto é:

1. copiar a URI ou os dados de conexão no console
2. configurar manualmente a ENV DATABASE_URL no projeto HTTP

PostgreSQL com psql

A URI PostgreSQL fornecida pelo console usa sslmode=verify-full&sslrootcert=system. Isso exige TLS, valida a cadeia de certificados pelo armazenamento confiável do sistema e confirma que o hostname corresponde ao certificado.

Em versões modernas do psql, basta copiar a URI completa. Clientes mais antigos que não suportam sslrootcert=system devem configurar sslrootcert apontando para um bundle de CA confiável, por exemplo:

psql "postgresql://app:[REDACTED]@<host>:<port>/app?sslmode=verify-full&sslrootcert=/etc/ssl/certs/ca-certificates.crt"

Não substitua verify-full por require, disable ou qualquer opção que deixe de validar o certificado ou o hostname. Não use o endereço IP no lugar do host fornecido pelo console.

Alguns drivers precisam de ajustes, como psycopg[binary], asyncpg, pg (node-postgres) e mysql2. Veja os exemplos por linguagem e driver em Conectar sua aplicação ao banco.

PostgreSQL

• pode operar de 1 a 3 instâncias totais (o plano db-free usa sempre 1 instância)
• com 1 instância, existe apenas a instância primária
• com múltiplas instâncias, a primária atende escrita e leitura
• as demais instâncias são usadas como réplicas de leitura
• no pagamento por hora, a quantidade de instâncias pode ser aumentada ou reduzida depois
• em mensal e anual, a quantidade de instâncias fica fixa no contrato

MariaDB

• sempre opera com 3 instâncias: uma primária e duas réplicas
• não permite aumentar ou diminuir a quantidade de instâncias
• não está disponível no plano db-free; começa no db-starter

Versão do banco

Na criação, o usuário pode escolher qualquer versão disponível no console.

Na edição:

• é possível fazer upgrade para frente, para uma versão oferecida pelo plano: PostgreSQL 16, 17 ou 18; MariaDB 11
• downgrade não é suportado
• o banco precisa estar em execução

Atenção: upgrade de versão pode causar alguns minutos de indisponibilidade. Faça essa alteração em janela de baixo uso.

Storage

Todo banco de dados na Zenifra usa armazenamento persistente.

Regras de storage

• o storage pode aumentar
• o storage nunca pode diminuir
• a alteração só está disponível no pagamento por hora; em mensal e anual, a capacidade fica fixa durante o contrato
• no plano db-free, o storage é fixo em 1 GB
• aumentar storage pode causar indisponibilidade temporária

Failover e replicação

PostgreSQL e MariaDB contam com failover automático quando há réplicas: se a instância primária falhar, uma réplica pode ser promovida. No PostgreSQL, isso exige 2 ou 3 instâncias; com 1 instância não há réplica para assumir. O MariaDB sempre opera com 3 instâncias.

Durante um failover, conexões abertas podem ser encerradas. Configure sua aplicação para reconectar e repetir operações idempotentes.

Backups

A Zenifra não oferece hoje backup automático, restauração pelo console nem recuperação para um ponto no tempo para PostgreSQL e MariaDB. Réplicas protegem contra falha de instância, mas não contra exclusão acidental ou dados corrompidos pela aplicação.

Mantenha sua própria rotina de exportação, por exemplo com pg_dump (PostgreSQL) ou mariadb-dump/mysqldump (MariaDB), guarde as cópias fora do projeto e teste a restauração periodicamente.

Acesso do usuário

O usuário não tem acesso root ou superuser, mas possui acesso elevado o suficiente para operar o banco normalmente, criar tabelas, ler tabelas e executar o fluxo comum de uso da aplicação.

Métricas

As métricas de PostgreSQL e MariaDB estão disponíveis nos planos db-premium e db-enterprise. Elas são exibidas por instância, como um snapshot atualizado a cada 60 segundos, sem histórico:

• recursos: CPU, memória e uso/capacidade de armazenamento
• conexões
• atividade (transações ou consultas)
• cache de leitura
• tamanho do banco
• locks e deadlocks
• latência média e operações lentas
• saúde e replicação

Veja os guias de métricas do PostgreSQL e de métricas do MariaDB.

Próximos passos

1. Conectar sua aplicação ao banco
2. Configurações de Banco de Dados
3. Planos de Banco de Dados
4. Banco de Dados Chave‑Valor com Valkey
5. Analytics e ClickHouse
6. Criar projeto HTTP e configurar ENVs manualmente