Développement d'applications

Cette page sert de référence CLI et de guide des flux de travail pour Databricks Apps et AppKit. Elle couvre l'ajout de plugins, la génération de projet (scaffolding), le déploiement, la gestion et le dépannage de votre application.

Chaque commande ci-dessous est présentée avec une invocation courante, la liste complète de ses options et un tableau décrivant chacune d'elles. Exécutez databricks <command> --help pour connaître le comportement actuel des options : la CLI fait foi.

Configuration locale

Copiez .env.example vers .env, puis renseignez l'URL de votre workspace et les identifiants de vos ressources avant d'exécuter npm run dev. AppKit s'appuie sur ces valeurs pour établir les connexions locales aux ressources Databricks.

Exemple de fichier .env pour une application utilisant Lakebase Postgres :

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

Si votre application utilise Lakebase, accordez également le rôle databricks_superuser à votre utilisateur local avant de l'exécuter en local. Le service principal de l'application crée les schémas et les tables lors du premier déploiement et en devient propriétaire. Sans cette autorisation, votre identité locale ne peut pas accéder à ces objets :

GRANT databricks_superuser TO "<your-email>";

Consultez Développement Lakebase pour découvrir le workflow complet d'accès local.

Pour tester sur des données de production sans redéployer, consultez le pont distant.

Ajouter un plugin

Pour ajouter un plugin à une application existante, importez-le et enregistrez-le dans createApp, au sein de server/server.ts :

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

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

Régénérez ensuite appkit.plugins.json avec les besoins en ressources mis à jour :

npx @databricks/appkit plugin sync --write

Cette opération s'exécute automatiquement lors de npm run dev et npm run build. Commitez le fichier appkit.plugins.json mis à jour avec votre code : c'est lui qui indique au pipeline de déploiement les ressources à provisionner.

Consultez la référence des plugins AppKit pour les options de configuration de chaque plugin, ou Créer des plugins personnalisés pour ajouter les vôtres.

Découvrir les plugins

Répertoriez les plugins disponibles et les champs de ressources qu'ils requièrent :

databricks apps manifest

Options de scaffold

Utilisez databricks apps init pour générer le scaffold d'un nouveau projet AppKit. Le Démarrage rapide Apps présente la méthode la plus rapide. Ces options permettent un scaffolding non interactif ou avancé.

databricks apps init --name my-app

L'option --name désactive les invites et applique les valeurs par défaut aux options non spécifiées. Les noms d'applications doivent être en minuscules, séparés par des traits d'union et comporter au maximum 26 caractères. Exécutez databricks apps manifest pour afficher les plugins disponibles et leurs clés --set.

Configuration de l'environnement

En local (npm run dev) : les variables proviennent du fichier .env situé à la racine du projet.

Une fois déployé : les variables proviennent des entrées env de app.yaml. Utilisez value pour les chaînes de caractères simples et valueFrom pour les resource bindings :

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

Les ressources référencées par valueFrom doivent être déclarées dans databricks.yml. Consultez Configuration de l'application pour la liste complète des ressources.

Liste de contrôle avant déploiement

Avant de déployer en production :

• L'application écoute sur 0.0.0.0, sur le port DATABRICKS_APP_PORT
• La commande de app.yaml utilise la syntaxe tableau (pas de chaîne shell)
• Aucun fichier de plus de 10 Mo dans le projet
• Les secrets utilisent valueFrom (jamais value)
• databricks.yml déclare toutes les ressources requises
• databricks apps validate s'exécute sans erreur (--skip-tests ignore les tests pour une exécution plus rapide)
• npm run build aboutit en local

Valider

Lancez la validation depuis le répertoire de votre projet d'application avant de déployer :

databricks apps validate --profile $DATABRICKS_PROFILE

La validation exécute une compilation, une vérification des types et une analyse statique. Passez --skip-tests pour une exécution plus rapide.

Déploiement

databricks apps deploy

La CLI valide la configuration, compile le projet, le téléverse et démarre l'app. Par défaut, elle exécute la même validation de projet que databricks apps validate (build, typecheck, lint). Utilisez --skip-validation pour ignorer cette étape. L'option --source-code-path est inutile lors d'un déploiement depuis un projet AppKit généré par scaffold.

Vérifier le déploiement

Vérifiez que l'application a bien été déployée :

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

Consultez les journaux :

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)

Gestion des applications

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

Options de apps stop

Options de apps start

Options de apps delete

apps delete demande une confirmation. Passez --auto-approve en CI pour ignorer cette invite.

CI/CD

Pour automatiser les déploiements en CI, définissez DATABRICKS_HOST et DATABRICKS_TOKEN (ou utilisez OAuth avec DATABRICKS_CLIENT_ID et DATABRICKS_CLIENT_SECRET) :

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

Ou utilisez un profil préconfiguré :

databricks apps deploy --profile ci-profile

Consultez la documentation sur l'authentification de la Databricks CLI pour connaître toutes les méthodes d'authentification.

Dépannage

Pour aller plus loin, consultez Deploy apps ainsi que le pont distant AppKit pour les problèmes de connexion locale.

• Le déploiement de l'app échoue : consultez les journaux pour repérer les messages d'erreur, validez la syntaxe du fichier app.yaml et vérifiez que les secrets et les variables d'environnement de la section env se résolvent correctement. Assurez-vous que toutes les dépendances sont incluses ou installées.
• Erreurs 401 (authentification) : vérifiez que votre jeton est valide (databricks auth token --profile <PROFILE>), qu'il n'a pas expiré et qu'il inclut les scopes OAuth requis. Les scopes de votre jeton doivent former un sur-ensemble de ceux configurés pour l'autorisation utilisateur de l'app.
• Erreurs 403 (permission refusée) : vérifiez que vous disposez de la permission CAN USE sur l'app. Des scopes OAuth insuffisants peuvent eux aussi provoquer des erreurs 403, même si les permissions sont correctes.
• Erreurs 404 (app introuvable) : vérifiez que le nom de l'app et l'URL du workspace sont corrects, que l'app est déployée et en cours d'exécution, et que le chemin de l'endpoint existe.
• Le déploiement Git échoue : pour les dépôts privés, vérifiez que le service principal de l'app dispose d'un identifiant Git configuré. Si vous déployez via la CLI, l'API ou les DAB, créez d'abord l'app, puis ajoutez l'identifiant Git.

Documentation AppKit

Accédez à la référence de l'API AppKit, à la documentation des composants et à celle des plugins depuis le terminal :

npx @databricks/appkit docs                        # parcourir l'index de la documentation
npx @databricks/appkit docs --full                 # index complet avec toutes les entrées de l'API
npx @databricks/appkit docs "<query-or-doc-path>"  # afficher une section ou un fichier précis

Exécutez la commande sans argument pour parcourir l'index. Pratique lorsque vous développez avec un assistant de codage IA : orientez-le vers cette ressource plutôt que de le laisser deviner la structure des API, ou consultez la référence AppKit sur ce site.

Pour aller plus loin

Parcourez le catalogue de modèles pour commencer à développer, ou enrichissez votre application de nouvelles capacités : Lakebase Postgres pour le stockage persistant ou Agent Bricks pour les fonctionnalités d'IA.