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).

Em bancos Analytics (ClickHouse), data.clickhouse traz apenas status, instances, readyInstances e storage (e cpu e memory quando disponíveis):

{
  "status": "success",
  "message": "got database status successfully",
  "data": {
    "project_id": "6650f1a2b3c4d5e6f7a8b9c2",
    "name": "analytics-pedidos",
    "plan": "analytics-production",
    "status": "<estado-atual>",
    "clickhouse": {
      "status": "<estado-atual>",
      "instances": 3,
      "readyInstances": 3,
      "storage": "<armazenamento>"
    }
  }
}

Não dependa de outros campos. Durante uma troca de plano, instances e readyInstances ajudam a acompanhar o andamento; para o estado da troca, use plan_change em GET /v1/project/:id (Informações de projetos).

Um banco parado responde status: "stopped" em qualquer mecanismo. Se o projeto não existir na organização ou não for um banco, a resposta é 404 com database project not found; um :id em formato inválido retorna 400.

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 que usam este banco e os nomes das variáveis de ambiente que receberam a conexão: as criadas junto com o banco a partir de um template e as ligadas por uma conexão interna. O campo via indica a origem do vínculo (template, connection ou ambos). Aplicações excluídas não aparecem. 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"], "via": ["template"] }
    ]
  }
}

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

Limite: 50 requisições por minuto.

Renovar a senha

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

Gera uma nova senha aleatória para o banco PostgreSQL, MariaDB ou ClickHouse. Envie um corpo vazio ({}). A operação é síncrona: a resposta 200 só chega depois que a nova senha foi aplicada, e a senha anterior deixa de funcionar. Atualize as aplicações que usam o banco. Para Key Value, cache e fila, use a rotação de credencial de serviços gerenciados.

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

A nova senha aparece somente nesta resposta, enviada com Cache-Control: no-store. Guarde-a em local seguro antes de descartar a resposta.

O banco precisa estar em running. Se a renovação falhar no meio, a Zenifra restaura a credencial anterior. Enquanto uma renovação estiver aberta, parar o banco, trocar o plano, mudar instâncias ou armazenamento respondem 409 com PROJECT_OPERATION_IN_PROGRESS.

Limite: 5 requisições por minuto.

Atualizar a versão

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

{
  "version": "18"
}

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

A troca só avança de versão: não é possível voltar para uma versão anterior. O banco precisa estar em running. Faça backup e valide a compatibilidade da aplicação antes de trocar de versão. ClickHouse tem uma única versão disponível e não aceita esta operaçã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.