開始使用 Lakebase 的 Databricks CLI

本指南將協助你開始使用 Databricks CLI，管理你的 Lakebase 專案、分支及計算（端點）。你只需幾個指令就能學會如何建立一個可運作的專案。

欲了解完整指令參考及所有可用選項，請參閱 Databricks CLI 的 postgres 指令。

先決條件

Databricks CLI：安裝 Databricks CLI。請參見安裝 Databricks CLI。
工作區存取權：您必須能存取 Lakebase 資源所在的 Azure Databricks 工作區。

驗證 Azure Databricks

在執行任何 CLI 指令前，先用你的 Azure Databricks 工作空間進行認證：

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

用你實際的工作區網址替換 https://your-workspace.cloud.databricks.com 。這個指令會開啟一個瀏覽器視窗，讓你用 OAuth 與你的 Azure Databricks 帳號進行認證。

備註

如果你有多個設定檔，請使用 --profile 旗標指定要使用哪一個： databricks postgres <command> --profile my-profile。要查看你設定的設定檔，請執行 databricks auth profiles。

欲了解更多認證選項，請參閱 Databricks 認證。

取得命令說明

CLI 為所有指令提供內建協助。用 --help 來查看可用的指令和選項。

了解所有 Postgres 指令的概覽：

databricks postgres --help

該指令顯示所有可用指令、全域旗標及資源命名慣例的資訊。

針對特定指令獲得詳細協助：

databricks postgres create-project --help

這會顯示指令的目的、必要與可選參數、使用範例，以及可用的旗標。

快速入門：建立你的第一個專案

請依照以下步驟建立一個帶有分支與運算端點的專案：

1. 建立專案

建立 Lakebase 專案：

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

此指令會建立專案並等待其完成。專案 ID （my-project）會成為資源名稱的一部分： projects/my-project。專案以預設的生產分支和讀寫計算端點建立，兩者皆有自動產生的 ID。

可選擇性地將專案 ID 匯出為變數，用於後續指令：

export PROJECT_ID="my-project"

2. 取得分行識別碼

列出你專案中的分支，以找到預設的分支 ID：

databricks postgres list-branches projects/$PROJECT_ID

此系統會回傳專案中所有分支的資訊。尋找具有 "default": true 狀態的分支。請注意欄位中的 name 分支 ID（例如 production 預設分支）。

可選擇性地將分支 ID 匯出為變數，用於後續指令：

export BRANCH_ID="production"

用清單輸出中實際的分支 ID 替換 production 。

3. 取得端點 ID

列出你分支中的端點。預設分支會自動包含一個讀寫端點：

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

請注意欄位中的 name 端點 ID（例如 primary 預設的讀寫端點）。可選擇性地匯出為變數：

export ENDPOINT_ID="primary"

用清單輸出中的實際端點 ID 替換 primary 。

4. 產生資料庫憑證

產生憑證以連接您的資料庫：

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

這個指令會回傳一個 OAuth 標記，你可以用 PostgreSQL 客戶端 psql ，利用你的 Databricks 身份存取你的資料。關於如何與 psql 連接的逐步說明，請參見「Connect with psql」。欲了解更多關於令牌到期與認證的資訊，請參閱認證。

管理專案

列出專案

列出你工作區中的所有專案：

databricks postgres list-projects

指令會回傳每個專案的名稱、顯示名稱、目前狀態和時間戳記。

獲取專案詳情

獲取專案詳細資訊：

databricks postgres get-project projects/$PROJECT_ID

該指令會回傳專案的顯示名稱、PostgreSQL 版本、擁有者、歷史保留期限、分支大小限制、儲存空間大小及時間戳記。

管理分支

取得分行詳情

獲取分行詳細資訊：

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

指令會回傳分支的當前狀態、保護狀態、邏輯大小、來源分支細節（如適用）及時間戳記。

建立功能分支

根據現有分支建立一個新分支來測試變更。當你指定source_branch時，新分支在建立時將擁有與來源分支相同的模式和資料。將專案和分支 ID 換成你的實際值：

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

備註

建立分支時，必須指定一個過期政策。用 no_expiry: true 來建立永久分支。

若要在 JSON 規格中使用 shell 變數（例如 $PROJECT_ID 或 $BRANCH_ID），請將 --json 的值用雙引號括起來，並逸出內部引號。

Lakebase 會自動建立帶有主要讀寫運算端點的功能分支。完成功能分支的開發與測試後，你可以刪除它：

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

備註

刪除指令會立即回傳，但實際刪除可能需要時間才能完成。你可以透過執行對應的 get resource 指令來驗證刪除，該指令在資源完全刪除後會回傳錯誤。

更新分支保護

使用 update mask 模式更新資源。更新遮罩指定要更新哪些欄位：

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

此範例設 spec.is_protected 為 true，使該分支受到保護。更新遮罩（spec.is_protected）告訴 API 要更新哪個欄位。指令會回傳更新後的資源，顯示新值和更新的時間 update_time 戳。

管理運算

取得運算詳細資料

獲取關於終點的詳細資訊：

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

該指令會回傳端點類型、自動縮放設定、目前狀態、連線主機、暫停逾時及時間戳記。

擴展讀取能力並使用讀取副本

新增讀取副本以處理增加的讀取流量。以下範例將讀取副本加入預設生產分支：

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

你可以建立多個具有不同端點 ID（read-replica-1、、 read-replica-2等）的讀取副本來分配讀取工作負載。

更新自動縮放限制

要更新多個欄位，請使用逗號分隔的清單：

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

將縮放設定為零

若要將擴縮設為零，請在更新遮罩中加入 spec.suspension。設定 suspend_timeout_duration （60秒–604800秒）來定義非活動逾時，或 no_suspension: true 停用它。不要同時設定兩者。設定 no_suspension: false 無效且會回傳錯誤。預設情況下，分支 production 啟用了縮放至零（scale to zero）並設有 24 小時逾時。

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

管理職務

使用 CLI 來建立並管理 Postgres 角色，以便在分支內存取資料庫。有關角色類型與認證的詳細指引，請參閱「建立 Postgres 角色」。

建立角色

建立基於密碼的角色：

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

建立與 Azure Databricks 身份連結的 OAuth 認證角色：

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

列出並取得角色

列出該分支的所有職務：

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

了解特定職位的詳細資訊：

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

回應包含系統產生的角色資源名稱（例如， rol-xxxx-xxxxxxxxxx），用於更新與刪除呼叫。

更新角色

使用 update mask 模式來更新角色。將更新遮罩作為第二個位置參數傳遞。

更新 spec.attributes時，你必須提供三個屬性欄位——API 會替換整個屬性物件：

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

刪除角色

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

如果該角色擁有資料庫物件，請在刪除前使用 --reassign-owned-to 轉移所有權：

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

管理同步資料表

同步資料表會將 Unity 目錄資料複製到 Lakebase 資料庫，實現低延遲的操作讀取。使用 create-synced-table，搭配 {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
    }
  }'

同步的表格 ID 同時成為 Unity 目錄實體名稱，並識別 Postgres 表格。取得狀態並刪除一個相同 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 和 create-catalog 是長時間執行的作業。預設情況下，CLI 會等待完成。用 --no-wait 來立即退貨或 --timeout 設定自訂等待時間。參見長時間執行的操作。

關於同步模式、資料類型映射及容量規劃的詳細指引，請參閱「以同步資料表服務湖屋資料」。

理解關鍵概念

長時間執行的作業

建立、更新和刪除指令是長時間執行的操作。預設情況下，CLI 會等待操作完成。使用 --no-wait 立即返回並分別查詢狀態。

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

調查營運狀態：

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

資源命名

Lakebase 使用階層式資源名稱：

專案： projects/{project_id} 建立專案時你要指定專案 ID。
分支： projects/{project_id}/branches/{branch_id}。建立分支時要指定分支 ID。
終點： projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}。建立端點時，你要指定端點 ID（例如 primaryread-replica-1或）。

ID 必須長度為 1 到 63 個字元，以小寫字母開頭，且僅包含小寫字母、數字和連字號。

更新遮罩

Update 指令需要一個更新遮罩，指定要修改哪些欄位。遮罩可以是像 spec.display_name 這樣的欄位路徑，或者是多個欄位的逗號分隔列表。

--json負載包含這些欄位的新值。只有更新遮罩中列出的欄位會被修改。

其他資源

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-11