Aan de slag met de Databricks CLI voor Lakebase

Deze handleiding helpt u aan de slag te gaan met de Databricks CLI om uw Lakebase-projecten, vertakkingen en berekeningen (eindpunten) te beheren. In slechts enkele opdrachten leert u hoe u een werkend project maakt.

Zie De Postgres-opdrachten van Databricks CLI voor volledige opdrachtreferenties en alle beschikbare opties.

Vereiste voorwaarden

  • Databricks CLI: Installeer de Databricks CLI. Zie De Databricks CLI installeren.
  • Werkruimtetoegang: U moet toegang hebben tot een Azure Databricks-werkruimte waarin uw Lakebase-resource zich bevindt.

Verifiëren met Azure Databricks

Voordat u CLI-opdrachten uitvoert, moet u zich verifiëren met uw Azure Databricks-werkruimte:

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

Vervang door https://your-workspace.cloud.databricks.com uw werkelijke werkruimte-URL. Met deze opdracht opent u een browservenster voor verificatie met uw Azure Databricks-account met behulp van OAuth.

Opmerking

Als u meerdere profielen hebt, gebruikt u de --profile vlag om op te geven welke u wilt gebruiken: databricks postgres <command> --profile my-profile. Als u uw geconfigureerde profielen wilt weergeven, voert u het volgende uit databricks auth profiles.

Zie Databricks-verificatie voor meer verificatieopties.

Help voor opdrachten ophalen

De CLI biedt ingebouwde help voor alle opdrachten. Gebruik --help deze optie om beschikbare opdrachten en opties weer te geven.

Bekijk een overzicht van alle Postgres-opdrachten:

databricks postgres --help

Met de opdracht worden alle beschikbare opdrachten, algemene vlaggen en informatie over naamconventies voor resources weergegeven.

Krijg gedetailleerde help voor een specifieke opdracht:

databricks postgres create-project --help

Dit toont het doel van de opdracht, de vereiste en optionele parameters, gebruiksvoorbeelden en beschikbare vlaggen.

Quickstart: Uw eerste project maken

Volg deze stappen om een project te maken met een vertakking en rekeneindpunt:

1. Een project maken

Een Lakebase-project maken:

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

Met deze opdracht wordt een project gemaakt en wordt gewacht totdat het is voltooid. De project-id (my-project) maakt deel uit van de resourcenaam: projects/my-project. Het project wordt gemaakt met een standaardproductievertakking en een rekeneindpunt voor lezen/schrijven, beide met automatisch gegenereerde id's.

U kunt de project-id desgewenst exporteren als een variabele voor gebruik in volgende opdrachten:

export PROJECT_ID="my-project"

2. Haal de branch-id op

Vermeld de vertakkingen in uw project om de standaard branch-id te vinden:

databricks postgres list-branches projects/$PROJECT_ID

Hiermee wordt informatie geretourneerd over alle branches in het project. Zoek naar de tak met de status "default": true. Noteer de vertakkings-id uit het name veld (bijvoorbeeld production voor de standaardbranch).

U kunt eventueel de vertakkings-id exporteren als een variabele voor gebruik in volgende opdrachten:

export BRANCH_ID="production"

Vervang production door de werkelijke vertakkings-id uit de lijstuitvoer.

3. Haal de eindpunt-id op

Vermeld de eindpunten in uw vertakking. De standaardvertakking bevat automatisch een eindpunt voor lezen/schrijven:

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

Noteer de eindpunt-id uit het name veld (bijvoorbeeld primary voor het standaardeindpunt voor lezen/schrijven). U kunt deze desgewenst exporteren als een variabele:

export ENDPOINT_ID="primary"

Vervang primary door uw werkelijke eindpunt-id uit de lijstuitvoer.

4. Databasereferenties genereren

Referenties genereren om verbinding te maken met uw database:

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

De opdracht retourneert een OAuth-token dat u kunt gebruiken met PostgreSQL-clients, zoals psql toegang tot uw gegevens met behulp van uw Databricks-identiteit. Zie Verbinding maken met psql voor stapsgewijze instructies voor het maken van verbinding met psql. Zie Verificatie voor meer informatie over het verlopen en verifiëren van tokens.

Projecten beheren

Projecten weergeven

Alle projecten in uw werkruimte weergeven:

databricks postgres list-projects

De opdracht retourneert de naam, weergavenaam, huidige status en tijdstempels van elk project.

Projectdetails ophalen

Gedetailleerde informatie over een project ophalen:

databricks postgres get-project projects/$PROJECT_ID

De opdracht retourneert de weergavenaam van het project, postgreSQL-versie, eigenaar, bewaarperiode voor geschiedenis, limieten voor vertakkingsgrootte, opslaggrootte en tijdstempels.

Branches beheren

Branchgegevens ophalen

Haal gedetailleerde informatie over een branche op:

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

De opdracht geeft de huidige status van de branch, de beveiligingsstatus, de logische grootte, de details over de bronbranch (indien van toepassing) en de tijdstempels terug.

Een functiebranch maken

Maak een nieuwe vertakking op basis van een bestaande vertakking om wijzigingen te testen. Wanneer u een source_branch opgeeft, heeft de nieuwe branch hetzelfde schema en dezelfde gegevens als de bronbranch op het moment van maken. Vervang de project- en vertakkings-id's door uw werkelijke waarden:

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

Opmerking

Wanneer u een vertakking maakt, moet u een vervalbeleid opgeven. Gebruik no_expiry: true om een permanente vertakking te maken.

Als u shellvariabelen in de JSON-specificatie (zoals $PROJECT_ID of $BRANCH_ID) wilt gebruiken, gebruikt u dubbele aanhalingstekens voor de --json waarde en escapet u de interne aanhalingstekens.

Lakebase maakt automatisch de functievertakking met een primair rekeneindpunt voor lezen/schrijven. Nadat u klaar bent met ontwikkelen en testen op de functiebranch, kunt u deze verwijderen:

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

Opmerking

Verwijderopdrachten worden onmiddellijk geretourneerd, maar het kan even duren voordat het verwijderen is voltooid. U kunt de verwijdering controleren door de bijbehorende opdracht resource ophalen uit te voeren, die een fout retourneert nadat de resource volledig is verwijderd.

Branchbeveiliging bijwerken

Werk een resource bij met behulp van het patroon updatemasker. Het updatemasker geeft aan welke velden moeten worden bijgewerkt:

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

In dit voorbeeld wordt ingesteld spec.is_protected op true, waardoor de vertakking wordt beveiligd. Het updatemasker (spec.is_protected) vertelt de API welk veld moet worden bijgewerkt. De opdracht retourneert de bijgewerkte resource met de nieuwe waarde en een bijgewerkte update_time tijdstempel.

Berekeningen beheren

Berekeningsgegevens ophalen

Gedetailleerde informatie over een eindpunt ophalen:

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

De opdracht retourneert het eindpunttype, instellingen voor automatisch schalen, huidige status, verbindingshost, time-out onderbreken en tijdstempels.

Leesbewerkingen schalen met leesreplica's

Voeg leesreplica's toe om het toegenomen leesverkeer te verwerken. In het volgende voorbeeld wordt een leesreplica toegevoegd aan de standaardproductiebranch:

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

U kunt meerdere leesreplica's maken met verschillende eindpunt-id's (read-replica-1, read-replica-2enzovoort) om leesworkloads te distribueren.

Limieten voor automatisch schalen bijwerken

Als u meerdere velden wilt bijwerken, gebruikt u een door komma's gescheiden lijst:

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

Schaal naar nul configureren

Als u schalen naar nul wilt configureren, neemt u spec.suspension op in het updatemask. Stel suspend_timeout_duration (60s-604800s) in om de time-out voor inactiviteit te definiëren of no_suspension: true om deze uit te schakelen. Stel niet beide in. De instelling no_suspension: false is ongeldig en retourneert een fout. De production branch is standaard ingesteld op schalen naar nul, met een time-out van 24 uur.

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

Rollen beheren

Gebruik de CLI om Postgres-rollen te maken en te beheren voor databasetoegang binnen een vertakking. Zie Postgres-rollen maken voor gedetailleerde richtlijnen over roltypen en verificatie.

Een rol maken

Maak een rol op basis van een wachtwoord:

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

Een OAuth-rol maken die is gekoppeld aan een Azure Databricks-identiteit:

# 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 weergeven en ophalen

Alle rollen in een branch weergeven:

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

Meer informatie over een specifieke rol:

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

Het antwoord bevat de resourcenaam van de door het systeem gegenereerde rol (bijvoorbeeld rol-xxxx-xxxxxxxxxx) die is vereist voor het bijwerken en verwijderen van aanroepen.

Een rol bijwerken

Werk een rol bij met behulp van het updatemaskerpatroon. Geef het updatemasker door als het tweede positionele argument.

Bij het bijwerken spec.attributesmoet u alle drie de kenmerkvelden opgeven: de API vervangt het hele kenmerkobject:

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

Een rol verwijderen

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

Als de rol eigenaar is van databaseobjecten, gebruikt --reassign-owned-to u deze om het eigendom over te dragen vóór verwijdering:

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

Gesynchroniseerde tabellen beheren

Gesynchroniseerde tabellen repliceren Unity Catalog-gegevens naar uw Lakebase-database voor leesbewerkingen met lage latentie. Gebruik create-synced-table met een {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
    }
  }'

De gesynchroniseerde tabel-id wordt de naam van de Unity Catalog-entiteit en identificeert de Postgres-tabel. Status ophalen en een gesynchroniseerde tabel verwijderen met dezelfde id-indeling:

# 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 en create-catalog langlopende bewerkingen zijn. De CLI wacht standaard op voltooiing. Gebruik --no-wait deze functie om onmiddellijk terug te keren of --timeout om een aangepaste wachttijd in te stellen. Zie Langlopende bewerkingen.

Zie Serve lakehouse-gegevens met gesynchroniseerde tabellen voor gedetailleerde richtlijnen voor synchronisatiemodi, toewijzing van gegevenstypen en capaciteitsplanning.

Belangrijke concepten begrijpen

Langlopende bewerkingen

Opdrachten voor maken, bijwerken en verwijderen zijn langlopende bewerkingen. De CLI wacht standaard totdat de bewerking is voltooid. Gebruik --no-wait dit om onmiddellijk te retourneren en de status afzonderlijk te peilen:

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

De status van de operatie peilen

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

Naamgeving van hulpbronnen

Lakebase maakt gebruik van hiërarchische resourcenamen:

  • Projecten: projects/{project_id}. U geeft de project-id op bij het maken van een project.
  • Vertakkingen: projects/{project_id}/branches/{branch_id}. U geeft de vertakkings-id op bij het maken van een vertakking.
  • Eindpunten: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. U geeft de eindpunt-id (zoals primary of read-replica-1) op bij het maken van een eindpunt.

Id's moeten 1-63 tekens lang zijn, beginnen met een kleine letter en mogen alleen kleine letters, cijfers en afbreekstreepjes bevatten.

Maskers bijwerken

Voor updateopdrachten is een updatemasker vereist waarmee wordt aangegeven welke velden moeten worden gewijzigd. Het masker is een veldpad zoals spec.display_name of een door komma's gescheiden lijst voor meerdere velden.

De --json payload bevat de nieuwe waarden voor deze velden. Alleen de velden die in het updatemasker worden vermeld, worden gewijzigd.

Aanvullende informatiebronnen

  • Laatst bijgewerkt om