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.

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 dessa steg för att skapa ett fullständigt arbetsprojekt 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 dina resurser

Visa en lista över alla projekt

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

databricks postgres list-projects

Kommandot returnerar information om varje projekt, inklusive dess namn, visningsnamn och aktuellt tillstånd. Den innehåller även tidsstämplar för skapande och uppdatering.

Hämta resursinformation

Få detaljerad information om ett projekt:

databricks postgres get-project projects/$PROJECT_ID

Kommandot returnerar detaljerad projektkonfiguration, inklusive visningsnamn, PostgreSQL-version, ägare och kvarhållningsperiod för historik. Den innehåller även gränser för grenstorlek, standardinställningar för slutpunkter, lagringsstorlek samt tidsstämplar för skapande och uppdatering.

Få detaljerad information om en gren:

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

Kommandot returnerar detaljerad greninformation, inklusive aktuellt tillstånd, standardgrenstatus, skyddsstatus och logisk storlek. Den innehåller även källgrensinformation (om den förgrenas från en annan gren) och tidsstämplar för skapande och uppdatering.

Få detaljerad information om en slutpunkt:

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

Kommandot returnerar detaljerad slutpunktskonfiguration, inklusive slutpunktstypen (skriv- och läsbar eller skrivskyddad), inställningar för automatisk skalning (lägsta och högsta beräkningsenheter) och det aktuella tillståndet (ACTIVE, IDLE och så vidare). Den innehåller även anslutningsvärd, paus-tidsgränsen samt skapande- och uppdaterings-tidsstämplar.

Uppdatera resurser

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.

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

Vanliga arbetsflöden

Skapa en funktionsgren från produktion

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

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

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.

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

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.

Nästa steg

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