Configuration de Lakebase Postgres

AppKit se connecte à Lakebase Postgres via une ressource postgres déclarée dans databricks.yml et la variable LAKEBASE_ENDPOINT définie dans app.yaml.

Cette page décrit l'intégration côté AppKit. Pour Lakebase à proprement parler (projets, branches, autoscaling, scale to zero), consultez la documentation Lakebase ou l'agent skill databricks-lakebase.

Valeurs de connexion

Databricks Apps injecte la plupart des valeurs de connexion au démarrage. LAKEBASE_ENDPOINT fait exception : cette variable est déclarée dans app.yaml via valueFrom: postgres et résolue au démarrage à partir de la ressource postgres :

env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres

En développement local, ces valeurs proviennent de votre fichier .env. La page Configuration locale explique comment les renseigner.

Manifeste des plugins

Lorsque vous enregistrez le plugin lakebase() dans createApp, AppKit génère le fichier appkit.plugins.json, qui déclare les ressources requises par le plugin. Exécutez npx @databricks/appkit plugin sync --write pour le régénérer après avoir ajouté ou modifié des plugins :

npx @databricks/appkit plugin sync --write

Cela s'exécute automatiquement lors des commandes npm run dev et npm run build. Versionnez ce fichier avec votre code.

La référence Configuration d'AppKit détaille les resource bindings de plugins dans app.yaml.

Hiérarchie des ressources

Lakebase Postgres organise les ressources en projets qui contiennent des branches, lesquelles contiennent à leur tour des computes et des bases de données.

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

• Projet : conteneur de premier niveau. Créé avec databricks postgres create-project.
• Branch : environnement de base de données isolé. Les nouveaux projets disposent par défaut d'une branch production contenant une base de données databricks_postgres.
• Compute : fournit la puissance de traitement et la mémoire d'une branch. Chaque branch se voit attribuer automatiquement un compute primary en lecture-écriture. Des réplicas en lecture seule peuvent être ajoutés pour faire monter en charge les lectures.
• Base de données : une base de données PostgreSQL au sein d'une branch. Listez-les avec databricks postgres list-databases <branch>.

La CLI et l'API désignent les computes sous le terme d'endpoints (ENDPOINT_TYPE_READ_WRITE pour la lecture-écriture, ENDPOINT_TYPE_READ_ONLY pour les read replicas). Les commandes et les chemins de ressources de ce document reprennent cette terminologie.

La référence de la CLI postgres couvre l'ensemble des commandes databricks postgres.

Création de branches

Les branches créent des environnements de base de données isolés. Lorsque vous créez une branche, Lakebase Postgres copie le schéma et les données de la branche source par copie sur écriture. La création d'une branche est instantanée et vous ne payez que pour les données que vous modifiez.

Chaque nouvelle branche reçoit un endpoint en lecture-écriture primary à l'adresse projects/{project_id}/branches/{branch_id}/endpoints/primary, qui hérite des default_endpoint_settings du projet. Utilisez create-endpoint pour ajouter des read replicas (ENDPOINT_TYPE_READ_ONLY).

Les branches nécessitent une politique d'expiration (ttl, expire_time ou no_expiry: true). La page Branch expiration détaille toutes les options. Pour les commandes CLI, la section Feature branches fournit des exemples.

Autoscaling

Les computes se mettent à l'échelle automatiquement entre un minimum et un maximum d'unités de calcul (CU) configurés. Vous définissez cette plage par projet ou par endpoint. Les valeurs CU par défaut, la taille de compute maximale et la contrainte min/max sont des paramètres Lakebase susceptibles d'évoluer ; consultez donc Autoscaling pour connaître les valeurs actuelles.

La mise à l'échelle au sein de la plage configurée s'effectue sans interruption des connexions. En revanche, modifier le minimum ou le maximum peut provoquer une brève interruption.

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

Scale to zero

Le scale to zero suspend les computes inactifs pour supprimer les coûts associés. Dès qu'une nouvelle requête arrive, le compute redémarre automatiquement (en général en quelques centaines de millisecondes).

Le délai d'expiration par défaut est de 24 heures. Vous pouvez définir n'importe quelle valeur entre 60 secondes et 7 jours. Pour les branches de développement, des délais plus courts (30 minutes, par exemple) réduisent encore les coûts. Les applications connectées à un compute suspendu subiront une brève pause lors de la première requête : prévoyez une logique de nouvelle tentative de connexion dans votre application.

Au redémarrage d'un compute, le contexte de session est réinitialisé (tables temporaires, requêtes préparées, paramètres de session, pools de connexions).

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

Pour aller plus loin

Consultez Développement avec Lakebase Postgres pour la configuration locale, les feature branches et l'API complète du plugin, ou parcourez le catalogue de modèles pour découvrir des patterns complets.