開始使用 Lakebase 的 Databricks CLI

這很重要

Lakebase 自動縮放在以下地區處於 Beta 階段：eastus2、westeurope、westus。

Lakebase 自動縮放是 Lakebase 的最新版本，具備自動縮放運算、縮放至零、分支及即時還原功能。關於與 Lakebase Provisioned 的功能比較，請參見「選擇版本」。

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

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

先決條件

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

使用 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（例如 br-divine-sea-y2k942xa）。

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

export BRANCH_ID="br-divine-sea-y2k942xa"

用清單輸出中你實際的預設分支 ID 來替換 br-divine-sea-y2k942xa 。

3. 取得端點 ID

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

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

請注意欄位中的 name 端點 ID。它會以格式 projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}。擷取端點 ID（例如 ep-plain-sunset-y2vc0zan），並可選擇匯出為變數：

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

用清單輸出中的實際端點 ID 替換 ep-plain-sunset-y2vc0zan 。

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

此會回傳詳細的分支資訊，包括目前狀態、預設分支狀態、保護狀態、邏輯大小、來源分支細節（若是從其他分支分支），以及建立/更新時間戳記。

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

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

此會回傳詳細的端點配置，包括端點類型（讀寫或唯讀）、自動縮放設定（最小與最大運算單元）、當前狀態（ACTIVE、IDLE 等）、連線主機、暫停逾時，以及建立/更新時間戳。

更新資源

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

常見工作流程

從生產環境建立一個功能分支

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

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

備註

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

要在 JSON 規範中使用 shell 變數（例如 $PROJECT_ID 或 $BRANCH_ID），你需要用雙引號表示 --json 值，並跳出內部引號。

功能分支需要一個讀寫計算端點，以允許資料庫操作：

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

完成功能分支的開發與測試後，你可以刪除它：

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

備註

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

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

新增讀取副本以處理增加的讀取流量。此範例在預設生產分支中新增一個讀取副本：

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等）的讀取副本來分配讀取工作負載。

理解關鍵概念

長時間執行的作業

建立、更新和刪除指令是長時間執行的操作。預設情況下，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-02-07