管理專案

專案是你 Lakebase 資源的頂層容器，包括分支、運算、資料庫和角色。 本頁說明如何建立專案、了解其結構、設定管理及生命週期管理。

如果你是 Lakebase 新手，建議先從 「開始 」開始建立你的第一個專案。

理解專案

專案結構

了解 Lakebase 專案結構有助於你有效組織和管理資源。 專案是你資料庫、分支、計算及相關資源的頂層容器。 每個專案包含計算預設值、還原視窗及適用於專案內所有分支的更新設定。

在頂層，專案包含一個或多個分支。 在專案中，你可以為不同環境建立分支，例如開發、測試、暫定和生產環境。 每個分支包含自己的運算、角色與資料庫。

Project
  └── Branches (main, development, staging, etc.)
        ├── Computes (R/W compute)
        ├── Roles (Postgres roles)
        └── Databases (Postgres databases)

分支

資料存在於分支中。 每個 Lakebase 專案都會建立一個名為 production的根分支，該分支無法刪除。 雖然你可以建立額外的分支並指定另一個分支作為預設分支，但根分支無法被刪除。

你可以從專案中的任何分支建立子分支。 當你建立子分支時，它會繼承建立時父分支的所有資料庫、角色和資料。 父分支的後續變更不會自動傳入子分支，從而實現獨立的開發、測試或實驗。

每個分支可以包含多個資料庫和角色。 了解更多：管理分支

計算

運算是一種虛擬化的運算資源，包含用於執行 PostGres 的虛擬CPU與記憶體。 當你建立專案時，會為專案的預設分支建立一個主要的 R/W（讀寫）運算。 每個分支都有一個主要的 R/W 運算。 要連接到位於分支上的資料庫，必須透過該分支所關聯的 R/W 運算系統連接。

除了主要的 R/W 運算外，你還可以在任何分支中新增一個或多個讀取複本（唯讀）運算。 讀取副本讓你能將主要運算中的唯讀工作負載卸載，用於水平讀取擴展、分析與報告查詢，以及使用者或應用程式的唯讀存取等使用場景。 了解更多： 管理運算、 讀取複本

角色

角色是Postgres角色。 需要一個角色來建立和存取資料庫。 角色屬於分支。 當你建立專案時，會自動為你的 Databricks 身份（例如 user@databricks.com）建立一個 Postgres 角色，該身份是預設 databricks_postgres 資料庫的擁有者。 在 Lakebase UI 中建立的任何角色都是有 databricks_superuser 權限的。 每個分支的職缺數量上限為500個。 了解更多： 管理職務

資料庫

資料庫是儲存 SQL 物件的容器，例如結構、資料表、檢視、函式和索引。 在 Lakebase 中，資料庫屬於分行。 你的專案預設分支會用一個名為 databricks_postgres的資料庫建立。 每個分行的資料庫數量限制為500個。 了解更多： 管理資料庫

資料庫綱要

Lakebase 中的所有資料庫都是以 public 結構建立的，這是任何標準 Postgres 實例的預設行為。 SQL 物件預設是在結構中 public 建立的。

專案限制

Lakebase Postgres 對專案執行以下限制：

同時啟用運算上限

同時啟用的運算限制限制同時執行的運算數量，以防止資源耗盡。 此限制可防止意外資源激增，例如同時啟動多個運算端點。 預設限制是每個專案同時進行 20 次運算。

重要： 預設分支不受此限制限制，確保隨時可用。

當你超過限制時，超出限制的額外運算會被暫停，且嘗試連接時會看到錯誤。 若要解決此問題：

1. 暫停其他活躍運算，再試一次。
2. 如果你經常遇到這個錯誤，請聯絡 Databricks 客服申請提高限額。

資料庫儲存配額

每個分行都有資料庫儲存配額。 這是操作配額而非架構限制，因為資料存放於雲端物件儲存，而非配置好的本地磁碟。 如果你需要更多配額，請聯絡 Databricks 客服。

當資料庫達到配額時，寫入效能會下降，但你仍可丟棄或刪除資料來回收空間。

計算器會在下一次啟動或重啟時接收當前配額。 已經在執行的運算會繼續使用它起始的配額，直到下一次重啟。

只有你的實際資料（Postgres 報告的表格和索引）會計入配額。 保留歷史以供 時間點還原 則不然。

區域可用性

支援的區域：

• eastus （美國東部）
• eastus2 （美國東2號公路）
• centralus （美國中部）
• northcentralus （美國中北部）
• southcentralus （美國中南部）
• westus （美國西部）
• westus2 （美國西部2號公路）
• canadacentral （加拿大中央）
• brazilsouth （巴西南部）
• northeurope （北歐）
• uksouth （英國南部）
• westeurope （西歐）
• francecentral （法國中央）
• germanywestcentral （德國西中部）
• australiaeast （澳洲東部）
• centralindia （中印度）
• southeastasia （東南亞）
• eastasia （東亞）
• japaneast （日本東）

你的 Lakebase 專案是在你的 Databricks 工作區區域建立的。

Postgres 版本支援

Lakebase Postgres 自動縮放支援 Postgres 16、Postgres 17 和 Postgres 18。 Postgres 17 是預設版本。 要使用 Postgres 18，請在建立新專案時選擇它。

創建與管理專案

建立一個專案

你可以在 Lakebase Postgres 建立多個專案，讓應用程式或客戶完全隔離，確保資料與資源的乾淨分離。

要建立專案：

UI

1. 點擊右上角的應用程式切換器即可開啟 Lakebase 應用程式。
2. 點擊 新專案。
3. 設定你的專案設定：
   • 顯示名稱：輸入專案名稱。 你可以使用任何字元，包括空格和特殊字元。 常見的命名模式包括以應用程式命名（例如 My Analytics App），或以專案服務的客戶或租戶命名（例如 Acme Corp DB）。 資源名稱會自動從你的顯示名稱衍生，並用來在 API 和 SDK 呼叫中識別專案。 對話框會顯示產生的資源名稱（例如， projects/my-analytics-app），讓你在建立專案前可以驗證。
   • Postgres 版本：選擇你想使用的 Postgres 版本。
   • 無伺服器使用政策 （可選）：選擇一個無伺服器使用政策，將無伺服器計算成本歸因於特定政策。 請參閱 無伺服器使用政策。

建立專案對話框會顯示專案設定選項。

你的 Lakebase 專案的 區域 設定為你的 Databricks 工作區區域，且無法修改。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

# Initialize the Workspace client
w = WorkspaceClient()

# Create a project with a custom project ID
operation = w.postgres.create_project(
    project=Project(
        spec=ProjectSpec(
            display_name="My Application",
            pg_version=17,
            budget_policy_id="<policy-id>"
        )
    ),
    project_id="my-app"
)

# Wait for operation to complete
result = operation.wait()
print(f"Created project: {result.name}")
print(f"Display name: {result.status.display_name}")
print(f"Postgres version: {result.status.pg_version}")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

// Initialize the Workspace client
WorkspaceClient w = new WorkspaceClient();

// Create a project with a custom project ID
CreateProjectOperation operation = w.postgres().createProject(
    new CreateProjectRequest()
        .setProjectId("my-app")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setDisplayName("My Application")
                .setPgVersion(17L)))
);

// Wait for operation to complete
Project result = operation.waitForCompletion();
System.out.println("Created project: " + result.getName());
System.out.println("Display name: " + result.getStatus().getDisplayName());
System.out.println("Postgres version: " + result.getStatus().getPgVersion());

CLI

# Create a project with a custom project ID
databricks postgres create-project my-app \
  --json '{
    "spec": {
      "display_name": "My Application",
      "pg_version": 17,
      "budget_policy_id": "<policy-id>"
    }
  }'

curl (Unix指令)

建立一個自訂專案 ID 的專案。 該 project_id 參數被指定為查詢參數，並成為專案資源名稱的一部分（例如， projects/my-app）。

curl -X POST "$WORKSPACE/api/2.0/postgres/projects?project_id=my-app" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "display_name": "My Application",
      "pg_version": 17,
      "budget_policy_id": "<policy-id>"
    }
  }' | jq

這是一個持續很久的行動。 回應會包含一個操作名稱，你可以用來查詢狀態。 手術通常在幾秒內完成。

project_id 是必要參數。

新專案預設包含以下資源：

• 單一 production 分支（預設分支）

• 與分支相關聯的單一主要讀寫運算，預設設定如下：

  分支	計算單位 （CU）	高可用性	Autoscaling	自動縮減至零
  production	8 - 16 CU	Disabled	Enabled	啟用（24小時）

  當你建立專案時，系統會建立 production 分支，並預設為其建立一個已啟用「縮減為零」功能的運算資源，閒置逾時時間為 24 小時。 如果需要，你可以調整此運算資源的逾時時間，或關閉縮減至零。

• 一個名為 databricks_postgres的 Postgres 資料庫

• 適用於 Databricks Identity 的 Postgres 角色（例如，user@databricks.com）

若要更改現有專案的計算設定，請參見 「配置專案設定」。 若要修改新專案的預設運算設定，請參閱「配置專案設定」中的「計算預設值」。

獲取專案詳情

取得特定專案的詳細資訊。

UI

1. 點擊右上角的應用程式切換器即可開啟 Lakebase 應用程式。
2. 從專案列表中選擇您的專案以查看詳細資料。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Get project details
project = w.postgres.get_project(name="projects/my-project")

print(f"Project: {project.name}")
print(f"Display name: {project.status.display_name}")
print(f"Postgres version: {project.status.pg_version}")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.Project;

WorkspaceClient w = new WorkspaceClient();

// Get project details
Project project = w.postgres().getProject("projects/my-project");

System.out.println("Project: " + project.getName());
System.out.println("Display name: " + project.getStatus().getDisplayName());
System.out.println("Postgres version: " + project.getStatus().getPgVersion());

CLI

# Get project details
databricks postgres get-project projects/my-project

curl (Unix指令)

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

回應內容包括：

• name： 資源名稱 （projects/my-project）
• status：Project配置與當前狀態（display_name、pg_version等）

注意：該 spec 欄位未被填入用於 GET 操作。 所有資源屬性都會在 status 欄位回傳。

列出專案

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

UI

1. 點擊右上角的應用程式切換器即可開啟 Lakebase 應用程式。
2. 專案清單會顯示你能存取的所有專案。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# List all projects
projects = w.postgres.list_projects()

for project in projects:
    print(f"Project: {project.name}")
    print(f"  Display name: {project.status.display_name}")
    print(f"  Postgres version: {project.status.pg_version}")

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// List all projects
for (Project project : w.postgres().listProjects(new ListProjectsRequest())) {
    System.out.println("Project: " + project.getName());
    System.out.println("  Display name: " + project.getStatus().getDisplayName());
    System.out.println("  Postgres version: " + project.getStatus().getPgVersion());
}

CLI

# List all projects
databricks postgres list-projects

curl (Unix指令)

curl -X GET "$WORKSPACE/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

回應格式：

{
  "projects": [
    {
      "name": "projects/my-project",
      "status": {
        "display_name": "My Project",
        "pg_version": 17
      }
    }
  ]
}

設定專案設定

建立專案後，你可以透過專案儀表板的 設定來修改各種設定：

一般設定

一般設定頁面顯示以下欄位：

• 顯示名稱：您專案中可編輯的顯示名稱。
• 資源名稱：唯讀。 你專案的完整資源路徑（格式： projects/{project_id}）。 在 API 和 SDK 呼叫中使用此值來識別專案。
• UID：唯讀。 系統為你的專案產生的唯一識別碼。
• 無伺服器使用政策：將您的專案關聯無伺服器使用政策，將無伺服器計算成本歸因於特定政策。 請參閱 無伺服器使用政策。
• 自訂標籤：為您的專案新增鍵值標籤。 標籤會記錄在您的帳戶的可計費使用紀錄（system.billing.usage）中，並可用於依團隊、專案或成本中心追蹤成本。 請參見 自訂標籤。 當你使用 API 或 CLI 更新自訂標籤時，新的清單會替換所有現有的標籤。

UI

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec, ProjectCustomTag, FieldMask

w = WorkspaceClient()

# Update project display name
w.postgres.update_project(
    name="projects/my-project",
    update_mask=FieldMask(field_mask=["spec.display_name"]),
    project=Project(spec=ProjectSpec(display_name="My Updated Project Name"))
).wait()

# Update serverless usage policy
w.postgres.update_project(
    name="projects/my-project",
    update_mask=FieldMask(field_mask=["spec.budget_policy_id"]),
    project=Project(spec=ProjectSpec(budget_policy_id="<policy-id>"))
).wait()

# Update custom tags (replaces all existing tags)
w.postgres.update_project(
    name="projects/my-project",
    update_mask=FieldMask(field_mask=["spec.custom_tags"]),
    project=Project(spec=ProjectSpec(custom_tags=[
        ProjectCustomTag(key="team", value="data-eng"),
        ProjectCustomTag(key="cost-center", value="1234")
    ]))
).wait()

CLI

# Update project display name
databricks postgres update-project projects/my-project spec.display_name \
  --json '{
    "spec": {
      "display_name": "My Updated Project Name"
    }
  }'

# Update serverless usage policy
databricks postgres update-project projects/my-project spec.budget_policy_id \
  --json '{
    "spec": {
      "budget_policy_id": "<policy-id>"
    }
  }'

# Update custom tags
databricks postgres update-project projects/my-project spec.custom_tags \
  --json '{
    "spec": {
      "custom_tags": [
        {"key": "team", "value": "data-eng"},
        {"key": "cost-center", "value": "1234"}
      ]
    }
  }'

curl (Unix指令)

# Update project display name
curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project?update_mask=spec.display_name" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "display_name": "My Updated Project Name"
    }
  }' | jq

# Update serverless usage policy
curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project?update_mask=spec.budget_policy_id" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "budget_policy_id": "<policy-id>"
    }
  }' | jq

# Update custom tags
curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project?update_mask=spec.custom_tags" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "custom_tags": [
        {"key": "team", "value": "data-eng"},
        {"key": "cost-center", "value": "1234"}
      ]
    }
  }' | jq

這些都是長期經營的行動。 回應會包含一個操作名稱，你可以用來查詢狀態。

計算預設值

這些預設值會作為你建立的任何主副本或讀取副本運算的初始設定。 修改這些預設不會改變任何現有計算的設定。

預設值：

• 運算容量： 2 ↔ 4 CU（自動擴展範圍;~4–8 GB RAM）
• 調整為零：預設為啟用——已勾選 在一段時間未活動後暫停運算，並選取 24 小時後暫停

點擊 「修改預設值 」以開啟對話框並更改這些值。

Lakebase Postgres 支援 0.5 CU 到 112 CU 的運算大小。 自動縮放適用於最高達 64 CU 的運算資源（從 0.5 開始，之後以 1 為增量遞增：1、2、3……64）。 較大的固定大小運算可達 112 CU。 每個運算單元（CU）提供 2 GB 記憶體。

代表性尺寸：

• 要啟用自動縮放，請使用滑桿設定計算大小範圍。 自動擴展會根據工作負載需求動態調整運算資源。 了解更多： 自動縮放
• 調整「歸零」設定，以增加或減少運算暫停前的非活躍運算時間（啟用時可從 60 秒延長至 7 天）。 你也可以關閉 縮放至零，以保持計算始終啟用。 了解更多： 縮放到零

歷史視窗

為你的專案設定歷史視窗長度。 預設情況下，Lakebase 會保留專案根分支的變更歷史，支援時間點還原以恢復遺失資料、查詢特定時間點的資料以調查資料問題，以及自過去狀態建立分支以支持開發工作流程。

你可以設定歷史期限從 2 天到 30 天，預設為 7 天。 請注意：

• 延長歷史視窗會增加你的儲存空間
• 歷史視窗設定會影響你專案中的所有分支

專案權限

透過授予 Azure Databricks 身份、群組和服務主體權限，控制誰能存取和管理你的 Lakebase 專案。 Project 權限決定使用者在 project 內可執行的動作，例如建立分支、管理運算及查看連線細節。

權限類型：

• 可以創建：檢視並建立專案資源
• 可用：檢視及使用專案資源（列出、檢視、連接及執行特定分支操作），無需建立或刪除專案或分支
• CAN MANAGE：完全掌控專案組態與資源

預設權限：

當您建立專案時，以下權限會自動分配：

• Project owner（建立project的使用者）：可以管理（完全控制）
• 工作區使用者：可以創建（可以檢視並建立專案）
• 工作區管理員：可以管理（完全控制）

若要授權其他使用者存取權，請參閱 管理專案權限。

更新

為了讓您的 Lakebase 運算與 Postgres 實例保持最新，Lakebase 會自動套用排程更新，包括 Postgres 的小型版本升級、安全修補程式及平台功能。 更新會套用在專案中的計算上，並需要短暫的運算重啟，只需幾秒鐘。

更新會自動套用，但你可以設定偏好的更新日期和時間。 重新啟動會在你選擇的時間範圍內進行。

有關更新的詳細資訊，請參見「管理更新」。

刪除專案

當你刪除專案時，它預設會進入軟刪除狀態，並保留 7 天後才會永久刪除。 在這個視窗內，你可以恢復專案並還原所有資料。 請參見 「恢復已刪除專案」。 若要跳過保留期並立即移除專案，請參見 「永久刪除專案」。

刪除前

Databricks 建議在刪除專案前，先刪除所有相關的 Unity 目錄目錄和同步資料表。 否則，嘗試檢視目錄或執行參考目錄的 SQL 查詢會導致錯誤。

如果你不是表格或目錄的擁有者，刪除前必須先將所有權重新分配給自己。

刪除專案

要刪除專案：

UI

1. 在 Lakebase 應用程式中進入你的專案 設定 。
2. 在 刪除專案 區塊，點擊 刪除 並輸入專案名稱以確認刪除。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Delete a project
operation = w.postgres.delete_project(name="projects/my-project")

print(f"Delete operation started: {operation.name()}")

這是一個持續很久的行動。 專案及其所有資源（分支、端點、資料庫、角色、資料）都會被刪除。

Java 開發套件

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

// Delete a project
w.postgres().deleteProject("projects/my-project");

System.out.println("Delete operation started");

這是一個持續很久的行動。 專案及其所有資源（分支、端點、資料庫、角色、資料）都會被刪除。

CLI

# Delete a project
databricks postgres delete-project projects/my-project

此指令立即返回。 該專案及其所有資源將被刪除。

curl (Unix指令)

curl -X DELETE "$WORKSPACE/api/2.0/postgres/projects/my-project" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

這是一個持續很久的行動。 回應中包含一個操作名稱，你可以用來檢查刪除狀態。

永久刪除專案

立即永久刪除 Lakebase 專案，無需等待 7 天軟刪除保留期結束：

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

operation = w.postgres.delete_project(name="projects/my-project", purge=True)
operation.wait()

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.DeleteProjectRequest;

WorkspaceClient w = new WorkspaceClient();

w.postgres().deleteProject(
    new DeleteProjectRequest()
        .setName("projects/my-project")
        .setPurge(true)
).waitForCompletion();

CLI

databricks postgres delete-project projects/my-project --purge

curl (Unix指令)

curl -X DELETE "$WORKSPACE/api/2.0/postgres/projects/my-project?purge=true" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

恢復已刪除的專案

當你刪除 Lakebase 專案時，它會進入軟刪除狀態，保留 7 天後才會永久刪除。 在這個視窗內，你可以恢復專案並還原所有資料。

修復的是什麼

恢復軟刪除的專案可恢復以下內容：

• 所有分支及其資料
• 所有 Postgres 資料庫與角色
• 所有計算端點及其配置
• Project 設定，包括計算預設值、還原視窗設定及更新偏好設定
• 專案權限

尋找已軟刪除的專案

要列出所有專案，包括軟刪除的專案，請使用參數 show_deleted 。 這對於找到你想恢復的專案資源名稱非常有用。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

for project in w.postgres.list_projects(show_deleted=True):
    print(f"Project: {project.name}")
    print(f"  Display name: {project.status.display_name}")
    if project.delete_time:
        print(f"  Deleted: {project.delete_time}")
        print(f"  Purge time: {project.purge_time}")

CLI

databricks postgres list-projects --show-deleted

curl (Unix指令)

curl -X GET "$WORKSPACE/api/2.0/postgres/projects?show_deleted=true" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

恢復專案

若要還原已軟刪除的 Lakebase 專案：

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

operation = w.postgres.undelete_project(name="projects/my-project")
operation.wait()

Java 開發套件

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.UndeleteProjectRequest;

WorkspaceClient w = new WorkspaceClient();

w.postgres().undeleteProject(
    new UndeleteProjectRequest().setName("projects/my-project")
).waitForCompletion();

CLI

databricks postgres undelete-project projects/my-project

curl (Unix指令)

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/undelete" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq