Desenvolvimento com Lakebase Postgres

Esta página aborda o desenvolvimento com Lakebase Postgres a partir de um app AppKit. Para o Lakebase em si (projetos, branches, autoscaling, conectividade), consulte a documentação do Lakebase ou a agent skill databricks-lakebase.

API do plugin do AppKit

O plugin lakebase() fornece um pg.Pool padrão com refresh automático de tokens OAuth. Depois de registrado, acesse-o por meio de AppKit.lakebase:

import { createApp, lakebase, server } from "@databricks/appkit";

const AppKit = await createApp({
  plugins: [server(), lakebase()],
});

// Consulta parametrizada padrão
const { rows } = await AppKit.lakebase.query<{ id: number; name: string }>(
  "SELECT id, name FROM app.items WHERE active = $1",
  [true],
);

// Configuração pronta para ORM (Drizzle, Prisma, TypeORM, etc.)
const ormConfig = AppKit.lakebase.getOrmConfig();
// Retorna: { host, port, database, ssl, user, ... }

// Configuração compatível com pg
const pgConfig = AppKit.lakebase.getPgConfig();

// pg.Pool puro para uso avançado
const pool = AppKit.lakebase.pool;

Configuração do pool

Sobrescreva os valores padrão do pool de conexões passando um objeto pool:

lakebase({
  pool: {
    max: 10, // máximo de conexões (padrão: 10)
    connectionTimeoutMillis: 5000, // tempo limite de conexão em ms (padrão: 10000)
    idleTimeoutMillis: 30000, // tempo limite de inatividade em ms (padrão: 30000)
  },
});

O padrão max: 10 aplica-se ao pool compartilhado do service principal. Já os pools por usuário, criados em nome do usuário por asUser(req), têm como padrão max: 3.

Integração de cache

O Lakebase Postgres também serve de base para o plugin de cache do AppKit quando está íntegro. Para a API completa, a integração com ORM e a configuração de conexão, consulte a referência do plugin.

Modelo de autenticação

O Lakebase Postgres autentica conexões de banco de dados usando tokens OAuth ou senhas nativas do Postgres. O método depende de onde seu app é executado.

Apps implantados: ao adicioná-lo como recurso a um Databricks App, o Databricks cria um service principal automaticamente, concede a ele uma role correspondente no Postgres e injeta os detalhes de conexão como variáveis de ambiente. O plugin lakebase() do AppKit cuida do refresh do token OAuth automaticamente.

Desenvolvimento local: sua identidade pessoal do Databricks se conecta com um token OAuth gerado pelo comando databricks postgres generate-database-credential. Os tokens expiram após uma hora, mas a expiração só é verificada no login: conexões já abertas continuam ativas mesmo depois que o token expira. Execute databricks apps deploy pelo menos uma vez antes de rodar npm run dev. A seção Configuração local explica por que a ordem importa e o que fazer caso você se depare com erros de permissão.

About authentication aborda a autenticação por senha do Postgres, a rotação de tokens e os fluxos máquina a máquina.

Configuração local

O comando databricks apps init preenche o .env com os valores corretos de conexão do Lakebase Postgres. Execute databricks apps deploy antes de npm run dev. A implantação configura uma identidade gerenciada (o service principal do app), que cria o schema app e as tabelas na primeira inicialização e se torna proprietária deles. Se, em vez disso, você executar npm run dev primeiro, esses objetos serão criados com as suas credenciais pessoais. Nesse caso, o app implantado não conseguirá acessá-los e retornará o erro permission denied for schema app.

Acesso local ao banco de dados

Se você criou o projeto Lakebase Postgres, sua identidade já tem o acesso necessário. Depois que databricks apps deploy for executado uma vez, npm run dev funciona.

Para colaboradores que precisam de acesso local de leitura/escrita, conceda a eles uma role na branch pela interface do Lakebase (Roles & Databases). A autenticação por senha do Postgres é uma alternativa ao OAuth: habilite as conexões por senha, crie uma role com senha e use essa senha como PGPASSWORD no .env. About authentication descreve os passos para as duas opções.

Você também pode gerar uma credencial de curta duração para usar com qualquer cliente PostgreSQL (DBeaver, pgAdmin, DataGrip ou um driver de linguagem):

databricks postgres generate-database-credential \
  projects/my-project/branches/production/endpoints/primary

A documentação do plugin do AppKit: desenvolvimento local aborda alternativas de permissões granulares para equipes que precisam de acesso restrito ao escopo do schema.

Conectar com psql

O databricks psql abre uma sessão interativa do PostgreSQL em um endpoint de branch. É necessário ter o psql instalado localmente. Se nenhum destino for informado, o comando pede que você escolha entre os bancos de dados a que tem acesso.

databricks psql --project my-project

Passe argumentos adicionais diretamente para o psql após o separador --, por exemplo: databricks psql --project my-project -- -c "SELECT 1".

Feature branches

Use as branches do Lakebase Postgres para isolar alterações de esquema e testar migrações sem afetar a produção:

databricks postgres create-branch projects/my-project feature-xyz \
  --json '{"spec": {"no_expiry": true}}'

Um endpoint primary de leitura e escrita é criado automaticamente, herdando as default_endpoint_settings do projeto. As branches exigem uma política de expiração (ttl, expire_time ou no_expiry: true). Consulte Expiração de branch para conhecer as políticas disponíveis.

Exclua ao terminar:

databricks postgres delete-branch projects/my-project/branches/feature-xyz

Aplicativos fora da plataforma

Para aplicativos hospedados fora do Databricks (AWS, Vercel, Netlify, entre outros), a plataforma não injeta detalhes de conexão nem renova tokens OAuth automaticamente. A rotação de tokens é responsabilidade do aplicativo. Sobre a autenticação do Lakebase aborda a rotação de tokens e os padrões máquina a máquina. O template Lakebase Off-Platform inclui uma implementação completa, com configuração de ambiente e integração com o Drizzle ORM.

Para provisionar e conectar sem um template, crie um projeto, consulte seu endpoint e banco de dados e, em seguida, conecte-se:

databricks postgres create-project <project-id>
databricks postgres list-endpoints projects/<project-id>/branches/production -o json
databricks postgres list-databases projects/<project-id>/branches/production -o json
databricks psql --project <project-id>

create-project cria um projeto com uma branch production padrão, um banco de dados databricks_postgres e um endpoint de leitura e escrita. Se você não tiver o psql, execute databricks postgres generate-database-credential <endpoint-path> e use o token retornado como senha (o nome de usuário é seu e-mail do Databricks) em qualquer cliente PostgreSQL. Consulte a documentação do Lakebase ou a agent skill databricks-lakebase para conhecer o fluxo completo e as flags.

Os valores que você precisa obter na saída de list-endpoints e list-databases:

Operações de longa duração

Por padrão, os comandos de criação, atualização e exclusão bloqueiam até a conclusão. Use --no-wait para retornar imediatamente e consultar o status:

databricks postgres create-project my-project \
  --json '{"spec": {"display_name": "My Project"}}' \
  --no-wait

databricks postgres get-operation projects/my-project/operations/<operation-id>

Declarative Automation Bundles

Os Declarative Automation Bundles (DABs) permitem definir a infraestrutura do Lakebase Postgres como código no databricks.yml, versionada junto com sua aplicação. Um bundle especifica postgres_projects, postgres_branches e postgres_endpoints sob resources.

bundle:
  name: my-lakebase-app

resources:
  postgres_projects:
    my_app:
      project_id: "my-lakebase-app"
      display_name: "My Lakebase Postgres App"
      pg_version: 17
      history_retention_duration: "172800s"
      default_endpoint_settings:
        autoscaling_limit_min_cu: 0.5
        autoscaling_limit_max_cu: 1.0
        suspend_timeout_duration: "300s"
        pg_settings:
          log_min_duration_statement: "1000"

  postgres_branches:
    dev_branch:
      parent: ${resources.postgres_projects.my_app.id}
      branch_id: "dev"
      no_expiry: true
      is_protected: false

  postgres_endpoints:
    read_replica:
      parent: ${resources.postgres_branches.dev_branch.id}
      endpoint_id: "replica"
      endpoint_type: "ENDPOINT_TYPE_READ_ONLY"
      autoscaling_limit_min_cu: 0.5
      autoscaling_limit_max_cu: 0.5

Validar e implantar

databricks bundle validate
databricks bundle deploy

bundle deploy é idempotente: cria novos recursos e atualiza os existentes para refletir a configuração. Diferentemente de Databricks Jobs ou Apps, não existe uma etapa bundle run. Os recursos do Lakebase Postgres ficam ativos assim que são implantados. A documentação dos Declarative Automation Bundles descreve todas as opções, e a agent skill databricks-dabs pode criar e validar bundles.

Máscaras de atualização

Os comandos de atualização exigem uma máscara de atualização que indique quais campos devem ser modificados. O payload --json contém os novos valores. Apenas os campos incluídos na máscara são alterados.

databricks postgres update-branch \
  projects/my-project/branches/production \
  spec.is_protected \
  --json '{"spec": {"is_protected": true}}'

Para vários campos, use uma máscara de atualização separada por vírgulas (por exemplo, spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu).

Solução de problemas

Para problemas de configuração de Databricks Apps (recursos em databricks.yml e app.yaml), consulte Add a Lakebase resource to a Databricks app, que traz a referência de recursos e variáveis de ambiente. Para problemas de conexão, incluindo o despertar após ociosidade e o formato do endpoint, consulte Troubleshooting in Connect external apps, que traz as correções.

• permission denied for schema app (app implantado): npm run dev foi executado antes de databricks apps deploy, de modo que o schema pertence às suas credenciais pessoais e o service principal do app não consegue acessá-lo. (No PostgreSQL, a propriedade de um schema está vinculada à role que o criou e não pode ser reatribuída por usuários comuns.) Se houver dados a preservar, exporte-os (com pg_dump ou copiando as tabelas para um schema temporário) antes de removê-lo. Em seguida, remova o schema e reimplante para que o SP o recrie na inicialização: databricks psql --project <project-id> -- -c "DROP SCHEMA IF EXISTS app CASCADE;" e depois databricks apps deploy.
• permission denied for schema app (desenvolvimento local, colaborador): Somente quem criou o projeto Lakebase recebe acesso databricks_superuser automaticamente. Para conceder acesso local a um colega de equipe, o criador deve adicionar uma role para a identidade dele na branch (Roles & Databases na interface do Lakebase) ou configurar a autenticação por senha do Postgres. Consulte About authentication para ver os passos.
• Unknown field path in update_mask: 'spec.suspend_timeout_duration': Use spec.suspension como máscara de atualização para todas as alterações de suspensão em nível de endpoint feitas com update-endpoint. Para desativar o scale to zero, informe {"spec": {"no_suspension": true}}. Para alterar o tempo limite, informe {"spec": {"suspend_timeout_duration": "300s"}}. Não há suporte para definir no_suspension: false.
• Conexão recusada após período de inatividade: O Autoscaling do Lakebase faz scale to zero quando o recurso está ocioso. A primeira conexão após a inatividade dispara o despertar e pode sofrer um pequeno atraso. Se a sua biblioteca de conexão não fizer novas tentativas automaticamente, adicione um breve laço de repetição.

Documentação do AppKit

Acesse a referência da API do AppKit, a documentação dos componentes e a dos plugins direto pelo terminal:

npx @databricks/appkit docs                    # navegar pelo índice da documentação
npx @databricks/appkit docs "lakebase"         # ver a documentação do plugin do Lakebase Postgres

Ou consulte a referência do plugin Lakebase Postgres do AppKit neste site.

Próximos passos

Os templates abrangem padrões comuns do Lakebase Postgres. Explore-os para encontrar um ponto de partida ou copie um deles para o seu agente de codificação e faça o scaffold de um app funcional.