Prise en main de l’interface CLI Databricks pour Lakebase

Ce guide vous aide à bien démarrer avec l’interface CLI Databricks pour gérer vos projets, branches et calculs Lakebase (points de terminaison). Vous allez apprendre à créer un projet de travail en quelques commandes seulement.

Pour obtenir des informations de référence complètes sur les commandes et toutes les options disponibles, consultez les commandes postgres de l’interface CLI Databricks.

Prerequisites

  • Interface CLI Databricks : installez l’interface CLI Databricks. Consultez Installer l’interface CLI Databricks.
  • Accès à l’espace de travail : vous devez avoir accès à un espace de travail Azure Databricks où réside votre ressource Lakebase.

S’authentifier avec Azure Databricks

Avant d’exécuter des commandes CLI, authentifiez-vous auprès de votre espace de travail Azure Databricks :

databricks auth login --host https://your-workspace.cloud.databricks.com

Remplacez https://your-workspace.cloud.databricks.com par l’URL de votre espace de travail réel. Cette commande ouvre une fenêtre de navigateur pour vous permettre de vous authentifier auprès de votre compte Azure Databricks à l’aide d’OAuth.

Note

Si vous avez plusieurs profils, utilisez l’indicateur --profile pour spécifier celui à utiliser : databricks postgres <command> --profile my-profile. Pour afficher vos profils configurés, exécutez databricks auth profiles.

Pour plus d’options d’authentification, consultez l’authentification Databricks.

Obtenir de l’aide sur les commandes

L’interface CLI fournit de l’aide intégrée pour toutes les commandes. Permet --help d’afficher les commandes et options disponibles.

Obtenez une vue d’ensemble de toutes les commandes Postgres :

databricks postgres --help

La commande affiche toutes les commandes disponibles, les indicateurs globaux et les informations sur les conventions d’affectation de noms des ressources.

Obtenez une aide détaillée pour une commande spécifique :

databricks postgres create-project --help

Cela montre l’objectif de la commande, les paramètres obligatoires et facultatifs, les exemples d’utilisation et les indicateurs disponibles.

Démarrage rapide : Créer votre premier projet

Procédez comme suit pour créer un projet avec une branche et un point de terminaison de calcul :

1. Créer un projet

Créez un projet Lakebase :

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

Cette commande crée un projet et attend qu’il se termine. L’ID de projet (my-project) fait partie du nom de la ressource : projects/my-project. Le projet est créé avec une branche de production par défaut et un point de terminaison de calcul en lecture-écriture, tous deux ayant des identifiants générés automatiquement.

Si vous le souhaitez, exportez l’ID de projet en tant que variable à utiliser dans les commandes suivantes :

export PROJECT_ID="my-project"

2. Obtenir l’ID de branche

Répertoriez les branches de votre projet pour trouver l’ID de branche par défaut :

databricks postgres list-branches projects/$PROJECT_ID

Cela retourne des informations sur toutes les branches du projet. Recherchez la branche avec "default": true dans l’état. Notez l’ID de branche du name champ (par exemple, production pour la branche par défaut).

Exportez éventuellement l’ID de branche en tant que variable à utiliser dans les commandes suivantes :

export BRANCH_ID="production"

Remplacez production par votre identifiant de branche réel dans la liste de sortie.

3. Obtenir l’ID de point de terminaison

Répertoriez les points de terminaison dans votre branche. La branche par défaut inclut automatiquement un point de terminaison en lecture-écriture :

databricks postgres list-endpoints projects/$PROJECT_ID/branches/$BRANCH_ID

Notez l’ID de point de terminaison du name champ (par exemple, primary pour le point de terminaison en lecture-écriture par défaut). Si vous le souhaitez, exportez-le en tant que variable :

export ENDPOINT_ID="primary"

Remplacez primary par votre ID de point de terminaison réel à partir de la sortie de la liste.

4. Générer des informations d’identification de base de données

Générez des informations d’identification pour vous connecter à votre base de données :

databricks postgres generate-database-credential \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

La commande retourne un jeton OAuth que vous pouvez utiliser avec des clients PostgreSQL comme psql pour accéder à vos données à l’aide de votre identité Databricks. Pour obtenir des instructions pas à pas sur la connexion avec psql, consultez Se connecter avec psql. Pour plus d’informations sur l’expiration et l’authentification des jetons, consultez Authentification.

Gérer les projets

Répertorier les projets

Répertoriez tous les projets de votre espace de travail :

databricks postgres list-projects

La commande renvoie le nom, le nom d’affichage, l’état actuel et les horodatages de chaque projet.

Obtenir les détails du projet

Obtenez des informations détaillées sur un projet :

databricks postgres get-project projects/$PROJECT_ID

La commande retourne le nom complet du projet, la version PostgreSQL, le propriétaire, la période de rétention de l’historique, les limites de taille de branche, la taille du stockage et les horodatages.

Gérer les branches

Obtenir les détails de la branche

Obtenez des informations détaillées sur une branche :

databricks postgres get-branch projects/$PROJECT_ID/branches/$BRANCH_ID

La commande retourne l’état actuel de la branche, l’état de la protection, la taille logique, les détails de la branche source (le cas échéant) et les horodatages.

Créer une branche de fonctionnalité

Créez une branche basée sur une branche existante pour tester les modifications. Lorsque vous spécifiez un source_branch, la nouvelle branche aura le même schéma et les mêmes données que la branche source au moment de la création. Remplacez les ID de projet et de branche par vos valeurs réelles :

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

Note

Lors de la création d’une branche, vous devez spécifier une stratégie d’expiration. Utilisez no_expiry: true pour créer une branche permanente.

Pour utiliser des variables shell à l’intérieur de la spécification JSON (comme $PROJECT_ID ou $BRANCH_ID), utilisez des guillemets doubles pour la --json valeur et échappez les guillemets internes.

Lakebase crée automatiquement la branche fonctionnelle avec un point de terminaison principal de calcul en lecture-écriture. Une fois le développement et le test terminés sur la branche de fonctionnalité, vous pouvez le supprimer :

databricks postgres delete-branch projects/$PROJECT_ID/branches/feature

Note

Les commandes de suppression retournent immédiatement, mais la suppression réelle peut prendre du temps. Vous pouvez vérifier la suppression en exécutant la commande get resource correspondante, qui retourne une erreur une fois la ressource entièrement supprimée.

Mise à jour de la protection des branches

Mettez à jour une ressource à l’aide du modèle de masque de mise à jour. Le masque de mise à jour spécifie les champs à mettre à jour :

databricks postgres update-branch \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  spec.is_protected \
  --json '{
    "spec": {
      "is_protected": true
    }
  }'

Cet exemple définit spec.is_protected sur true, ce qui rend la branche protégée. Le masque de mise à jour (spec.is_protected) indique à l’API quel champ mettre à jour. La commande retourne la ressource mise à jour montrant la nouvelle valeur et un horodatage mis à jour update_time .

Gérer les calculs

Obtenir les détails du calcul

Obtenez des informations détaillées sur un point de terminaison :

databricks postgres get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

La commande renvoie le type de point de terminaison, les paramètres de mise à l’échelle automatique, l’état actuel, l’hôte de connexion, le délai d’expiration de suspension et les horodatages.

Lecture de la mise à l’échelle avec des réplicas en lecture

Ajoutez des réplicas en lecture pour gérer le trafic de lecture accru. L’exemple suivant ajoute un réplica en lecture à la branche de production par défaut :

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  read-replica-1 \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_ONLY",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 4.0
    }
  }'

Vous pouvez créer plusieurs réplicas en lecture avec différents ID de point de terminaison (read-replica-1, read-replica-2, etc.) pour distribuer des charges de travail de lecture.

Mettre à jour les limites de mise à l’échelle automatique

Pour mettre à jour plusieurs champs, utilisez une liste séparée par des virgules :

databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{
    "spec": {
      "autoscaling_limit_min_cu": 1.0,
      "autoscaling_limit_max_cu": 8.0
    }
  }'

Configurer la mise à l’échelle à zéro

Pour configurer la mise à l’échelle sur zéro, incluez spec.suspension dans le masque de mise à jour. Définissez suspend_timeout_duration (60s-604800s) pour définir le délai d’inactivité ou no_suspension: true pour le désactiver. Ne les définissez pas ensemble. Le paramètre no_suspension: false n’est pas valide et retourne une erreur. Par défaut, la branche production a l’option de mise à l’échelle à zéro activée, avec un délai d’expiration de 24 heures.

# Disable scale to zero (compute stays active indefinitely)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "no_suspension": true
    }
  }'

# Enable scale to zero with a 5-minute inactivity timeout (60s–604800s)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "suspend_timeout_duration": "300s"
    }
  }'

Gestion des rôles

Utilisez l’interface CLI pour créer et gérer des rôles Postgres pour l’accès à la base de données dans une branche. Pour obtenir des instructions détaillées sur les types de rôles et l’authentification, consultez Créer des rôles Postgres.

Créer un rôle

Créez un rôle basé sur un mot de passe :

databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

Créez un rôle OAuth lié à une identité Azure Databricks :

# For a user:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

# For a service principal:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "<sp-client-id>"}}'

Répertorier et obtenir des rôles

Répertorier tous les rôles dans une branche :

databricks postgres list-roles projects/$PROJECT_ID/branches/$BRANCH_ID

Obtenez des détails sur un rôle spécifique :

databricks postgres get-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

La réponse inclut le nom de ressource de rôle généré par le système (par exemple, rol-xxxx-xxxxxxxxxx) requis pour les appels de mise à jour et de suppression.

Mettre à jour un rôle

Mettez à jour un rôle à l’aide du modèle de masque de mise à jour. Passez le masque de mise à jour comme deuxième argument positionnel.

Lors de la mise à jour spec.attributes, vous devez fournir les trois champs d’attribut : l’API remplace l’ensemble de l’objet attributs :

databricks postgres update-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  "spec.attributes" \
  --json '{"spec": {"attributes": {"createdb": true, "createrole": false, "bypassrls": false}}}'

Supprimer un rôle

databricks postgres delete-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

Si le rôle possède des objets de base de données, utilisez-le --reassign-owned-to pour transférer la propriété avant la suppression :

databricks postgres delete-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  --reassign-owned-to projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$OTHER_ROLE_ID

Gestion des tables synchronisées

Les tables synchronisées répliquent les données Unity Catalog dans votre base de données Lakebase pour des lectures opérationnelles à faible latence. Utiliser create-synced-table avec un {catalog}.{schema}.{table} ID :

databricks postgres create-synced-table my-catalog.sales.orders \
  --json '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "databricks_postgres",
      "create_database_objects_if_missing": true
    }
  }'

L’ID de table synchronisé devient à la fois le nom de l’entité catalogue Unity et identifie la table Postgres. Obtenez l’état et supprimez une table synchronisée avec le même format d’ID :

# Check status
databricks postgres get-synced-table "synced_tables/my-catalog.sales.orders"

# Delete
databricks postgres delete-synced-table "synced_tables/my-catalog.sales.orders"

create-synced-table et create-catalog sont des opérations de longue durée. Par défaut, l’interface de ligne de commande attend la fin de l’exécution. Permet --no-wait de retourner immédiatement ou --timeout de définir une durée d’attente personnalisée. Consultez les opérations de longue durée.

Pour obtenir des conseils détaillés sur les modes de synchronisation, le mappage des types de données et la planification de la capacité, consultez Servir les données lakehouse avec des tables synchronisées.

Présentation des concepts clés

Opérations de longue durée

Les commandes Créer, mettre à jour et supprimer sont des opérations de longue durée. Par défaut, l’interface CLI attend que l’opération se termine. Utilisez --no-wait pour un retour immédiat et interroger l'état séparément :

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

Consultez l’état du fonctionnement :

databricks postgres get-operation projects/$PROJECT_ID/operations/operation-id

Nommage des ressources

Lakebase utilise des noms de ressources hiérarchiques :

  • Projets : projects/{project_id}. Vous spécifiez l’ID de projet lors de la création d’un projet.
  • Branches : projects/{project_id}/branches/{branch_id}. Vous spécifiez l’ID de branche lors de la création d’une branche.
  • Points de terminaison : projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Vous spécifiez l’ID de point de terminaison (par primary exemple ou read-replica-1) lors de la création d’un point de terminaison.

Les ID doivent comporter 1 à 63 caractères, commencer par une lettre minuscule et contenir uniquement des lettres minuscules, des chiffres et des traits d’union.

Mettre à jour des masques

Les commandes de mise à jour nécessitent un masque de mise à jour qui spécifie les champs à modifier. Le masque est un chemin de champ, comme spec.display_name, ou une liste de chemins séparés par des virgules pour plusieurs champs.

La --json charge utile contient les nouvelles valeurs de ces champs. Seuls les champs répertoriés dans le masque de mise à jour sont modifiés.

Ressources supplémentaires

  • Dernière mise à jour :