Desarrollo de aplicaciones

Esta página es la referencia de la CLI y de los flujos de trabajo para Databricks Apps y AppKit. Abarca cómo añadir plugins, hacer scaffolding, desplegar, gestionar y solucionar problemas de tu aplicación.

Cada comando que aparece a continuación muestra una invocación habitual, su conjunto completo de flags y una tabla en la que se describe cada uno. Ejecuta databricks <command> --help para conocer el comportamiento actual de los flags, ya que la CLI es la fuente de verdad.

Configuración local

Copia .env.example a .env y completa la URL de tu workspace y los ID de los recursos antes de ejecutar npm run dev. AppKit los usa para conectarse localmente a los recursos de Databricks.

Ejemplo de .env para una app con Lakebase Postgres:

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

Si tu aplicación usa Lakebase, concede también el rol databricks_superuser a tu usuario local antes de ejecutarla en local. El service principal de la aplicación crea los esquemas y las tablas en el primer despliegue y es su propietario. Sin este permiso, tu identidad local no podrá acceder a esos objetos:

GRANT databricks_superuser TO "<your-email>";

Consulta Desarrollo con Lakebase para conocer el flujo de trabajo completo de acceso local.

Para probar con datos de producción sin volver a desplegar, consulta el puente remoto.

Agregar un plugin

Para agregar un plugin a una app existente, impórtalo y regístralo en createApp, dentro de server/server.ts:

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

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

Luego, regenera appkit.plugins.json con los requisitos de recursos actualizados:

npx @databricks/appkit plugin sync --write

Esto se ejecuta automáticamente durante npm run dev y npm run build. Haz commit del archivo appkit.plugins.json actualizado junto con tu código, ya que indica al pipeline de despliegue qué recursos debe aprovisionar.

Consulta la referencia de plugins de AppKit para conocer las opciones de configuración de cada plugin, o Crear plugins personalizados para añadir los tuyos.

Descubrir plugins

Lista los plugins disponibles y los campos de recurso que requieren:

databricks apps manifest

Opciones de scaffold

Usa databricks apps init para generar el scaffold de un nuevo proyecto de AppKit. La Guía rápida de Apps muestra la vía rápida. Usa estas opciones para un scaffolding no interactivo o avanzado.

databricks apps init --name my-app

Al pasar --name se omiten los mensajes interactivos y se usan los valores por defecto para las opciones no especificadas. Los nombres de las apps deben estar en minúsculas, separados por guiones y no superar los 26 caracteres. Ejecute databricks apps manifest para ver los plugins disponibles y sus claves --set.

Configuración del entorno

Local (npm run dev): variables del archivo .env en la raíz del proyecto.

Desplegado: variables de las entradas env de app.yaml. Usa value para cadenas de texto simples y valueFrom para los resource bindings:

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

Los recursos referenciados mediante valueFrom deben declararse en databricks.yml. Consulta Configuración de la app para ver la lista completa de recursos.

Lista de comprobación previa al despliegue

Antes de desplegar en producción:

• La app escucha en 0.0.0.0 en el puerto DATABRICKS_APP_PORT
• El comando de app.yaml usa sintaxis de array (sin cadenas de shell)
• No hay archivos de más de 10 MB en el proyecto
• Los secrets usan valueFrom (nunca value)
• databricks.yml declara todos los recursos necesarios
• databricks apps validate se ejecuta correctamente (--skip-tests omite las pruebas para acelerar la ejecución)
• npm run build funciona correctamente en local

Validar

Ejecuta la validación desde el directorio del proyecto de tu app antes de desplegarla:

databricks apps validate --profile $DATABRICKS_PROFILE

La validación ejecuta una compilación, una verificación de tipos y el linter. Usa --skip-tests para una ejecución más rápida.

Despliegue

databricks apps deploy

La CLI valida la configuration, compila el proyecto, lo sube e inicia la app. De forma predeterminada ejecuta la misma validación de proyecto que databricks apps validate (build, typecheck, lint). Pasa --skip-validation para omitir ese paso. No hace falta indicar --source-code-path al desplegar desde un proyecto de AppKit generado con scaffold.

Verifica el despliegue

Comprueba que la app se haya desplegado correctamente:

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"
}

Ver los registros:

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)

Gestión de aplicaciones

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

Opciones de apps stop

Opciones de apps start

Opciones de apps delete

apps delete pide confirmación. Usa --auto-approve en CI para omitir esa confirmación.

CI/CD

Para despliegues automatizados en CI, define DATABRICKS_HOST y DATABRICKS_TOKEN (o usa OAuth con DATABRICKS_CLIENT_ID y DATABRICKS_CLIENT_SECRET):

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

O usa un perfil preconfigurado:

databricks apps deploy --profile ci-profile

Consulta la documentación de autenticación de la Databricks CLI para conocer todos los métodos de autenticación.

Solución de problemas

Para obtener más ayuda, consulta Deploy apps y el puente remoto de AppKit si tienes problemas de conexión local.

• La app no se despliega: revisa los registros en busca de mensajes de error, valida la sintaxis de app.yaml y verifica que los secrets y las variables de entorno de la sección env se resuelvan correctamente. Confirma que todas las dependencias estén incluidas o instaladas.
• Errores 401 (autenticación): verifica que tu token sea válido (databricks auth token --profile <PROFILE>), que no haya expirado y que incluya los ámbitos de OAuth necesarios. Los ámbitos de tu token deben ser un superconjunto de los ámbitos configurados para la autorización de usuario de la app.
• Errores 403 (permiso denegado): verifica que tengas el permiso CAN USE sobre la app. Unos ámbitos de OAuth insuficientes también pueden provocar errores 403, incluso con permisos válidos.
• Errores 404 (app no encontrada): verifica que el nombre de la app y la URL del workspace sean correctos, que la app esté desplegada y en ejecución, y que la ruta del endpoint exista.
• Falla el despliegue desde Git: en el caso de repositorios privados, verifica que el service principal de la app tenga configurada una credencial de Git. Si despliegas mediante la CLI, la API o DABs, crea primero la app y luego agrega la credencial de Git.

Documentación de AppKit

Accede a la referencia de la API de AppKit, la documentación de componentes y la de plugins desde la terminal:

npx @databricks/appkit docs                        # explorar el índice de la documentación
npx @databricks/appkit docs --full                 # índice completo con todas las entradas de la API
npx @databricks/appkit docs "<query-or-doc-path>"  # ver una sección o un archivo concreto

Ejecútalo sin argumentos para explorar el índice. Resulta útil cuando desarrollas con un asistente de programación con IA: dirígelo aquí en lugar de dejar que adivine la estructura de las API, o consulta la referencia de AppKit en este sitio.

Siguientes pasos

Explora el catálogo de plantillas para empezar a crear tu app o añádele nuevas capacidades: Lakebase Postgres para almacenamiento persistente o Agent Bricks para funciones de IA.