Configuração do Lakebase Postgres

O AppKit se conecta ao Lakebase Postgres por meio de um recurso postgres declarado no databricks.yml e da variável LAKEBASE_ENDPOINT definida no app.yaml.

Esta página trata da configuração no AppKit. Para saber mais sobre o Lakebase em si (projetos, branches, autoscaling, escala a zero), consulte a documentação do Lakebase ou a agent skill databricks-lakebase.

Valores de conexão

O Databricks Apps injeta a maioria dos valores de conexão na inicialização. LAKEBASE_ENDPOINT é a exceção: ele é declarado no app.yaml por meio de valueFrom: postgres e resolvido na inicialização a partir do recurso postgres:

env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres

No desenvolvimento local, esses valores vêm do seu arquivo .env. A seção Configuração local explica como preenchê-los.

Manifesto de plugins

Ao registrar o plugin lakebase() em createApp, o AppKit gera o arquivo appkit.plugins.json, que declara os recursos exigidos pelo plugin. Execute npx @databricks/appkit plugin sync --write para regenerá-lo após adicionar ou alterar plugins:

npx @databricks/appkit plugin sync --write

Isso é executado automaticamente durante npm run dev e npm run build. Faça o commit do arquivo junto com seu código.

A referência de configuração do AppKit detalha as vinculações de recursos de plugins no app.yaml.

Hierarquia de recursos

O Lakebase Postgres organiza os recursos em projetos que contêm branches, e cada branch contém computes e bancos de dados.

projects/{project_id}
  └── branches/{branch_id}
        ├── endpoints/{endpoint_id}   (compute)
        └── databases/{database_id}

• Project: contêiner de nível superior. Criado com databricks postgres create-project.
• Branch: ambiente de banco de dados isolado. Novos projetos recebem um branch production padrão com um banco de dados databricks_postgres.
• Compute: fornece capacidade de processamento e memória para um branch. Cada branch recebe automaticamente um compute primary de leitura e escrita. Réplicas somente leitura podem ser adicionadas para escalar as leituras.
• Database: um banco de dados PostgreSQL dentro de um branch. Liste com databricks postgres list-databases <branch>.

A CLI e a API se referem aos computes como endpoints (ENDPOINT_TYPE_READ_WRITE para leitura e escrita, ENDPOINT_TYPE_READ_ONLY para réplicas de leitura). Os comandos e caminhos de recursos deste documento usam esse termo.

A referência da CLI postgres abrange todos os comandos databricks postgres.

Branching

As branches criam ambientes de banco de dados isolados. Ao criar uma branch, o Lakebase Postgres copia o esquema e os dados da branch de origem por meio de copy-on-write. A criação de novas branches é instantânea e você paga apenas pelos dados que alterar.

Cada nova branch recebe um endpoint de leitura e escrita primary em projects/{project_id}/branches/{branch_id}/endpoints/primary, que herda as default_endpoint_settings do projeto. Use create-endpoint para adicionar réplicas de leitura (ENDPOINT_TYPE_READ_ONLY).

As branches exigem uma política de expiração (ttl, expire_time ou no_expiry: true). Consulte Expiração de branch para ver todas as opções. Para comandos da CLI, veja os exemplos em Feature branches.

Autoscaling

Os computes escalam automaticamente entre um mínimo e um máximo de unidades de compute (CU) configurados. Você define o intervalo por projeto ou por endpoint. Os valores padrão de CU, o tamanho máximo de compute e a restrição de mín./máx. são configurações do Lakebase que mudam ao longo do tempo, portanto consulte Autoscaling para ver os valores atuais.

O escalonamento dentro do intervalo configurado ocorre sem interrupção das conexões. Alterar o mínimo ou o máximo pode causar uma breve interrupção.

databricks postgres update-endpoint \
  projects/my-project/branches/production/endpoints/primary \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{"spec": {"autoscaling_limit_min_cu": 1.0, "autoscaling_limit_max_cu": 8.0}}'

Escala para zero

O escala para zero suspende computes ociosos para eliminar custos. Quando chega uma nova consulta, o compute é retomado automaticamente (normalmente em algumas centenas de milissegundos).

O tempo limite padrão é de 24 horas. Defina qualquer valor entre 60 segundos e 7 dias. Em branches de desenvolvimento, tempos limite mais curtos (30 minutos, por exemplo) reduzem ainda mais os custos. Aplicativos conectados a um compute suspenso terão uma breve pausa na primeira consulta. Implemente lógica de repetição de conexão no seu aplicativo.

Quando um compute é retomado, o contexto da sessão é reiniciado (tabelas temporárias, instruções preparadas, configurações de sessão, pools de conexões).

databricks postgres update-project \
  projects/my-project \
  "spec.default_endpoint_settings" \
  --json '{"spec": {"default_endpoint_settings": {"suspend_timeout_duration": "300s"}}}'

databricks postgres update-endpoint \
  projects/my-project/branches/production/endpoints/primary \
  "spec.suspension" \
  --json '{"spec": {"suspend_timeout_duration": "300s"}}'

databricks postgres update-endpoint \
  projects/my-project/branches/production/endpoints/primary \
  "spec.suspension" \
  --json '{"spec": {"no_suspension": true}}'

Próximos passos

Consulte Desenvolvimento com Lakebase Postgres para configuração local, feature branches e a API completa do plugin, ou explore o catálogo de templates para conferir padrões completos.