Conexão e referências

O banco não entra na rede privada do grupo (nbg-…): ele fica no nó de banco e é acessado pela URL das variáveis, com TLS, no public_host. Por isso o app deve usar as variáveis entregues, nunca um hostname montado à mão.

Variáveis referenciáveis

Prefixo = name do serviço-banco (aqui db):

Motor	Referências
PostgreSQL	${{db.DATABASE_URL}}, ${{db.PGHOST}}, ${{db.PGPORT}}, ${{db.PGUSER}}, ${{db.PGPASSWORD}}, ${{db.PGDATABASE}}
MariaDB	${{db.DATABASE_URL}}, ${{db.MYSQL_HOST}}, ${{db.MYSQL_PORT}}, ${{db.MYSQL_USER}}, ${{db.MYSQL_PASSWORD}}, ${{db.MYSQL_DATABASE}}
SQLite	${{db.LIBSQL_URL}}, ${{db.LIBSQL_AUTH_TOKEN}}, ${{db.DATABASE_URL}}

Todas são sensíveis: o valor resolvido de quem as referencia herda a sensibilidade e fica mascarado em log e UI (veja Referência a valor sensível).

Ligar o app ao banco

Defina no serviço do app uma variável cujo valor é a referência. A resolução acontece no deploy.

P=$(curl -sS -X POST "$NEBULAR_API/v1/projects" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: conexao-proj-$(date +%s)-$RANDOM" \
  -d "{\"name\": \"demo-conexao-$(date +%s)-$RANDOM\"}" | jq -r '.id')
S=$(curl -sS -X POST "$NEBULAR_API/v1/projects/$P/services" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: conexao-svc-$P" \
  -d '{"name": "api", "kind": "app", "visibility": "private", "source": {"type": "image", "ref": "ghcr.io/org/app:1.2"}}' | jq -r '.id')

curl -sS -X PUT "$NEBULAR_API/v1/projects/$P/services/$S/variables/DATABASE_URL" \
  -H "Authorization: Bearer $NEBULAR_TOKEN" -H "Content-Type: application/json" \
  -d '{"value": "${{db.DATABASE_URL}}"}'

{"name": "DATABASE_URL"}

O POST do deploy responde 422 unresolved_reference se db não existir no projeto ou a variável não existir (details.references lista quais), e 422 reference_cycle se as referências formarem ciclo. Corrija a referência e faça deploy de novo; não adianta repetir igual.

Conexão com TLS

• PostgreSQL: mantenha sslmode=verify-full (já vem na DATABASE_URL); a CA é pública, não instale nada.
• MariaDB: ssl=true (já vem na DATABASE_URL).
• SQLite: LIBSQL_URL (TLS) + LIBSQL_AUTH_TOKEN.

Como o serviço alcança o banco

O serviço conecta ao public_host do nó de banco (por exemplo db1.<dominio>:5432), saindo da rede do projeto pela internet pública, sempre com TLS (sslmode=verify-full no PostgreSQL: valide o certificado e o nome do host, com a CA pública, sem instalar nada). O nó de banco só aceita conexões vindas dos IPs de saída da plataforma: um cliente em outra origem (seu notebook, outro provedor) é recusado na rede, mesmo com a credencial certa. Cada banco tem a sua própria credencial (usuário e senha só dele, sem privilégios administrativos), entregue pelas referências acima. O acesso direto de fora da plataforma não é suportado: faça a consulta de dentro de um serviço do projeto. Detalhes de isolamento: Isolamento.

Quando o valor muda

Rotação de credencial, restore em SQLite ou restore para banco novo mudam o valor referenciado: os serviços dependentes ficam marcados “precisam de redeploy”. Faça deploy deles (Deploys e status).

Se algo falhar

Resposta	O que fazer
422 unresolved_reference no deploy	Variável ou serviço referenciado não existe: confira o nome do serviço-banco e a variável da tabela acima.
422 reference_cycle no deploy	Remova a referência circular entre variáveis.
app não conecta (TLS/credencial)	Houve rotação? Faça deploy do app para re-resolver.
404 not_found	Projeto/serviço inexistente ou de outro time.

Veja Variáveis e referências e Erros.

Se um app usa um driver de banco (PostgreSQL, MySQL, MongoDB) mas nenhum banco está ligado, a plataforma detecta e sugere criar um banco gerenciado e injetar a referência ${{db.DATABASE_URL}} automaticamente — sem criar nada sem a sua autorização. Veja Sugestões de persistência.