Condividi tramite

Introduzione all'interfaccia della riga di comando di Databricks per Lakebase

Importante

La scalabilità automatica di Lakebase si trova in Beta nelle aree seguenti: eastus2, westeurope, westus.

Lakebase Autoscaling è la versione più recente di Lakebase con calcolo autoscalante, riduzione a zero, ramificazione e ripristino istantaneo. Per il confronto delle funzionalità con Lakebase Provisioned, vedere scegliere tra le versioni.

Questa guida illustra come iniziare a usare l'interfaccia della riga di comando di Databricks per gestire progetti, rami e calcoli di LakeBase (endpoint). Si apprenderà come creare un progetto funzionante in pochi comandi.

Per la documentazione completa sui comandi e tutte le opzioni disponibili, vedere i comandi postgres del CLI di Databricks.

Prerequisiti

  • Interfaccia della riga di comando di Databricks: installare l'interfaccia della riga di comando di Databricks. Vedere Installare l'interfaccia della riga di comando di Databricks.
  • Accesso all'area di lavoro: è necessario avere accesso a un'area di lavoro di Azure Databricks in cui risiede la risorsa Lakebase.

Eseguire l'autenticazione con Databricks

Prima di eseguire qualsiasi comando dell'interfaccia della riga di comando, eseguire l'autenticazione con l'area di lavoro di Azure Databricks:

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

Sostituire https://your-workspace.cloud.databricks.com con l'URL effettivo dell'area di lavoro. Questo comando apre una finestra del browser per l'autenticazione con l'account Azure Databricks usando OAuth.

Annotazioni

Se sono presenti più profili, usare il --profile flag per specificare quale usare: databricks postgres <command> --profile my-profile. Per visualizzare i profili configurati, eseguire databricks auth profiles.

Per altre opzioni di autenticazione, vedere Autenticazione di Databricks.

Ottenere la guida per i comandi

L'interfaccia CLI offre un aiuto integrato per tutti i comandi. Usare --help per visualizzare i comandi e le opzioni disponibili.

Ottenere una panoramica di tutti i comandi postgres:

databricks postgres --help

Vengono visualizzati tutti i comandi disponibili, i flag globali e le informazioni sulle convenzioni di denominazione delle risorse.

Ottenere una guida dettagliata per un comando specifico:

databricks postgres create-project --help

Vengono illustrati lo scopo del comando, i parametri obbligatori e facoltativi, gli esempi di utilizzo e i flag disponibili.

Guida introduttiva: Creare il primo progetto

Seguire questa procedura per creare un progetto di lavoro completo con un ramo e un endpoint di calcolo:

1. Creare un progetto

Creare un nuovo progetto Lakebase:

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

Questo comando crea un progetto e attende il completamento. L'ID progetto (my-project) diventa parte del nome della risorsa: projects/my-project. Il progetto viene creato con un ramo di produzione predefinito e un endpoint di calcolo di lettura/scrittura, entrambi con ID generati automaticamente.

Facoltativamente, esportare l'ID progetto come variabile da usare nei comandi successivi:

export PROJECT_ID="my-project"

2. Ottenere l'ID ramo

Elencare i rami nel progetto per trovare l'ID ramo predefinito:

databricks postgres list-branches projects/$PROJECT_ID

Vengono restituite informazioni su tutti i rami del progetto. Cercare il ramo con "default": true nello stato . Annotare l'ID del ramo dal campo name, ad esempio br-divine-sea-y2k942xa.

Facoltativamente, esportare l'ID del ramo come variabile da usare nei comandi successivi:

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

Sostituire br-divine-sea-y2k942xa con il reale ID branch predefinito dall'output dell'elenco.

3. Ottenere l'ID endpoint

Elencare gli endpoint nella filiale. Il ramo predefinito include automaticamente un endpoint di lettura/scrittura:

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

Prendere nota dell'ID endpoint dal name campo. Sarà nel formato projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Estrarre l'ID endpoint (ad esempio , ep-plain-sunset-y2vc0zan) ed esportarlo facoltativamente come variabile:

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

Sostituire ep-plain-sunset-y2vc0zan con l'ID endpoint effettivo dall'output dell'elenco.

4. Generare le credenziali del database

Generare le credenziali per connettersi al database:

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

Il comando restituisce un token OAuth che è possibile usare con i client PostgreSQL come psql per accedere ai dati usando l'identità di Databricks. Per istruzioni dettagliate sulla connessione con psql, vedere Connettersi con psql. Per altre informazioni sulla scadenza e l'autenticazione dei token, vedere Autenticazione.

Gestione delle risorse

Elencare tutti i progetti

Elencare tutti i progetti nell'area di lavoro:

databricks postgres list-projects

Vengono restituite informazioni su ogni progetto, inclusi il nome visualizzato, lo stato corrente e i timestamp di creazione/aggiornamento.

Ottenere i dettagli della risorsa

Ottenere informazioni dettagliate su un progetto:

databricks postgres get-project projects/$PROJECT_ID

Viene restituita la configurazione dettagliata del progetto, tra cui il nome visualizzato, la versione di PostgreSQL, il proprietario, il periodo di conservazione della cronologia, i limiti delle dimensioni del ramo, le impostazioni predefinite dell'endpoint, le dimensioni di archiviazione e i timestamp di creazione/aggiornamento.

Ottenere informazioni dettagliate su un ramo:

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

Vengono restituite informazioni dettagliate sui rami, tra cui lo stato corrente, lo stato predefinito del ramo, lo stato di protezione, le dimensioni logiche, i dettagli del ramo di origine (se rami da un altro ramo) e i timestamp di creazione/aggiornamento.

Ottenere informazioni dettagliate su un endpoint:

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

Viene restituita la configurazione dettagliata dell'endpoint, incluso il tipo di endpoint (lettura/scrittura o sola lettura), le impostazioni di scalabilità automatica (unità di calcolo minime e massime), lo stato corrente (ACTIVE, IDLE e così via), l'host di connessione, il timeout di sospensione e i timestamp di creazione/aggiornamento.

Aggiornare le risorse

Aggiornare una risorsa usando il modello di maschera di aggiornamento. La maschera di aggiornamento specifica i campi da aggiornare:

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

In questo esempio viene impostato spec.is_protected su true, rendendo protetto il ramo . La maschera di aggiornamento (spec.is_protected) indica all'API quale campo aggiornare. Il comando restituisce la risorsa aggiornata che mostra il nuovo valore e un timestamp aggiornato update_time .

Per aggiornare più campi, usare un elenco delimitato da virgole:

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

Flussi di lavoro comuni

Creare un ramo di funzionalità dall'ambiente di produzione

Creare un nuovo ramo basato su un ramo esistente per testare le modifiche. Quando si specifica un source_branch, il nuovo ramo avrà lo stesso schema e gli stessi dati del ramo di origine al momento della creazione. Sostituire gli ID progetto e ramo con i valori effettivi:

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

Annotazioni

Quando si crea un ramo, è necessario specificare un criterio di scadenza. Usare no_expiry: true per creare un ramo permanente.

Per usare le variabili della shell all'interno della specifica JSON (ad esempio $PROJECT_ID o $BRANCH_ID), è necessario usare virgolette doppie per il --json valore ed eseguire l'escape delle virgolette interne.

Il ramo di funzionalità richiede un endpoint di calcolo di lettura/scrittura per consentire le operazioni del database:

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

Dopo aver completato lo sviluppo e il test nel ramo delle funzionalità, è possibile eliminarlo:

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

Annotazioni

I comandi delete restituiscono immediatamente, ma il completamento dell'eliminazione effettiva può richiedere tempo. È possibile verificare l'eliminazione eseguendo il comando get resource corrispondente, che restituisce un errore dopo l'eliminazione completa della risorsa.

Scalare le letture con repliche di lettura

Aggiungi repliche di lettura per gestire l'aumento del traffico di lettura. Questo esempio aggiunge una replica di lettura al ramo di produzione predefinito:

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

È possibile creare più repliche in lettura con ID endpoint diversi (read-replica-1, read-replica-2e così via) per distribuire i carichi di lavoro di lettura.

Informazioni sui concetti chiave

Operazioni a esecuzione prolungata

I comandi di creazione, aggiornamento ed eliminazione sono operazioni a esecuzione prolungata. Per impostazione predefinita, l'interfaccia della riga di comando attende il completamento dell'operazione. Usare --no-wait per tornare immediatamente e controllare lo stato separatamente.

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

Verificare lo stato dell'operazione:

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

Denominazione delle risorse

Lakebase usa nomi di risorse gerarchici:

  • Progetti: projects/{project_id}. Specificare l'ID progetto durante la creazione di un progetto.
  • Rami: projects/{project_id}/branches/{branch_id}. Specificare l'ID del ramo al momento della creazione di un ramo.
  • Endpoint: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Specificare l'ID endpoint (ad esempio primary o read-replica-1) durante la creazione di un endpoint.

Gli ID devono avere una lunghezza di 1-63 caratteri, iniziare con una lettera minuscola e contenere solo lettere minuscole, numeri e trattini.

Aggiorna le maschere

I comandi di aggiornamento richiedono una maschera di aggiornamento che specifica i campi da modificare. La maschera è un percorso di campo come spec.display_name o un elenco delimitato da virgole per più campi.

Il --json payload contiene i nuovi valori per tali campi. Vengono modificati solo i campi elencati nella maschera di aggiornamento.

Passaggi successivi

  • Last updated on