Partager via

Prise en main de l’interface CLI Databricks pour Lakebase

Important

La mise à l’échelle automatique Lakebase est en version bêta dans les régions suivantes : eastus2, westeurope, westus.

La version Autoscaling de Lakebase est la dernière de Lakebase, offrant l'autoscaling, la mise à l'échelle à zéro, la bifurcation et la restauration instantanée. Pour la comparaison des fonctionnalités avec Lakebase Provisioned, consultez le choix entre les versions.

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 auprès de 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

Cela 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, br-divine-sea-y2k942xa).

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

export BRANCH_ID="br-divine-sea-y2k942xa"

Remplacez br-divine-sea-y2k942xa par votre ID de branche par défaut réel à partir de la sortie de la liste.

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. Il sera au format projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Extrayez l’ID de point de terminaison (par exemple) ep-plain-sunset-y2vc0zanet exportez-le éventuellement en tant que variable :

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

Remplacez ep-plain-sunset-y2vc0zan 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

Cela retourne des informations sur chaque projet, y compris son nom, son nom d’affichage, son état actuel et ses horodatages de création/mise à jour.

Obtenir les détails de la ressource

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

databricks postgres get-project projects/$PROJECT_ID

Cette opération retourne une configuration détaillée du projet, notamment le nom complet, la version PostgreSQL, le propriétaire, la période de rétention de l’historique, les limites de taille de branche, les paramètres de point de terminaison par défaut, la taille du stockage et les horodatages de création/mise à jour.

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

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

Cela retourne des informations détaillées sur la branche, notamment l’état actuel, le statut de la branche par défaut, le statut de la protection, la taille logique, les détails de la branche source (si elle est issue d'une autre branche) ainsi que 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

Cette opération renvoie 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), l’état actuel (ACTIVE, INACTIF, etc.), l’hôte de connexion, le délai d’attente d’interruption, ainsi que 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/br-divine-sea-y2k942xa",
      "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), vous devez utiliser des guillemets doubles pour la --json valeur et échapper les guillemets internes.

La branche de fonctionnalité a besoin d’un point de terminaison de calcul en lecture-écriture pour autoriser les opérations de base de données :

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

Une fois votre développement et votre test effectué 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.

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. Cet exemple ajoute une réplique 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.

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

  • Last updated on