Kom igång med Databricks CLI för Lakebase

Den här guiden hjälper dig att komma igång med Databricks CLI för att hantera dina Lakebase-projekt, grenar och beräkningar (slutpunkter). Du får lära dig hur du skapar ett fungerande projekt med bara några få kommandon.

Fullständig kommandoreferens och alla tillgängliga alternativ finns i Postgres-kommandon för Databricks CLI.

Förutsättningar

• Databricks CLI: Installera Databricks CLI. Se till att Installera Databricks CLI.
• Åtkomst till arbetsyta: Du måste ha åtkomst till en Azure Databricks-arbetsyta där din Lakebase-resurs finns.

Autentisera med Azure Databricks

Autentisera med din Azure Databricks-arbetsyta innan du kör några CLI-kommandon:

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

Ersätt https://your-workspace.cloud.databricks.com med din faktiska url för arbetsytan. Det här kommandot öppnar ett webbläsarfönster där du kan autentisera med ditt Azure Databricks-konto med OAuth.

Anmärkning

Om du har flera profiler använder du --profile flaggan för att ange vilken som ska användas: databricks postgres <command> --profile my-profile. Om du vill visa dina konfigurerade profiler kör du databricks auth profiles.

Fler autentiseringsalternativ finns i Databricks-autentisering.

Hämta kommandohjälp

CLI tillhandahåller inbyggd hjälp för alla kommandon. Använd --help för att se tillgängliga kommandon och alternativ.

Få en översikt över alla Postgres-kommandon:

databricks postgres --help

Kommandot visar alla tillgängliga kommandon, globala flaggor och information om namngivningskonventioner för resurser.

Få detaljerad hjälp för ett specifikt kommando:

databricks postgres create-project --help

Detta visar kommandots syfte, obligatoriska och valfria parametrar, användningsexempel och tillgängliga flaggor.

Snabbstart: Skapa ditt första projekt

Följ de här stegen för att skapa ett projekt med en gren- och beräkningsslutpunkt:

1. Skapa ett projekt

Skapa ett Lakebase-projekt:

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

Det här kommandot skapar ett projekt och väntar på att det ska slutföras. Projekt-ID:t (my-project) blir en del av resursnamnet: projects/my-project. Projektet skapas med en standardproduktionsgren och en läs/skriv slutpunkt för beräkning, båda med automatiskt genererade ID:er.

Du kan också exportera projekt-ID:t som en variabel som ska användas i efterföljande kommandon:

export PROJECT_ID="my-project"

2. Hämta gren-ID:t

Visa en lista över grenarna i projektet för att hitta standardgrenens ID:

databricks postgres list-branches projects/$PROJECT_ID

Detta returnerar information om alla grenar i projektet. Leta efter grenen med "default": true i statusen. Observera gren-ID:t från name fältet (till exempel production för standardgrenen).

Du kan också exportera gren-ID:t som en variabel för användning i efterföljande kommandon:

export BRANCH_ID="production"

Ersätt production med ditt faktiska gren-ID från listans utdata.

3. Hämta slutpunktens ID

Visa en lista över slutpunkterna i din gren. Standardgrenen innehåller automatiskt en läs- och skrivslutpunkt.

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

Observera slutpunkts-ID:t från name fältet (till exempel primary för standardslutpunkten för läsning och skrivning). Du kan också exportera den som en variabel:

export ENDPOINT_ID="primary"

Ersätt primary med ditt faktiska slutpunkts-ID från listans utdata.

4. Generera databasautentiseringsuppgifter

Generera autentiseringsuppgifter för att ansluta till databasen:

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

Kommandot returnerar en OAuth-token som du kan använda med PostgreSQL-klienter som psql att komma åt dina data med hjälp av din Databricks-identitet. Stegvisa anvisningar om hur du ansluter med psql finns i Ansluta med psql. Mer information om tokens giltighetstid och autentisering finns i Autentisering.

Hantera projekten

Lista projekt

Visa en lista över alla projekt på din arbetsyta:

databricks postgres list-projects

Kommandot returnerar varje projekts namn, visningsnamn, aktuellt tillstånd och tidsstämplar.

Hämta projektinformation

Få detaljerad information om ett projekt:

databricks postgres get-project projects/$PROJECT_ID

Kommandot returnerar projektets visningsnamn, PostgreSQL-version, ägare, kvarhållningsperiod för historik, gränser för grenstorlek, lagringsstorlek och tidsstämplar.

Hantera filialer

Hämta greninformation

Få detaljerad information om en gren:

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

Kommandot returnerar grenens aktuella tillstånd, skyddsstatus, logiska storlek, källgrensinformation (om tillämpligt) och tidsstämplar.

Skapa en funktionsgren

Skapa en ny gren baserat på en befintlig gren för att testa ändringar. När du anger en source_branchhar den nya grenen samma schema och data som källgrenen när den skapades. Ersätt projekt- och gren-ID:na med dina faktiska värden:

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

Anmärkning

När du skapar en gren måste du ange en förfalloprincip. Använd no_expiry: true för att skapa en permanent gren.

Om du vill använda gränssnittsvariabler i JSON-specifikationen (t.ex $PROJECT_ID . eller $BRANCH_ID) använder du dubbla citattecken för --json värdet och slipper de interna citattecknarna.

Lakebase skapar automatiskt funktionsgrenen med en primär beräkningsslutpunkt för läsning och skrivning. När du har slutfört utvecklingen och testningen av funktionsgrenen kan du ta bort den:

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

Anmärkning

Ta bort kommandon returneras omedelbart, men den faktiska borttagningen kan ta tid att slutföra. Du kan kontrollera borttagningen genom att köra motsvarande get-resurskommando, som returnerar ett fel när resursen har tagits bort helt.

Uppdatera grenskydd

Uppdatera en resurs med hjälp av uppdateringsmaskmönstret. Uppdateringsmasken anger vilka fält som ska uppdateras:

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

Det här exemplet anger spec.is_protected till true, vilket gör grenen skyddad. Uppdateringsmasken (spec.is_protected) talar om för API:et vilket fält som ska uppdateras. Kommandot returnerar den uppdaterade resursen som visar det nya värdet och en uppdaterad update_time tidsstämpel.

Hantera beräkningar

Visa beräkningsdetaljer

Få detaljerad information om en slutpunkt:

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

Kommandot returnerar slutpunktstypen, inställningar för automatisk skalning, aktuellt tillstånd, anslutningsvärd, tidsgräns för paus och tidsstämplar.

Skala läsningar med läsrepliker

Lägg till läsrepliker för att hantera ökad lästrafik. I följande exempel läggs en läsreplik till standardproduktionsgrenen:

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

Du kan skapa flera läsrepliker med olika slutpunkts-ID:t (read-replica-1, read-replica-2osv.) för att distribuera läsarbetsbelastningar.

Uppdatera begränsningar för automatisk skalning

Om du vill uppdatera flera fält använder du en kommaavgränsad lista:

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

Konfigurera skalning till noll

Om du vill konfigurera skalning till noll tar du med spec.suspension i uppdateringsmasken. Ange suspend_timeout_duration (60s–604800s) för att definiera tidsgränsen för inaktivitet eller no_suspension: true för att inaktivera den. Ange inte båda. Inställningen no_suspension: false är ogiltig och returnerar ett fel. Som standard har grenen production skalning till noll aktiverat med en tidsgräns på 24 timmar.

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

Hantera roller

Använd CLI för att skapa och hantera Postgres-roller för databasåtkomst inom en gren. Detaljerad vägledning om rolltyper och autentisering finns i Skapa Postgres-roller.

Skapa en roll

Skapa en lösenordsbaserad roll:

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

Skapa en OAuth-roll som är kopplad till en Azure Databricks identitet:

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

Lista och få roller

Visa en lista över alla roller i en gren:

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

Få information om en specifik roll:

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

Svaret innehåller det systemgenererade rollresursnamnet (till exempel rol-xxxx-xxxxxxxxxx) som krävs för uppdaterings- och borttagningsanrop.

Uppdatera en roll

Uppdatera en roll med hjälp av uppdateringsmaskmönstret. Skicka uppdateringsmasken som det andra positionsargumentet.

När du uppdaterar spec.attributesmåste du ange alla tre attributfälten – API:et ersätter hela attributobjektet:

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

Ta bort en roll

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

Om rollen äger databasobjekt använder du --reassign-owned-to för att överföra ägarskapet innan du tas bort:

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

Hantera synkroniserade tabeller

Synkroniserade tabeller replikerar Unity Catalog-data till din Lakebase-databas för driftläsningar med låg svarstid. Använd create-synced-table med ett {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
    }
  }'

Det synkroniserade tabell-ID:t blir både Enhetskatalogens entitetsnamn och identifierar Postgres-tabellen. Hämta status och ta bort en synkroniserad tabell med samma ID-format:

# 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 och create-catalog är tidskrävande åtgärder. Som standard väntar CLI på att slutföras. Använd --no-wait för att returnera omedelbart eller --timeout för att ange en anpassad väntetid. Se Tidskrävande åtgärder.

Detaljerad vägledning om synkroniseringslägen, datatypsmappning och kapacitetsplanering finns i Hantera lakehouse-data med synkroniserade tabeller.

Förstå viktiga begrepp

Tidskrävande åtgärder

Kommandon för att skapa, uppdatera och ta bort är tidskrävande åtgärder. Som standard väntar CLI tills åtgärden har slutförts. Använd --no-wait för att returnera omedelbart och kontrollera statusen separat:

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

Kontrollera driftstatusen:

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

Resursnamngivning

Lakebase använder hierarkiska resursnamn:

• Projekt: projects/{project_id}. Du anger projekt-ID när du skapar ett projekt.
• Grenar: projects/{project_id}/branches/{branch_id}. Du anger gren-ID när du skapar en gren.
• Slutpunkter: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Du anger slutpunkts-ID (t.ex primary . eller read-replica-1) när du skapar en slutpunkt.

ID:n måste vara 1–63 tecken långt, börja med en liten bokstav och endast innehålla små bokstäver, siffror och bindestreck.

Uppdatera masker

Uppdateringskommandon kräver en uppdateringsmask som anger vilka fält som ska ändras. Masken är en fältsökväg som spec.display_name eller en kommaavgränsad lista för flera fält.

Nyttolasten --json innehåller de nya värdena för dessa fält. Endast de fält som anges i uppdateringsmasken ändras.

Ytterligare resurser

• Referens för Databricks CLI-postgres-kommandon
• Skapa Postgres-roller
• Ansluta med psql
• Hantera filialer
• Konfigurera automatisk skalning
• Hantera lakehouse-data med synkroniserade tabeller