Začínáme s rozhraním příkazového řádku Databricks pro Lakebase

Tato příručka vám pomůže začít s Databricks CLI pro správu vašich Lakebase projektů, větví a výpočtů (koncových bodů). V několika příkazech se dozvíte, jak vytvořit pracovní projekt.

Pro úplnou referenci příkazů a všechny dostupné možnosti viz Příkazy postgres Databricks CLI.

Požadavky

• Rozhraní příkazového řádku Databricks: Nainstalujte rozhraní příkazového řádku Databricks. Viz Instalace rozhraní příkazového řádku Databricks.
• Přístup k pracovnímu prostoru: Musíte mít přístup k pracovnímu prostoru Azure Databricks, kde se nachází prostředek Lakebase.

Ověřování pomocí Azure Databricks

Před spuštěním příkazů rozhraní příkazového řádku se ověřte v pracovním prostoru Azure Databricks:

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

Nahraďte https://your-workspace.cloud.databricks.com skutečnou adresou URL pracovního prostoru. Tento příkaz otevře okno prohlížeče pro ověření pomocí účtu Azure Databricks pomocí OAuth.

Poznámka:

Pokud máte více profilů, pomocí příznaku --profile určete, který z nich se má použít: databricks postgres <command> --profile my-profile. Pokud chcete zobrazit nakonfigurované profily, spusťte databricks auth profilespříkaz .

Další možnosti ověřování najdete v tématu Ověřování Databricks.

Získání nápovědy k příkazům

Rozhraní příkazového řádku poskytuje integrovanou nápovědu pro všechny příkazy. Umožňuje --help zobrazit dostupné příkazy a možnosti.

Získejte přehled všech příkazů Postgres:

databricks postgres --help

Příkaz zobrazí všechny dostupné příkazy, globální příznaky a informace o konvencích pojmenování prostředků.

Získejte podrobnou nápovědu pro konkrétní příkaz:

databricks postgres create-project --help

Zobrazí se účel příkazu, povinné a volitelné parametry, příklady použití a dostupné příznaky.

Rychlý start: Vytvoření prvního projektu

Projekt s větví a výpočetním koncovým bodem vytvoříte takto:

1. Vytvoření projektu

Vytvoření projektu Lakebase:

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

Tento příkaz vytvoří projekt a počká na jeho dokončení. ID projektu (my-project) se stane součástí názvu zdroje: projects/my-project. Projekt se vytvoří s výchozí produkční větví a koncovým bodem výpočetního prostředí pro čtení i zápis, oba s automaticky generovanými ID.

Volitelně můžete ID projektu exportovat jako proměnnou, která se použije v následujících příkazech:

export PROJECT_ID="my-project"

2. Získání ID větve

Vypište větve v projektu a vyhledejte výchozí ID větve:

databricks postgres list-branches projects/$PROJECT_ID

Vrátí informace o všech větvích v projektu. Vyhledejte větev se stavem "default": true . Poznamenejte si ID větve z name pole (například production pro výchozí větev).

Volitelně můžete ID větve exportovat jako proměnnou pro použití v dalších příkazech:

export BRANCH_ID="production"

Nahraďte production skutečným ID větve z výstupu seznamu.

3. Získání ID koncového bodu

Vypište koncové body ve vaší větvi. Výchozí větev automaticky zahrnuje koncový bod pro čtení i zápis:

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

Poznamenejte si ID koncového name bodu z pole (například primary výchozí koncový bod pro čtení i zápis). Volitelně ho exportujte jako proměnnou:

export ENDPOINT_ID="primary"

Nahraďte primary skutečným ID koncového bodu z výstupu seznamu.

4. Generování přihlašovacích údajů databáze

Vygenerujte přihlašovací údaje pro připojení k databázi:

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

Příkaz vrátí token OAuth, který můžete použít s klienty PostgreSQL, jako je psql, pro přístup k vašim datům pomocí vaší identity Databricks. Podrobné pokyny k připojení pomocí psql najdete v tématu Připojení pomocí psql. Další informace o vypršení platnosti tokenu a ověřování najdete v tématu Ověřování.

Správa projektů

Výpis projektů

Zobrazení seznamu všech projektů v pracovním prostoru:

databricks postgres list-projects

Příkaz vrátí název každého projektu, zobrazovaný název, aktuální stav a časové razítka.

Získání podrobností o projektu

Získejte podrobné informace o projektu:

databricks postgres get-project projects/$PROJECT_ID

Příkaz vrátí zobrazovaný název projektu, verzi PostgreSQL, vlastníka, dobu uchovávání historie, omezení velikosti větve, velikost úložiště a časová razítka.

Správa branchí

Získání podrobností o větvi

Získejte podrobné informace o větvi:

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

Příkaz vrátí aktuální stav, stav ochrany, logickou velikost, podrobnosti zdrojové větve (pokud je k dispozici) a časové razítko.

Vytvořte větev funkcionality

Vytvořte novou větev založenou na existující větvi, která bude testovat změny. Když zadáte source_branch, nová větev bude mít stejné schéma a data jako zdrojová větev v době vytvoření. Nahraďte ID projektu a větve skutečnými hodnotami:

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

Poznámka:

Při vytváření větve musíte zadat politiku vypršení platnosti. Použijte no_expiry: true k vytvoření trvalé větve.

Pokud chcete použít proměnné shellu uvnitř specifikace JSON (například $PROJECT_ID nebo $BRANCH_ID), použijte u hodnoty --json dvojité uvozovky a vnitřní uvozovky escapujte.

Lakebase automaticky vytvoří větev funkce s primárním koncovým bodem výpočetního prostředí pro čtení i zápis. Po dokončení vývoje a testování ve větvi funkcí ji můžete odstranit:

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

Poznámka:

Příkazy odstranění se vrátí okamžitě, ale dokončení skutečného odstranění může chvíli trvat. Odstranění můžete ověřit spuštěním odpovídajícího příkazu get resource, který vrátí chybu po úplném odstranění prostředku.

Aktualizace ochrany větví

Aktualizujte prostředek pomocí vzoru aktualizační masky. Maska aktualizace určuje, která pole se mají aktualizovat:

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

V tomto příkladu se nastaví spec.is_protected na true, což zajistí ochranu větve. Maska aktualizace (spec.is_protected) říká rozhraní API, které pole se má aktualizovat. Příkaz vrátí aktualizovaný zdroj, který zobrazuje novou hodnotu a aktualizované update_time časové razítko.

Správa výpočetních prostředků

Získat podrobnosti o výpočetních prostředcích

Získejte podrobné informace o koncovém bodu:

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

Příkaz vrátí typ koncového bodu, nastavení automatického škálování, aktuální stav, hostitele připojení, pozastavení časového limitu a časové razítko.

Škálování výkonu čtení pomocí čtecích replik

Přidejte repliky pro čtení pro zvládání zvýšeného provozu na čtení. Následující příklad přidá repliku pro čtení do výchozí produkční větve:

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

Pro distribuci úloh čtení můžete vytvořit několik replik pro čtení s různými ID koncových bodů (read-replica-1read-replica-2atd.).

Aktualizace omezení automatického škálování

Pokud chcete aktualizovat více polí, použijte seznam oddělený čárkami:

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

Konfigurace škálování na nulu

Pokud chcete nakonfigurovat škálování na nulu, zahrňte spec.suspension do masky aktualizace. Nastavte suspend_timeout_duration (60s–604800s) a definujte časový limit nečinnosti nebo no_suspension: true ho zakažte. Nenastavujte obojí. Nastavení no_suspension: false je neplatné a vrátí chybu. Ve výchozím nastavení production má větev povolené škálování na nulu s časovým limitem 24 hodin.

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

Správa rolí

Pomocí rozhraní příkazového řádku můžete vytvářet a spravovat role Postgres pro přístup k databázi v rámci větve. Podrobné pokyny k typům rolí a ověřování najdete v tématu Vytvoření rolí Postgres.

Vytvoření role

Vytvořte roli založenou na heslech:

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

Vytvořte roli OAuth svázanou s Azure Databricks identitou:

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

Výpis a zobrazení rolí

Výpis všech rolí ve větvi:

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

Získejte podrobnosti o konkrétní roli:

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

Odpověď obsahuje název prostředku role generované systémem (například rol-xxxx-xxxxxxxxxx) vyžadovaný pro volání aktualizace a odstranění.

Aktualizace role

Aktualizujte roli pomocí vzoru masky pro aktualizaci. Předejte masku aktualizace jako druhý poziční argument.

Při aktualizaci spec.attributesje nutné zadat všechna tři pole atributů – rozhraní API nahradí celý objekt atributů:

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

Odstranění role

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

Pokud role vlastní databázové objekty, použijte --reassign-owned-to k převodu vlastnictví před odstraněním:

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

Správa synchronizovaných tabulek

Synchronizované tabulky replikují data katalogu Unity do databáze Lakebase pro provozní čtení s nízkou latencí. Použijte create-synced-table s ID {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
    }
  }'

ID synchronizované tabulky se stane názvem entity Unity Catalog a identifikuje tabulku Postgres. Získejte stav a odstraňte synchronizovanou tabulku se stejným formátem ID:

# 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 a create-catalog jsou dlouhotrvající operace. Ve výchozím nastavení CLI čeká na dokončení. Slouží --no-wait k okamžitému vrácení nebo --timeout nastavení vlastní doby čekání. Viz dlouhotrvající operace.

Podrobné pokyny k režimům synchronizace, mapování datových typů a plánování kapacity najdete v tématu Obsluha dat lakehouse se synchronizovanými tabulkami.

Pochopení klíčových konceptů

Dlouhotrvající operace

Příkazy vytvoření, aktualizace a odstranění jsou dlouhotrvající operace. Ve výchozím nastavení rozhraní příkazového řádku čeká na dokončení operace. Použijte --no-wait k okamžitému návratu a samostatnému sledování stavu.

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

Zkontrolujte stav operace:

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

Pojmenování zdrojů

Lakebase používá názvy hierarchických prostředků:

• Projekty: projects/{project_id}. Při vytváření projektu zadáte ID projektu.
• Větve: projects/{project_id}/branches/{branch_id}. Při vytváření větve zadáte ID větve.
• Koncové body: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Při vytváření koncového bodu zadáte ID koncového bodu (například primary nebo read-replica-1).

ID musí mít délku 1 až 63 znaků, musí začínat malým písmenem a obsahovat jenom malá písmena, číslice a pomlčky.

Aktualizace masek

Příkazy aktualizace vyžadují masku aktualizace, která určuje pole, která se mají upravit. Maska je cesta pole jako spec.display_name nebo seznam více polí oddělený čárkami.

Náklad --json obsahuje nové hodnoty těchto polí. Upraví se jenom pole uvedená v masce aktualizace.

Další zdroje informací

• Referenční příručka příkazů postgres pro Databricks CLI
• Vytvoření rolí Postgres
• Připojení s využitím psql
• Správa branchí
• Konfigurace automatického škálování
• Obsluha dat lakehouse se synchronizovanými tabulkami