Bancos de dados pela API

Use estas rotas para operar um projeto de banco de dados (PostgreSQL, MariaDB ou ClickHouse) já criado. Para criar o banco, veja Criar, listar e remover projetos. Serviços Valkey (Key-Value, Cache e Queue) usam as rotas de Serviços gerenciados.

Autenticação e permissões

Todas as rotas aceitam uma API Key da organização (x-api-key: znf_... ou Authorization: Bearer znf_...) ou um token de usuário com x-organization-id. As permissões usam o recurso database:<project-id>:

owner tem acesso completo. assistant, member e API Keys precisam do scope no ID do banco ou em database:*. Sem ele, a resposta é 403 com insufficient organization permission.

Consultar o estado

GET /v1/project/:id/database/status

{
  "status": "success",
  "message": "got database status successfully",
  "data": {
    "project_id": "6650f1a2b3c4d5e6f7a8b9c1",
    "name": "banco-pedidos",
    "plan": "db-basic",
    "status": "<estado-atual>"
  }
}

status é um texto informativo com o estado atual do banco; quando o estado detalhado não está disponível, a API devolve o status do projeto. Use-o para exibição e diagnóstico, não como valor fixo de automação. A resposta também pode trazer um objeto com detalhes específicos do mecanismo; não dependa desses detalhes. Para o ciclo de vida do projeto, use GET /v1/project/:id (Informações de projetos).

Se o projeto não existir na organização ou não for um banco, a resposta é 404 com database project not found.

Limite: 50 requisições por minuto.

Consultar a conexão

GET /v1/project/:id/database/connection

{
  "status": "success",
  "message": "got database connection successfully",
  "data": {
    "host": "<host>",
    "port": 5432,
    "database": "<database>",
    "username": "<username>",
    "connectionStringRO": "postgresql://<username>:********@<host-leitura>:5432/<database>",
    "connectionString": "postgresql://<username>:********@<host>:5432/<database>"
  }
}

A senha nunca é devolvida por esta rota: as strings de conexão vêm com a senha mascarada como ********. connectionStringRO aparece apenas quando o banco tem endpoint somente leitura (PostgreSQL com 2 ou mais instâncias, por exemplo). Bancos ClickHouse também retornam httpsPort. Se você perdeu a senha, renove-a com a rota abaixo. Projeto inexistente ou que não é banco retorna 404 com database project not found.

Limite: 50 requisições por minuto.

Listar aplicações vinculadas

GET /v1/project/:id/database/linked-applications

Lista as aplicações criadas junto com este banco a partir de um template e os nomes das variáveis de ambiente que receberam a conexão. Consulte antes de renovar a senha para saber quais aplicações precisarão de novas credenciais. Só aparecem aplicações que a credencial pode ler (project.read). Projeto inexistente retorna 404; projeto que não é banco retorna 400.

{
  "status": "success",
  "data": {
    "linked_applications": [
      { "project_id": "6650f1a2b3c4d5e6f7a8b9c0", "variable_names": ["DATABASE_URL"] }
    ]
  }
}

Evite consultas repetidas: a resposta da renovação de senha também traz essa lista.

Renovar a senha

PATCH /v1/project/:id/database/password

Gera uma nova senha aleatória para o banco. Envie um corpo vazio ({}). A senha anterior deixa de funcionar; atualize as aplicações que usam o banco.

{
  "status": "success",
  "message": "database credentials updated with success",
  "data": {
    "password": "<nova-senha>",
    "linked_applications": [
      { "project_id": "6650f1a2b3c4d5e6f7a8b9c0", "variable_names": ["DATABASE_URL"] }
    ]
  }
}

A nova senha aparece somente nesta resposta. Guarde-a em local seguro antes de descartar a resposta.

Limite: 5 requisições por minuto.

Atualizar a versão

PATCH /v1/project/:id/database/version

{
  "version": "18"
}

{
  "status": "success",
  "message": "mariadb version updated with success"
}

A mensagem de sucesso é a mesma para todos os mecanismos. Faça backup e valide a compatibilidade da aplicação antes de trocar de versão.

Limite: 5 requisições por minuto.

Exemplos

curl "https://api.zenifra.com/v1/project/6650f1a2b3c4d5e6f7a8b9c1/database/connection" \
  -H "x-api-key: znf_..."

curl -X PATCH "https://api.zenifra.com/v1/project/6650f1a2b3c4d5e6f7a8b9c1/database/password" \
  -H "x-api-key: znf_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Próximos passos

• Conheça planos e limites em Planos de banco de dados.
• Libere o acesso de origem certa ao criar o banco com network_access, descrito em Criar, listar e remover projetos.
• Acompanhe uso e custos em Cobrança do projeto.
• Consulte métricas em Métricas e Logs.