Aller au contenu principal
Dernière mise à jour le

Démarrer avec le Databricks CLI pour Lakebase

Ce guide vous aide à get start avec la CLI Databricks pour gérer vos projets Lakebase, vos Branches et vos computes (Endpoints). Vous apprendrez comment créer un projet fonctionnel en quelques commandes seulement.

Pour une référence complète des commandes et toutes les options disponibles, consultez commandes Databricks CLI postgres.

Prérequis​

  • CLI Databricks : Installez la CLI Databricks. Consultez Installer la CLI Databricks.
  • Accès au Workspace : Vous devez avoir accès à un Workspace 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 Workspace Databricks :

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

Remplacez https://your-workspace.cloud.databricks.com par l'URL de votre Workspace. Cette commande ouvre une fenêtre de navigateur pour vous authentifier auprès de votre compte Databricks à l'aide d'OAuth.

remarque

Si vous avez plusieurs profils, utilisez l'indicateur --profile pour spécifier lequel 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 l'aide sur la commande​

La CLI fournit une aide intégrée pour toutes les commandes. Utilisez --help pour voir les commandes et options disponibles.

Obtenez un aperçu de toutes les commandes Postgres :

Bash
databricks postgres --help

La commande affiche toutes les commandes disponibles, les indicateurs globaux et les informations sur les conventions de nommage des ressources.

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

Bash
databricks postgres create-project --help

Ceci indique l'objectif de la commande, les paramètres obligatoires et facultatifs, les exemples d'utilisation et les indicateurs disponibles.

Démarrage rapide : Créez votre premier projet​

Suivez ces étapes pour créer un projet avec une Branch et un compute Endpoint :

1. Créer un projet​

Créer un projet Lakebase :

Bash
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 ressource : projects/my-project. Le projet est créé avec une branch de production default et un Endpoint de compute en lecture-écriture, tous deux avec des ID auto-générés.

Vous pouvez, si vous le souhaitez, exporter l'identifiant du projet en tant que variable à utiliser dans les commandes ultérieures :

Bash
export PROJECT_ID="my-project"

2. Obtenez l'ID de Branch​

Listez les branches de votre projet pour trouver l'ID de la branche default :

Bash
databricks postgres list-branches projects/$PROJECT_ID

Ceci renvoie des informations sur toutes les branches du projet. Recherchez la Branch avec "default": true dans le statut. Notez l'ID de la Branch à partir du champ name (par exemple, production pour la Branch default).

Exportez éventuellement l'ID de Branch en tant que variable à utiliser dans les commandes ultérieures :

Bash
export BRANCH_ID="production"

Remplacez production par votre ID de Branch actuel à partir de la sortie de la liste.

3. Obtenez l'ID d'Endpoint​

Listez les Endpoint dans votre Branch. La Branch default inclut automatiquement un Endpoint de lecture-écriture :

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

Notez l'ID de l'Endpoint à partir du champ name (par exemple, primary pour l'Endpoint de lecture/écriture « default »). Exportez-le en option en tant que variable :

Bash
export ENDPOINT_ID="primary"

Remplacez primary par l'ID de votre endpoint réel à partir de la sortie de la liste.

4. Générer les identifiants de base de données​

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

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

La commande renvoie un jeton OAuth que vous pouvez utiliser avec des clients PostgreSQL tels que psql pour accéder à vos données en utilisant votre identité Databricks. Pour des instructions étape par étape sur la connexion avec psql, consultez Connexion avec PSQL. Pour plus d'informations sur l'expiration des jetons et l'authentification, consultez Authentification.

Gérer les projets​

Lister les projets​

Listez tous les projets dans votre Workspace :

Bash
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 :

Bash
databricks postgres get-project projects/$PROJECT_ID

La commande renvoie le nom d'affichage du projet, la version PostgreSQL, le propriétaire, la période de rétention de l'historique, les limites de taille de la Branch, la taille du stockage et les timestamps.

Gérer les Branch​

Obtenir les détails de la Branch​

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

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

La commande renvoie l'état actuel de la Branch, son statut de protection, sa taille logique, les détails de la Branch source (le cas échéant) et les Timestamp.

Créer une Branch de fonctionnalités​

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

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

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

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

Lakebase crée automatiquement la Branch de fonctionnalités avec un Endpoint de compute principal en lecture-écriture. Une fois que vous avez terminé le développement et les tests sur la Branch de fonctionnalités, vous pouvez la supprimer :

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

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 de ressources correspondante, qui renvoie une erreur une fois la Ressources entièrement supprimée.

Mettre à jour la protection de Branch​

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

Bash
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, rendant la Branch protégée. Le masque de mise à jour (spec.is_protected) indique à l'API quel champ mettre à jour. La commande renvoie la Ressource mise à jour affichant la nouvelle valeur et un update_time timestamp mis à jour.

Gérer les computes​

Obtenir les détails du compute​

Obtenir des informations détaillées sur un endpoint :

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

La commande renvoie le type d'Endpoint, les paramètres d'autoscaling, l'état actuel, l'hôte de connexion, le délai d'expiration de la suspension et les Timestamps.

Monter en charge les lectures avec des réplicas en lecture​

Ajoutez des réplicas en lecture pour gérer l'augmentation du trafic de lecture. L'exemple suivant ajoute un réplica en lecture à la Branch de production par default :

Bash
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épliques en lecture avec des ID d'endpoint différents (read-replica-1, read-replica-2, etc.) pour distribuer les charges de travail en lecture.

Mettre à jour les limites du dimensionnement automatique​

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

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

Configurez la mise à l'échelle à zéro​

Pour configurer la mise à l'échelle jusqu'à 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 définissez pas les deux. Le paramètre no_suspension: false n'est pas valide et renvoie une erreur. Par default, la branch production a la mise à zéro activée avec un délai d'expiration de 24 heures.

Bash
# 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 la CLI pour créer et gérer les rôles Postgres pour l'accès à la base de données au sein d'une Branch. Pour des conseils détaillés 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 :

Bash
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é Databricks :

Bash
# 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>"}}'

Lister et obtenir les rôles​

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

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

Obtenir les détails sur un rôle spécifique :

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

La réponse inclut le nom de la 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​

Mettre à 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 de spec.attributes, vous devez fournir les trois champs d’attribut — l’API remplace l’objet d’attributs entier :

Bash
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​

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

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

Bash
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. Utilisez create-synced-table avec un ID {catalog}.{schema}.{table} :

Bash
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 la table synchronisée devient à la fois le nom de l'entité Unity Catalog et identifie la table Postgres. Obtenir le statut et supprimer une table synchronisée avec le même format d'ID :

Bash
# 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 default, l'interface de ligne de commande attend la fin de l'opération. Utilisez --no-wait pour revenir immédiatement ou --timeout pour définir une durée d'attente personnalisée. Consultez 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 des données lakehouse avec des tables synchronisées.

Comprendre les concepts clés​

Opérations de longue durée​

Les commandes de création, de mise à jour et de suppression sont des Opérations de longue durée. Par default, le CLI attend que l'Opération se termine. Utilisez --no-wait pour revenir immédiatement et interroger le statut séparément :

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

Interroger le statut de l’opération :

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

Dénomination des ressources​

Lakebase utilise des noms de ressources hiérarchiques :

  • Projets : projects/{project_id}. Vous spécifiez l'ID du projet lors de la création d'un projet.
  • Branches : projects/{project_id}/branches/{branch_id}. Vous spécifiez l'ID de Branch lors de la création d'une Branch.
  • **Endpoints** :. projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} Vous spécifiez l'ID de l'Endpoint (comme primary ou read-replica-1) lors de la création d'un Endpoint.

Les ID doivent comporter entre 1 et 63 caractères, start par une lettre minuscule et contenir uniquement des lettres minuscules, des chiffres et des tirets.

Mettre à jour les 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 séparée par des virgules pour plusieurs champs.

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

Ressources supplémentaires​

Sur cette page