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.

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 de travail complet 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.

Gestion de vos ressources

Répertorier tous les projets

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

databricks postgres list-projects

La commande retourne des informations sur chaque projet, y compris son nom, son nom complet et son état actuel. Il inclut également la création et la mise à jour des horodatages.

Obtenir les détails de la ressource

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

databricks postgres get-project projects/$PROJECT_ID

La commande retourne une configuration détaillée du projet, y compris le nom d’affichage, la version PostgreSQL, le propriétaire et la période de rétention de l’historique. Il inclut également les limites de taille de branche, les paramètres de point de terminaison par défaut, la taille de stockage et la création et la mise à jour des horodatages.

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

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

La commande retourne des informations détaillées sur les branches, notamment l’état actuel, l’état de la branche par défaut, l’état de la protection et la taille logique. Il comprend également les détails de la branche source (si elle provient d'une autre branche) et les horodatages de création et de mise à jour.

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 retourne une configuration détaillée du point de terminaison, notamment le type de point de terminaison (lecture-écriture ou lecture seule), les paramètres de mise à l’échelle automatique (unités de calcul minimales et maximales) et l’état actuel (ACTIVE, IDLE, etc.). Il inclut également l’hôte de connexion, le délai d’attente de suspension, et les horodatages de création et de mise à jour.

Mettre à jour les ressources

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 .

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

Flux de travail courants

Créer une branche de fonctionnalité à partir de la production

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

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

Mettre à l’échelle les lectures 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 de lecture avec différents ID de point de terminaison (read-replica-1, read-replica-2, etc.) pour distribuer des charges de travail de lecture.

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

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 retourner immédiatement 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.

Étapes suivantes

• Informations de référence sur les commandes postgres de l’interface CLI Databricks
• Créer des rôles Postgres
• Se connecter avec psql
• Gérer des branches
• Configurer la mise à l’échelle automatique