Erste Schritte mit der Databricks CLI für Lakebase

Dieser Leitfaden hilft Ihnen bei den ersten Schritten mit der Databricks CLI, um Ihre Lakebase-Projekte, -Verzweigungen und -Berechnungen (Endpunkte) zu verwalten. Sie erfahren, wie Sie ein Arbeitsprojekt in nur wenigen Befehlen erstellen.

Vollständige Befehlsreferenz und alle verfügbaren Optionen finden Sie unter CLI-Befehle von Databricks.

Voraussetzungen

• Databricks CLI: Installieren Sie die Databricks CLI. Siehe Installieren der Databricks CLI.
• Arbeitsbereichzugriff: Sie müssen Zugriff auf einen Azure Databricks-Arbeitsbereich haben, in dem sich Ihre Lakebase-Ressource befindet.

Authentifizieren mit Azure Databricks

Bevor Sie CLI-Befehle ausführen, authentifizieren Sie sich bei Ihrem Azure Databricks-Arbeitsbereich:

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

Ersetzen Sie https://your-workspace.cloud.databricks.com mit Ihrer tatsächlichen Arbeitsbereichs-URL. Mit diesem Befehl wird ein Browserfenster geöffnet, in dem Sie sich mit Ihrem Azure Databricks-Konto mithilfe von OAuth authentifizieren können.

Weitere Authentifizierungsoptionen finden Sie unter Databricks-Authentifizierung.

Hilfe zu Befehlen

Die CLI bietet integrierte Hilfe für alle Befehle. Verwenden Sie --help, um verfügbare Befehle und Optionen anzuzeigen.

Verschaffen Sie sich einen Überblick über alle Postgres-Befehle:

databricks postgres --help

Der Befehl zeigt alle verfügbaren Befehle, globalen Kennzeichnungen und Informationen zu Ressourcenbenennungskonventionen an.

Erhalten Sie detaillierte Hilfe zu einem bestimmten Befehl:

databricks postgres create-project --help

Dies zeigt den Zweck des Befehls, erforderliche und optionale Parameter, Verwendungsbeispiele und verfügbare Flags.

Schnellstart: Erstellen Ihres ersten Projekts

Führen Sie die folgenden Schritte aus, um ein vollständiges Arbeitsprojekt mit einem Verzweigungs- und Computeendpunkt zu erstellen:

1. Erstellen eines Projekts

Erstellen eines Lakebase-Projekts:

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

Dieser Befehl erstellt ein Projekt und wartet darauf, bis es abgeschlossen ist. Die Projekt-ID (my-project) wird Teil des Ressourcennamens: projects/my-project. Das Projekt wird mit einem standardmäßigen Produktions-Branch und einem Lese-/Schreib-Compute-Endpunkt erstellt, beide mit automatisch generierten IDs.

Exportieren Sie optional die Projekt-ID als Variable, die in nachfolgenden Befehlen verwendet werden soll:

export PROJECT_ID="my-project"

2. Abrufen der Verzweigungs-ID

Listen Sie die Verzweigungen in Ihrem Projekt auf, um die Standardverzweigungs-ID zu finden:

databricks postgres list-branches projects/$PROJECT_ID

Dadurch werden Informationen zu allen Filialen im Projekt zurückgegeben. Suchen Sie nach der Zweigstelle mit "default": true im Status. Notieren Sie sich die Branch-ID aus dem name-Feld (z. B. production für den Standardbranch).

Exportieren Sie optional die Verzweigungs-ID als Variable für die Verwendung in nachfolgenden Befehlen:

export BRANCH_ID="production"

Ersetzen Sie production durch Ihre tatsächliche Branch-ID aus der Listenausgabe.

3. Abrufen der Endpunkt-ID

Listen Sie die Endpunkte in Ihrer Verzweigung auf. Die Standardverzweigung enthält automatisch einen Lese-/Schreibzugriffsendpunkt:

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

Notieren Sie sich die Endpunkt-ID aus dem name-Feld (z. B. primary für den standardmäßigen Lese-/Schreibendpunkt). Exportieren Sie sie optional als Variable:

export ENDPOINT_ID="primary"

Ersetzen Sie primary durch Ihre tatsächliche Endpunkt-ID aus der Liste.

4. Generieren von Datenbankanmeldeinformationen

Generieren Sie Anmeldeinformationen, um eine Verbindung mit Ihrer Datenbank herzustellen:

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

Der Befehl gibt ein OAuth-Token zurück, das Sie mit PostgreSQL-Clients psql verwenden können, um mit Ihrer Databricks-Identität auf Ihre Daten zuzugreifen. Schrittweise Anleitungen zum Herstellen einer Verbindung mit psql finden Sie unter "Verbinden mit psql". Weitere Informationen zum Token-Ablauf und zur Authentifizierung finden Sie unter Authentifizierung.

Verwalten Ihrer Ressourcen

Alle Projekte auflisten

Auflisten aller Projekte in Ihrem Arbeitsbereich:

databricks postgres list-projects

Der Befehl gibt Informationen zu jedem Projekt zurück, einschließlich Name, Anzeigename und aktueller Status. Sie umfasst auch Erstellungs- und Aktualisierungszeitstempel.

Abrufen von Ressourcendetails

Erhalten Sie detaillierte Informationen zu einem Projekt:

databricks postgres get-project projects/$PROJECT_ID

Der Befehl gibt die detaillierte Projektkonfiguration zurück, einschließlich des Anzeigenamens, der PostgreSQL-Version, des Besitzers und der Aufbewahrungsdauer der Historie. Sie umfasst auch Verzweigungsgrößenbeschränkungen, Standardendpunkteinstellungen, Speichergröße und Erstellungs- und Aktualisierungszeitstempel.

Erlangen Sie detaillierte Informationen zu einem Branch:

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

Der Befehl gibt detaillierte Verzweigungsinformationen zurück, einschließlich des aktuellen Zustands, des Standardverzweigungsstatus, des Schutzstatus und der logischen Größe. Sie enthält außerdem Details zum Quellzweig (falls aus einem anderen Zweig abgeleitet) sowie Erstellungs- und Aktualisierungszeitsstempel.

Erhalten Sie detaillierte Informationen zu einem Endpunkt:

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

Der Befehl gibt eine detaillierte Endpunktkonfiguration zurück, einschließlich des Endpunkttyps (Lese-/Schreibzugriff oder schreibgeschützt), automatischer Skalierungseinstellungen (Minimum und Maximum Compute Units) und des aktuellen Zustands (ACTIVE, IDLE usw.). Sie enthält auch den Verbindungshost, das Anhalten des Timeouts und das Erstellen und Aktualisieren von Zeitstempeln.

Aktualisieren von Ressourcen

Aktualisieren Sie eine Ressource mithilfe des Aktualisierungsformatmusters. Die Aktualisierungsmaske gibt an, welche Felder aktualisiert werden sollen:

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

In diesem Beispiel wird spec.is_protected auf true gesetzt, wodurch die Verzweigung geschützt wird. Das Updateformat (spec.is_protected) teilt der API mit, welches Feld aktualisiert werden soll. Der Befehl gibt die aktualisierte Ressource zurück, die den neuen Wert und einen aktualisierten update_time Zeitstempel anzeigt.

Verwenden Sie zum Aktualisieren mehrerer Felder eine durch Trennzeichen getrennte Liste:

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

Allgemeine Workflows

Erstellen eines Featurezweigs aus der Produktion

Erstellen Sie eine neue Verzweigung basierend auf einer vorhandenen Verzweigung, um Änderungen zu testen. Wenn Sie eine source_branchVerzweigung angeben, verfügt die neue Verzweigung zum Zeitpunkt der Erstellung über dasselbe Schema und dieselben Daten wie die Quell-Verzweigung. Ersetzen Sie die Projekt- und Verzweigungs-IDs durch Ihre tatsächlichen Werte:

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

Lakebase erstellt automatisch den Feature-Branch mit einem primären Rechenendpunkt für Lese-/Schreibzugriff. Nachdem Sie die Entwicklung und Tests für den Featurezweig abgeschlossen haben, können Sie sie löschen:

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

Skalierung von Lesen mit Lesereplikaten

Fügen Sie Lesereplikate hinzu, um erhöhten Lesedatenverkehr zu verarbeiten. Im folgenden Beispiel wird dem Standard-Produktionszweig ein Lesereplikat hinzugefügt.

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

Sie können mehrere Lesereplikate mit unterschiedlichen Endpunkt-IDs (read-replica-1, read-replica-2, usw.) erstellen, um die Lesearbeitslasten zu verteilen.

Verwalten von Rollen

Verwenden Sie die CLI zum Erstellen und Verwalten von Postgres-Rollen für den Datenbankzugriff innerhalb einer Verzweigung. Ausführliche Anleitungen zu Rollentypen und Authentifizierung finden Sie unter Erstellen von Postgres-Rollen.

Erstellen einer Rolle

Erstellen einer kennwortbasierten Rolle:

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

Erstellen Sie eine OAuth-Rolle, die an eine Azure Databricks Identität gebunden ist:

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

Rollen auflisten und abrufen

Auflisten aller Rollen in einem Branch:

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

Abrufen von Details zu einer bestimmten Rolle:

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

Die Antwort enthält den vom System generierten Rollenressourcennamen (zum Beispiel rol-xxxx-xxxxxxxxxx), der für Aktualisierungs- und Löschaufrufe erforderlich ist.

Aktualisieren einer Rolle

Aktualisieren Sie eine Rolle mithilfe der Aktualisierungsmaske. Übergeben Sie die Aktualisierungsmaske als zweites Positionsargument.

Beim Aktualisieren spec.attributesmüssen Sie alle drei Attributfelder bereitstellen – die API ersetzt das gesamte Attributobjekt:

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

Löschen einer Rolle

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

Wenn die Rolle Datenbankobjekte besitzt, verwenden Sie --reassign-owned-to, um den Besitz vor dem Löschen zu übertragen.

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

Grundlegendes zu den wichtigsten Konzepten

Zeitintensive Vorgänge

Befehle zum Erstellen, Aktualisieren und Löschen sind lang andauernde Vorgänge. Standardmäßig wartet die CLI auf den Abschluss des Vorgangs. Verwenden Sie --no-wait, um sofort zurückzukehren und den Status separat abzufragen.

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

Abfragen des Vorgangs-Status:

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

Ressourcen-Namensgebung

Lakebase verwendet hierarchische Ressourcennamen:

• Projekte: projects/{project_id}. Sie geben die Projekt-ID beim Erstellen eines Projekts an.
• Verzweigungen: projects/{project_id}/branches/{branch_id}. Beim Erstellen einer Verzweigung geben Sie die Branch-ID an.
• Endpunkte: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Sie geben die Endpunkt-ID (wie primary oder read-replica-1) beim Erstellen eines Endpunkts an.

IDs müssen 1 bis 63 Zeichen lang sein, mit einem Kleinbuchstaben beginnen und nur Kleinbuchstaben, Zahlen und Bindestriche enthalten.

Aktualisieren von Masken

Aktualisierungsbefehle erfordern eine Aktualisierungsmaske, die angibt, welche Felder geändert werden sollen. Die Maske ist ein Feldpfad wie spec.display_name oder eine durch Kommas getrennte Liste für mehrere Felder.

Die --json Nutzlast enthält die neuen Werte für diese Felder. Nur die in der Aktualisierungsmaske aufgeführten Felder werden geändert.

Nächste Schritte

• Databricks CLI Postgres-Befehlsreferenz
• Erstellen von Postgres-Rollen
• Herstellen einer Verbindung mit psql
• Verwalten von Branches
• Konfigurieren der Autoskalierung