Rozpocznij korzystanie z interfejsu wiersza polecenia (CLI) Databricks dla Lakebase.

Ten przewodnik ułatwia rozpoczęcie pracy z interfejsem wiersza polecenia usługi Databricks w celu zarządzania projektami, gałęziami i obliczeniami usługi Lakebase (punktami końcowymi). Dowiesz się, jak utworzyć projekt roboczy w kilku poleceniach.

Aby uzyskać pełną dokumentację poleceń i wszystkie dostępne opcje, zobacz polecenia postgres CLI Databricks.

Wymagania wstępne

Interfejs wiersza polecenia usługi Databricks: zainstaluj interfejs wiersza polecenia usługi Databricks. Zobacz Zainstaluj Databricks CLI.
Dostęp do obszaru roboczego: musisz mieć dostęp do obszaru roboczego usługi Azure Databricks, w którym znajduje się zasób usługi Lakebase.

Uwierzytelnianie przy użyciu Azure Databricks

Przed uruchomieniem jakichkolwiek poleceń CLI uwierzytelnij się w Azure Databricks.

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

Zastąp https://your-workspace.cloud.databricks.com swoim rzeczywistym adresem URL obszaru roboczego. To polecenie otwiera okno przeglądarki służące do uwierzytelniania przy użyciu konta usługi Azure Databricks przy użyciu protokołu OAuth.

Uwaga / Notatka

Jeśli masz wiele profilów, użyj flagi --profile , aby określić, która z nich ma być używana: databricks postgres <command> --profile my-profile. Aby wyświetlić skonfigurowane profile, uruchom polecenie databricks auth profiles.

Aby uzyskać więcej opcji uwierzytelniania, zobacz Uwierzytelnianie w usłudze Databricks.

Uzyskiwanie pomocy dotyczącej poleceń

CLI oferuje wbudowaną pomoc dla wszystkich poleceń. Użyj --help polecenia , aby wyświetlić dostępne polecenia i opcje.

Zapoznaj się z omówieniem wszystkich poleceń bazy danych Postgres:

databricks postgres --help

Polecenie wyświetla wszystkie dostępne polecenia, flagi globalne i informacje o konwencjach nazewnictwa zasobów.

Uzyskaj szczegółową pomoc dotyczącą określonego polecenia:

databricks postgres create-project --help

Spowoduje to wyświetlenie przeznaczenia polecenia, wymaganych i opcjonalnych parametrów, przykładów użycia i dostępnych flag.

Szybki start: tworzenie pierwszego projektu

Wykonaj następujące kroki, aby utworzyć projekt z gałęzią i punktem końcowym obliczeniowym:

1. Tworzenie projektu

Utwórz projekt Lakebase:

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

To polecenie tworzy projekt i czeka na jego ukończenie. Identyfikator projektu (my-project) staje się częścią nazwy zasobu: projects/my-project. Projekt jest tworzony z domyślną gałęzią produkcyjną i punktem końcowym obliczeniowym odczytu i zapisu, zarówno z automatycznie wygenerowanymi identyfikatorami.

Opcjonalnie wyeksportuj identyfikator projektu jako zmienną do użycia w kolejnych poleceniach:

export PROJECT_ID="my-project"

2. Pobierz identyfikator gałęzi

Wyświetl listę gałęzi w projekcie, aby znaleźć domyślny identyfikator gałęzi:

databricks postgres list-branches projects/$PROJECT_ID

Spowoduje to zwrócenie informacji o wszystkich gałęziach w projekcie. Wyszukaj gałąź, której status to "default": true. Zanotuj identyfikator gałęzi z name pola (na przykład production dla gałęzi domyślnej).

Opcjonalnie wyeksportuj identyfikator gałęzi jako zmienną do użycia w kolejnych poleceniach:

export BRANCH_ID="production"

Zastąp production rzeczywistym ID gałęzi z danych wyjściowych listy.

3. Pobieranie identyfikatora punktu końcowego

Wyświetl listę punktów końcowych w gałęzi. Gałąź domyślna automatycznie zawiera punkt końcowy odczytu i zapisu:

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

Zanotuj identyfikator punktu końcowego name z pola (na przykład primary dla domyślnego punktu końcowego odczytu i zapisu). Opcjonalnie wyeksportuj go jako zmienną:

export ENDPOINT_ID="primary"

Zastąp primary rzeczywistym identyfikatorem punktu końcowego z listy wyników.

4. Generowanie poświadczeń bazy danych

Wygeneruj poświadczenia, aby nawiązać połączenie z bazą danych:

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

Polecenie zwraca token OAuth, którego można używać z klientami PostgreSQL, takimi jak psql, aby uzyskać dostęp do danych przy użyciu swojej tożsamości w Databricks. Aby uzyskać instrukcje krok po kroku dotyczące nawiązywania połączenia z bazą danych psql, zobacz Connect with psql (Nawiązywanie połączenia za pomocą narzędzia psql). Aby uzyskać więcej informacji na temat wygasania i uwierzytelniania tokenów, zobacz Uwierzytelnianie.

Zarządzanie projektami

Lista projektów

Wyświetl listę wszystkich projektów w obszarze roboczym:

databricks postgres list-projects

Polecenie zwraca nazwę każdego projektu, nazwę wyświetlaną, bieżący stan i znaczniki czasu.

Pobieranie szczegółów projektu

Uzyskaj szczegółowe informacje o projekcie:

databricks postgres get-project projects/$PROJECT_ID

Polecenie zwraca nazwę wyświetlaną projektu, wersję bazy danych PostgreSQL, właściciela, okres przechowywania historii, limity rozmiaru gałęzi, rozmiar magazynu i znaczniki czasu.

Zarządzanie oddziałami

Pobierz szczegóły gałęzi

Uzyskaj szczegółowe informacje o gałęzi:

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

Polecenie zwraca bieżący stan gałęzi, stan ochrony, rozmiar logiczny, szczegóły gałęzi źródłowej (jeśli dotyczy) i znaczniki czasu.

Utwórz gałąź funkcji

Utwórz nową gałąź na podstawie istniejącej gałęzi, aby przetestować zmiany. Po określeniu source_branch, nowa gałąź będzie miała ten sam schemat i dane co gałąź źródłowa podczas tworzenia. Zastąp identyfikatory projektów i gałęzi rzeczywistymi wartościami:

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

Uwaga / Notatka

Podczas tworzenia gałęzi należy określić zasady wygasania. Użyj no_expiry: true, aby utworzyć gałąź stałą.

Aby użyć zmiennych powłoki wewnątrz specyfikacji JSON (na przykład $PROJECT_ID lub $BRANCH_ID), użyj podwójnych cudzysłowów dla wartości --json i zastosuj znaki ucieczki przy wewnętrznych cudzysłowach.

Usługa Lakebase automatycznie tworzy gałąź funkcji z podstawowym punktem końcowym obliczeniowym odczytu i zapisu. Po zakończeniu programowania i testowania w gałęzi funkcji można go usunąć:

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

Uwaga / Notatka

Polecenia usuwania są zwracane natychmiast, ale rzeczywiste usunięcie może zająć trochę czasu. Usunięcie można zweryfikować, uruchamiając odpowiednie polecenie get resource, które zwraca błąd po pełnym usunięciu zasobu.

Aktualizowanie ochrony gałęzi

Zaktualizuj zasób przy użyciu wzorca maski aktualizacji. Maska aktualizacji określa, które pola mają być aktualizowane:

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

W tym przykładzie ustawiono wartość spec.is_protectedtrue, dzięki czemu gałąź jest chroniona. Maska aktualizacji (spec.is_protected) informuje interfejs API, które pole ma być aktualizowane. Polecenie zwraca zaktualizowany zasób z nową wartością i zaktualizowaną update_time sygnaturą czasową.

Zarządzanie obliczeniami

Pobierz szczegóły zasobów obliczeniowych

Uzyskaj szczegółowe informacje o punkcie końcowym:

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

Polecenie zwraca typ punktu końcowego, ustawienia skalowania automatycznego, bieżący stan, host połączenia, limit czasu wstrzymania i znaczniki czasu.

Skaluj odczyty za pomocą replik odczytowych.

Dodaj repliki do odczytu, aby obsługiwać zwiększony ruch odczytu. Poniższy przykład dodaje replikę do odczytu do domyślnej gałęzi produkcyjnej:

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

Możesz utworzyć wiele replik do odczytu z różnymi identyfikatorami punktów końcowych (read-replica-1, read-replica-2itp.), aby dystrybuować obciążenia odczytu.

Aktualizowanie limitów skalowania automatycznego

Aby zaktualizować wiele pól, użyj listy rozdzielanej przecinkami:

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

Konfigurowanie skalowania do zera

Aby skonfigurować skalowanie do zera, uwzględnij spec.suspension w masce aktualizacji. Ustaw suspend_timeout_duration wartość (60s–604800s), aby zdefiniować limit czasu braku aktywności lub no_suspension: true wyłączyć go. Nie ustawiaj obu tych jednocześnie. Ustawienie no_suspension: false jest nieprawidłowe i zwraca błąd. Domyślnie dla gałęzi production włączono skalowanie do zera z 24-godzinnym limitem czasu.

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

Zarządzanie rolami

Użyj interfejsu wiersza polecenia, aby utworzyć role bazy danych Postgres i zarządzać nimi na potrzeby dostępu do bazy danych w gałęzi. Aby uzyskać szczegółowe wskazówki dotyczące typów ról i uwierzytelniania, zobacz Tworzenie ról Postgres.

Tworzenie roli

Utwórz rolę opartą na hasłach:

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

Utwórz rolę OAuth powiązaną z tożsamością Azure Databricks:

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

Listuj i pobieraj role

Lista wszystkich ról w gałęzi:

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

Uzyskaj szczegółowe informacje o określonej roli:

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

Odpowiedź zawiera nazwę zasobu roli wygenerowanej przez system (na przykład rol-xxxx-xxxxxxxxxx) wymaganą do wywołań aktualizacji i usuwania.

Aktualizowanie roli

Zaktualizuj rolę przy użyciu wzorca maski aktualizacji. Przekaż maskę aktualizacji jako drugi argument pozycyjny.

Podczas aktualizowania spec.attributeselementu należy podać wszystkie trzy pola atrybutów — interfejs API zastępuje cały obiekt atrybutów:

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

Usuwanie roli

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

Jeśli rola jest właścicielem obiektów bazy danych, użyj polecenia --reassign-owned-to , aby przenieść własność przed usunięciem:

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

Zarządzanie zsynchronizowanych tabel

Tabele zsynchronizowane replikują dane z Unity Catalog do bazy danych Lakebase na potrzeby operacyjnych odczytów o niskich opóźnieniach. Użyj create-synced-table z identyfikatorem {catalog}.{schema}.{table} :

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

Identyfikator zsynchronizowanej tabeli jest zarówno nazwą obiektu Unity Catalog, jak i identyfikatorem tabeli Postgres. Pobierz stan i usuń zsynchronizowaną tabelę z tym samym formatem identyfikatora:

# 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 i create-catalog są długotrwałymi operacjami. Domyślnie CLI czeka na zakończenie. Użyj --no-wait, aby natychmiast wrócić, lub --timeout, aby ustawić niestandardowy czas oczekiwania. Zobacz Długotrwałe operacje.

Aby uzyskać szczegółowe wskazówki dotyczące trybów synchronizacji, mapowania typów danych i planowania pojemności, zobacz Udostępnianie danych lakehouse przy użyciu zsynchronizowanych tabel.

Opis kluczowych pojęć

Długotrwałe operacje

Polecenia tworzenia, aktualizowania i usuwania są długotrwałymi operacjami. Domyślnie CLI czeka na zakończenie operacji. Użyj polecenia --no-wait, aby natychmiast wrócić i sondować stan oddzielnie.

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

Sonduj stan operacji:

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

Nazewnictwo zasobów

Usługa Lakebase używa hierarchicznych nazw zasobów:

Projekty: projects/{project_id}. Identyfikator projektu należy określić podczas tworzenia projektu.
Gałęzie: projects/{project_id}/branches/{branch_id}. Identyfikator gałęzi należy określić podczas tworzenia gałęzi.
Punkty końcowe: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Identyfikator punktu końcowego (na przykład primary lub read-replica-1) należy określić podczas tworzenia punktu końcowego.

Identyfikatory muszą mieć długość od 1 do 63 znaków, zaczynać się od małej litery i zawierać tylko małe litery, cyfry i łączniki.

Aktualizuj maski

Polecenia aktualizacji wymagają maski aktualizacji określającej, które pola mają być modyfikowane. Maska jest ścieżką pola, na przykład spec.display_name lub listą rozdzielaną przecinkami dla wielu pól.

--json Ładunek zawiera nowe wartości dla tych pól. Modyfikowane są tylko pola wymienione w masce aktualizacji.

Dodatkowe zasoby

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-11