Desenvolvimento de apps

Esta página é a referência de CLI e de fluxos de trabalho para Databricks Apps e AppKit. Ela cobre como adicionar plugins, gerar a estrutura inicial, implantar, gerenciar e solucionar problemas do seu app.

Cada comando abaixo mostra uma invocação comum, seu conjunto completo de flags e uma tabela descrevendo cada uma delas. Execute databricks <command> --help para conferir o comportamento atual das flags, já que a CLI é a fonte da verdade.

Configuração local

Copie .env.example para .env e preencha a URL do seu workspace e os IDs dos recursos antes de executar npm run dev. O AppKit lê esses valores para as conexões locais com os recursos do Databricks.

Exemplo de .env para um app com Lakebase Postgres:

DATABRICKS_HOST=https://<workspace>.cloud.databricks.com
LAKEBASE_ENDPOINT=projects/<project>/branches/production/endpoints/primary

Se o seu app usa Lakebase, conceda também ao seu usuário local a função databricks_superuser antes de executá-lo localmente. O service principal do app cria os schemas e as tabelas na primeira implantação e se torna o proprietário deles. Sem essa concessão, sua identidade local não conseguirá acessar esses objetos:

GRANT databricks_superuser TO "<your-email>";

Consulte Desenvolvimento com Lakebase para ver o fluxo completo de acesso local.

Para testar com dados de produção sem precisar reimplantar, consulte o remote bridge.

Adicionar um plugin

Para adicionar um plugin a um app existente, importe-o e registre-o em createApp, no arquivo server/server.ts:

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

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

Em seguida, regenere o appkit.plugins.json com os requisitos de recursos atualizados:

npx @databricks/appkit plugin sync --write

Isso é executado automaticamente durante npm run dev e npm run build. Faça o commit do appkit.plugins.json atualizado junto com o seu código. É ele que informa ao pipeline de implantação quais recursos provisionar.

Consulte a referência de plugins do AppKit para ver as opções de configuração de cada plugin, ou Criando plugins personalizados para adicionar os seus próprios.

Descobrir plugins

Liste os plugins disponíveis e os campos de recurso obrigatórios de cada um:

databricks apps manifest

Opções de scaffold

Use databricks apps init para gerar a estrutura de um novo projeto AppKit. O Início rápido de Apps apresenta o caminho mais direto. Use estas opções para scaffolding não interativo ou avançado.

databricks apps init --name my-app

Passar --name suprime os prompts e aplica os valores padrão às opções não especificadas. Os nomes de apps devem estar em minúsculas, separados por hífen e ter no máximo 26 caracteres. Execute databricks apps manifest para ver os plugins disponíveis e suas chaves de --set.

Configuração de ambiente

Local (npm run dev): variáveis do arquivo .env na raiz do projeto.

Implantado: variáveis das entradas env do app.yaml. Use value para strings simples e valueFrom para vínculos de recursos:

env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres
  - name: WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: APP_LOG_LEVEL
    value: info

Os recursos referenciados por valueFrom devem ser declarados no databricks.yml. Consulte Configuração do app para ver a lista completa de recursos.

Checklist pré-implantação

Antes de implantar em produção:

• O app escuta em 0.0.0.0 na porta DATABRICKS_APP_PORT
• O comando em app.yaml usa sintaxe de array (sem strings de shell)
• Nenhum arquivo maior que 10 MB no projeto
• Os segredos usam valueFrom (nunca value)
• O databricks.yml declara todos os recursos necessários
• O databricks apps validate é concluído com sucesso (--skip-tests ignora os testes para uma execução mais rápida)
• O npm run build é concluído com sucesso localmente

Validar

Execute a validação a partir do diretório do projeto do seu app antes de implantar:

databricks apps validate --profile $DATABRICKS_PROFILE

A validação executa build, verificação de tipos e lint. Passe --skip-tests para uma execução mais rápida.

Implantar

databricks apps deploy

A CLI valida a configuração, compila o projeto, faz o upload e inicia o app. Por padrão, executa a mesma validação de projeto que databricks apps validate (build, typecheck, lint). Use --skip-validation para pular essa etapa. Não é necessário informar --source-code-path ao implantar a partir de um projeto AppKit criado por scaffolding.

Verifique a implantação

Confira se o app foi implantado com sucesso:

databricks apps get my-app -o json

{
  "name": "my-app",
  "url": "https://my-app-1234567890.us-west-2.databricksapps.com",
  "description": "A Databricks App powered by AppKit",
  "compute_size": "MEDIUM",
  "app_status": {
    "message": "App has status: App is running",
    "state": "RUNNING"
  },
  "compute_status": {
    "message": "App compute is running.",
    "state": "ACTIVE"
  },
  "active_deployment": {
    "deployment_id": "a1b2c3d4e5f6",
    "source_code_path": "/Workspace/Users/you@example.com/.bundle/my-app/default/files",
    "status": {
      "message": "App started successfully",
      "state": "SUCCEEDED"
    }
  },
  "resources": [
    {
      "name": "postgres",
      "postgres": {
        "branch": "projects/my-project/branches/production",
        "database": "projects/my-project/branches/production/databases/db-abc123",
        "permission": "CAN_CONNECT_AND_CREATE"
      }
    }
  ],
  "service_principal_client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Visualize os logs:

databricks apps logs my-app

[SYSTEM] [INFO] Starting Databricks Apps runtime...
[SYSTEM] [INFO] Starting deployment a1b2c3d4e5f6...
[SYSTEM] [INFO] Downloading source code from /Workspace/Users/.../src/a1b2c3d4e5f6
[SYSTEM] [INFO] Installing dependencies...
[BUILD] added 899 packages, and audited 900 packages in 21s
[SYSTEM] [INFO] Dependencies installed successfully.
[SYSTEM] [INFO] Running build script npm run build:server && npm run build:client
[BUILD] ✔ Build complete in 30ms
[BUILD] ✓ built in 2.80s
[SYSTEM] [INFO] Build completed successfully.
[SYSTEM] [INFO] Starting app with command: [npm run start]
[APP] [appkit:lakebase] Lakebase pool initialized
[APP] [appkit:server] Server running on http://0.0.0.0:8000
[APP] [appkit:server] Mode: production (static)

Gerenciamento de apps

databricks apps stop my-app
databricks apps start my-app
databricks apps delete my-app

Opções de apps stop

Opções de apps start

Opções do apps delete

O apps delete pede confirmação. Use --auto-approve em CI para pular a confirmação.

CI/CD

Para deploys automatizados em CI, defina DATABRICKS_HOST e DATABRICKS_TOKEN (ou use OAuth com DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET):

DATABRICKS_HOST=https://<workspace>.cloud.databricks.com \
DATABRICKS_TOKEN=dapi... \
databricks apps deploy

Ou use um perfil pré-configurado:

databricks apps deploy --profile ci-profile

Consulte a documentação de autenticação da Databricks CLI para ver todos os métodos de autenticação.

Solução de problemas

Para mais informações sobre solução de problemas, consulte Deploy apps e o AppKit remote bridge em caso de problemas de conexão local.

• Falha ao implantar o app: verifique as mensagens de erro nos logs, valide a sintaxe do app.yaml e confirme se os segredos e as variáveis de ambiente da seção env são resolvidos corretamente. Confirme também que todas as dependências estão incluídas ou instaladas.
• Erros 401 (autenticação): verifique se o seu token é válido (databricks auth token --profile <PROFILE>), se não expirou e se inclui os escopos de OAuth necessários. Os escopos do token devem ser um superconjunto dos escopos configurados para a autorização de usuário do app.
• Erros 403 (permissão negada): verifique se você tem a permissão CAN USE no app. Escopos de OAuth insuficientes também podem gerar erros 403, mesmo com as permissões corretas.
• Erros 404 (app não encontrado): verifique se o nome do app e a URL do workspace estão corretos, se o app está implantado e em execução e se o caminho do endpoint existe.
• Falha na implantação via Git: em repositórios privados, verifique se o service principal do app tem uma credencial Git configurada. Se a implantação for feita por CLI/API/DABs, crie o app primeiro e depois adicione a credencial Git.

Documentação do AppKit

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

npx @databricks/appkit docs                        # navegue pelo índice da documentação
npx @databricks/appkit docs --full                 # índice completo com todas as entradas da API
npx @databricks/appkit docs "<query-or-doc-path>"  # veja uma seção ou arquivo específico

Execute sem argumentos para navegar pelo índice. Útil ao desenvolver com um assistente de codificação com IA. Aponte-o para cá em vez de adivinhar os formatos das APIs, ou consulte a referência do AppKit neste site.

Próximos passos

Explore o catálogo de templates para começar a desenvolver ou adicione recursos ao seu app: Lakebase Postgres para armazenamento persistente ou Agent Bricks para funcionalidades de IA.