管理資料庫

本頁介紹如何建立、更新和刪除 Cloud Firestore 資料庫。每個項目可以建立多個 Cloud Firestore 資料庫。您可以使用多個資料庫設定正式版和測試環境、隔離客戶資料，以及進行資料區域化。

(default) 資料庫

如果您不指定資料庫，則 Cloud Firestore 用戶端庫和 Google Cloud CLI 預設連接到 (default) 資料庫。

必要的角色

如要建立及管理資料庫，您需要 Owner 或 Datastore Owner Identity and Access Management 角色。這些角色會授予必要權限。

所需權限

要管理資料庫，您需要以下權限：

• 建立資料庫：datastore.databases.create
• 讀取資料庫設定：datastore.databases.getMetadata
• 設定資料庫：datastore.databases.update
• 刪除資料庫：datastore.databases.delete
• 複製資料庫：datastore.databases.clone

建立資料庫

若要建立資料庫，請使用下列方法之一：

控制台

1. 前往 Firebase 控制台的「Firestore Database」頁面。

   前往 Firestore 資料庫

2. 如果這是你的第一個命名資料庫，請點選新增資料庫。
3. 否則，按一下 (預設)，然後按一下 新增資料庫。
4. 設定資料庫。請輸入資料庫 ID。選擇一個地點。 點選建立資料庫。

gcloud

使用 gcloud firestore databases create 指令。

gcloud firestore databases create \
--database=DATABASE_ID \
--location=LOCATION \
--type=DATABASE_TYPE \
[--delete-protection]

更改下列內容：

• DATABASE_ID：有效的資料庫 ID。
• LOCATION: Cloud Firestore 多區域或區域 的名稱。
• DATABASE_TYPE: firestore-native 表示原生模式，datastore-mode 表示資料儲存模式。

--delete-protection 是啟用防刪除功能的選用旗標。您必須先停用這項設定，才能刪除已啟用防刪除功能的資料庫。這個設定預設為停用。

如要為資料庫新增標記，請使用 --tags 旗標。例如：

• --tags=123/environment=production,123/costCenter=marketing
• --tags=tagKeys/333=tagValues/444

Firebase CLI

firebase firestore:databases:create DATABASE_ID \
--location=LOCATION \
[--delete-protection DELETE_PROTECTION_ENABLEMENT]

更改下列內容：

• DATABASE_ID：有效的資料庫 ID。
• LOCATION：Cloud Firestore 多地區或區域的名稱。
• DELETE_PROTECTION_ENABLEMENT：ENABLED 或 DISABLED。
建立的資料庫始終處於 Firestore Native 模式。

--delete-protection 是一個可選參數，用於啟用刪除保護。啟用刪除保護後，您將無法刪除資料庫，直到您停用此設定。這項設定預設為停用。

Terraform

resource "google_firestore_database" "database" {
  project     = "project-id"
  name        = DATABASE_ID
  location_id = LOCATION
  type        = DATABASE_TYPE

  // Optional
  delete_protection_state = DELETE_PROTECTION_STATE
}

更改下列內容：

• DATABASE_ID：有效的資料庫 ID。
• LOCATION：Cloud Firestore 多地區或區域的名稱。
• DATABASE_TYPE：原生模式為 FIRESTORE_NATIVE，Datastore 模式為 DATASTORE_MODE。
• DELETE_PROTECTION_ENABLEMENT：DELETE_PROTECTION_ENABLED 或 DELETE_PROTECTION_DISABLED。

delete_protection_state 是啟用防刪除功能的選用引數。啟用防刪除功能後，您必須先停用這項設定，才能刪除資料庫。這項設定預設為停用。

資料庫 ID

有效的資料庫 ID 包括 (default) 以及符合下列格式的 ID：

• 只能包含英文字母、數字和連字號 (-)。
• 字母必須為小寫。
• 第一個字元必須是字母。
• 最後一個字元須為英文字母或數字。
• 至少 4 個字元。
• 最多 63 個字元。
• 不得為 UUID 或類似 UUID 的值。舉例來說，請勿使用 f47ac10b-58cc-0372-8567-0e02b2c3d479 這類 ID。

刪除資料庫後，需等待 5 分鐘才能再次使用該資料庫 ID。

刪除防護措施

使用防刪除功能，避免誤刪資料庫。 如要刪除已啟用防刪除功能的資料庫，請先停用這項功能。刪除保護功能預設為停用。您可以在建立資料庫時啟用刪除保護機制，也可以更新資料庫設定來啟用這項機制。

為您的資料庫設定 Cloud Firestore Security Rules

使用 Firebase CLI 將 Cloud Firestore Security Rules 部署到您的每個資料庫。請參閱管理及部署 Cloud Firestore Security Rules 的指南。

使用客戶端庫存取指定名稱的資料庫

已命名的資料庫是指名稱不是 (default) 的資料庫。預設情況下，Firebase SDK 和 Google API 用戶端程式庫連接到專案中的 (default) Cloud Firestore 資料庫。若要建立連接到指定資料庫的用戶端，請在實例化用戶端時設定資料庫 ID。

筆記： 若要使用多個資料庫，請務必更新至最新版本。Firebase 客戶端 SDK和Google API 用戶端程式庫。

可列出資料庫

請使用下列其中一種方法列出資料庫：

控制台

前往 Google Cloud 控制台的「資料庫」頁面。

轉到資料庫

附註：您可以在 Google Cloud 控制台中檢視並列出您的資料庫。您可以使用 Google Cloud 控制台建立 (default) 資料庫，但要建立命名資料庫，您必須使用 Google Cloud CLI 或其他方法。 刪除資料庫使用 Google Cloud CLI 。

gcloud

使用 gcloud firestore databases list 指令列出專案中的所有資料庫。

gcloud firestore databases list

Firebase CLI

使用 firebase firestore:databases:list 指令列出項目中的所有資料庫。

firebase firestore:databases:list

查看資料庫詳細資料

如要查看單一資料庫的詳細資料，請使用下列其中一種做法：

gcloud

使用 gcloud firestore databases describe 指令：

gcloud firestore databases describe --database=DATABASE_ID

Firebase CLI

使用 firebase firestore:databases:get 指令：

firebase firestore:databases:get DATABASE_ID

將 DATABASE_ID 替換為資料庫 ID。

更新資料庫設定

如要更新資料庫的設定，請使用 gcloud firestore databases update 指令。使用這項指令可啟用或停用刪除保護機制。

更新防刪除設定

如要在資料庫上啟用防刪除功能，請使用 gcloud firestore databases update 指令並搭配 --delete-protection 標記。例如：

gcloud

gcloud firestore databases update --database=DATABASE_ID --delete-protection

將 DATABASE_ID 替換為資料庫 ID。

如要停用資料庫的防刪除功能，請使用 gcloud firestore databases update 指令並搭配 --no-delete-protection 旗標。例如：

gcloud

gcloud firestore databases update --database=DATABASE_ID --no-delete-protection

將 DATABASE_ID 替換為資料庫 ID。

刪除資料庫

如要刪除資料庫，請使用主控台或指令列工具。

如果資料庫已啟用防刪除設定，請先停用防刪除功能。

如果資料庫包含 App Engine 搜尋資料或 Blob 實體，請先刪除這些資料。

刪除資料庫時，系統不會自動刪除該資料庫的任何Eventarc觸發程序。觸發程序會停止傳送事件，但會繼續存在，直到您刪除觸發程序為止。

刪除資料庫不會產生刪除作業費用。

控制台

1. 前往 Firebase 控制台的「Firestore Database」頁面。

   前往 Firestore 資料庫

2. 在「資料」分頁中，按一下資料庫資料表檢視畫面上的 ，然後選取「刪除資料庫」。
3. 按照操作說明刪除資料庫。

gcloud

使用 `gcloud firestore databases delete` 指令。

gcloud firestore databases delete --database=DATABASE_ID

將 DATABASE_ID 替換為要刪除的資料庫 ID。如要刪除預設資料庫，請使用 ID '(default)'

複製資料庫

您可以將現有資料庫在所選時間戳記的狀態複製到新資料庫：

• 複製的資料庫是新資料庫，會建立在與來源資料庫相同的位置。

  如要建立副本，Cloud Firestore 會使用來源資料庫的時間點復原 (PITR) 資料。複製的資料庫包括所有資料和索引。

• 根據預設，複製的資料庫會採用與來源資料庫相同的加密方式，也就是使用 Google 的預設加密機制或 CMEK 加密機制。您可以指定其他加密類型，或使用其他金鑰進行 CMEK 加密。

• 時間戳記的精細度為一分鐘，且指定過去的時間點，該時間點位於 PITR 視窗定義的期間內：

  • 如果資料庫已啟用 PITR，您可以選取過去 7 天內的任何時間點 (如果啟用 PITR 的時間未滿 7 天，則可選取的時間範圍會更短)。
  • 如果未啟用 PITR，您可以選取過去一小時內的任一分鐘。
  • 你可以查看資料庫說明中可選取的最早時間戳記。

注意： 如要複製資料庫，您的 Google 帳戶必須具備 datastore.databases.clone IAM 權限。

主控台

Firebase 控制台不支援資料庫複製功能。您可以按照 Google Cloud CLI 的操作說明複製資料庫。

gcloud

使用 gcloud firestore databases clone 指令複製資料庫：

gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

更改下列內容：

• SOURCE_DATABASE：要複製的現有資料庫名稱。名稱格式為 projects/PROJECT_ID/databases/SOURCE_DATABASE_ID。

• PITR_TIMESTAMP：PITR 時間戳記，採用 RFC 3339 格式，精確度為分鐘。例如：2025-06-01T10:20:00.00Z 或 2025-06-01T10:30:00.00-07:00。

• DESTINATION_DATABASE_ID：新複製資料庫的資料庫 ID。這個資料庫 ID 不得與現有資料庫建立關聯。

範例：

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

如要在複製資料庫時繫結某些標記，請使用先前的指令和 --tags 旗標，這是要繫結的標記 KEY=VALUE 組合的選用清單。

範例：

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

根據預設，複製的資料庫會與來源資料庫採用相同的加密設定。如要變更加密設定，請使用 --encryption-type 引數：

• (預設) use-source-encryption：使用與來源資料庫相同的加密設定。
• google-default-encryption：使用 Google 的預設加密機制。
• customer-managed-encryption：使用 CMEK 加密。在 --kms-key-name 引數中指定金鑰 ID。

以下範例說明如何為複製的資料庫設定 CMEK 加密：

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

Firebase CLI

使用 firebase firestore:databases:clone 指令複製資料庫：

firebase firestore:databases:clone \
'SOURCE_DATABASE' \
'DESTINATION_DATABASE' \
--snapshot-time 'PITR_TIMESTAMP'

更改下列內容：

• SOURCE_DATABASE：要複製的現有資料庫名稱。名稱格式為 projects/PROJECT_ID/databases/SOURCE_DATABASE_ID。

• DESTINATION_DATABASE: 新克隆資料庫的資料庫名稱。名稱格式為 projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID。這個資料庫名稱不得與現有資料庫相關聯。

• PITR_TIMESTAMP：PITR 時間戳記，採用 RFC 3339 格式，精確度為分鐘。例如：2025-06-01T10:20:00.00Z 或 2025-06-01T10:30:00.00-07:00。如未指定，系統會選擇目前時間的快照，並向下取整至分鐘。

根據預設，複製的資料庫會與來源資料庫採用相同的加密設定。如要變更加密設定，請使用 --encryption-type 引數：

• (預設) USE_SOURCE_ENCRYPTION：使用與來源資料庫相同的加密設定。
• GOOGLE_DEFAULT_ENCRYPTION：使用 Google 的預設加密機制。
• CUSTOMER_MANAGED_ENCRYPTION：使用 CMEK 加密。在 --kms-key-name 引數中指定金鑰 ID。

設定每個資料庫的存取權限

您可以使用 Identity and Access Management 條件，在資料庫層級設定存取權。下列範例使用 Google Cloud CLI，為一或多個資料庫指派條件式存取權。您也可以在 Google Cloud 控制台中定義 IAM 條件。

警告： Google Cloud 控制台不會根據資料庫層級設定的 IAM 條件，允許/拒絕存取資料庫。這項限制僅適用於透過 Google Cloud 控制台存取資料庫。透過 Google Cloud 控制台以外的方式存取資料庫時 (例如使用 REST API 或用戶端程式庫)，系統會強制執行 IAM 條件。

查看現有的 IAM 政策

gcloud projects get-iam-policy PROJECT_ID

將 PROJECT_ID 設為您的專案 ID。

授予資料庫存取權

gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' \
--condition='expression=resource.name=="projects/PROJECT_ID/databases/DATABASE_ID",title=TITLE,description=DESCRIPTION'

設定下列欄位：

• PROJECT_ID：專案 ID
• EMAIL：代表特定 Google 帳戶的電子郵件地址，例如：[e-mail]。
• DATABASE_ID：資料庫 ID。
• TITLE: 表達式的可選標題。
• DESCRIPTION：運算式的選用說明。

授予所有資料庫的存取權，但一個資料庫除外

gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' \
--condition='expression=resource.name!="projects/PROJECT_ID/databases/DATABASE_ID",title=TITLE,description=DESCRIPTION'

設定下列欄位：

• PROJECT_ID：專案 ID
• EMAIL：代表特定 Google 帳戶的電子郵件地址，例如：[e-mail]。
• DATABASE_ID：資料庫 ID。
• TITLE: 表達式的可選標題。
• DESCRIPTION：運算式的選用說明。

移除特定成員和角色的政策

gcloud projects remove-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' --all

設定下列欄位：

• PROJECT_ID：專案 ID
• EMAIL：代表特定 Google 帳戶的電子郵件地址，例如：[e-mail]。

Cloud Monitoring

Cloud Firestore 指標會根據兩個受監控的資源回報。

• firestore.googleapis.com/Database
• firestore_instance(舊版)

您可以查看 firestore.googleapis.com/Database，檢查資料庫層級的匯總指標。firestore_instance 下方顯示的指標是專案層級的匯總資料。

限制

• 每個項目最多可以建立 100 個資料庫。如要提高這項上限，請與支援團隊聯絡。
• 如果 (default) 資料庫含有任何 GAE 搜尋資料，就無法刪除。 使用索引刪除 API 刪除 GAE 搜尋資料。如果您最近刪除了 GAE 搜尋資料，可能需要等待一段時間才能刪除資料庫。
• 如果 (default) 資料庫含有任何 Blob 實體，就無法刪除。使用 Blobstore 刪除 API 刪除 Blobstore 資料。 如要檢查 (default) 資料庫是否含有 Blobstore 資料，請在 Google Cloud 控制台中執行下列 GQL 查詢：SELECT * FROM __BlobInfo__。
• 刪除操作發生後，至少 5 分鐘內無法再使用資料庫 ID。
• Cloud Functions 第 1 版不支援 Firestore 已命名資料庫。使用 Cloud Firestore 觸發程序 (第 2 代) 為具名資料庫設定事件。
• 資料庫刪除後，即使建立同名的新資料庫，Firestore 函式觸發條件第 1 版和 Firestore 事件觸發條件也可能停止運作。

後續步驟

• 新增資料
• 取得資料
• 刪除資料