Python中访问Firestore命名数据库的实用指南

Firestore多数据库概述

google cloud firestore不仅支持每个项目一个默认数据库，还允许创建多个命名数据库。这种多数据库架构在以下场景中尤为有用：

• 多租户应用: 为每个租户隔离数据，提高数据安全性和管理效率。
• 环境分离: 将开发、测试、生产环境的数据存储在不同的数据库中，避免数据混淆。
• 数据分区: 根据业务逻辑或数据类型将数据分散到不同的数据库，优化查询性能或满足特定合规性要求。

默认情况下，使用Python SDK连接Firestore时，通常会访问名为(default)的数据库。然而，当需要操作特定的命名数据库时，就需要明确指定其名称。

核心方法：使用google-cloud-firestore SDK访问命名数据库

从google-cloud-firestore库的2.17.0版本开始，firestore.Client()构造函数引入了一个database参数，允许开发者直接指定要连接的数据库名称。这是访问命名数据库最直接和推荐的方式。

1. 前提条件

在开始之前，请确保您的google-cloud-firestore库已更新到2.17.0或更高版本。您可以使用以下命令进行更新：

pip install --upgrade google-cloud-firestore

2. 直接导入与初始化

为了明确使用支持database参数的客户端，建议直接从google.cloud导入firestore模块。

立即学习“Python免费学习笔记（深入）”；

from google.cloud import firestore
import os

# 确保已设置GOOGLE_APPLICATION_CREDENTIALS环境变量
# 或在代码中直接指定凭证文件路径
# os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"

# 初始化Firestore客户端，指定命名数据库
# 将 "your-named-database" 替换为您的实际数据库名称
# 注意：数据库名称通常是您在Google Cloud控制台创建时指定的ID
try:
    firestore_client_named = firestore.Client(database="my-custom-db")

    # 示例：在命名数据库中写入数据
    doc_ref_write = firestore_client_named.collection("users").document("alovelace")
    doc_ref_write.set({
        "first": "Ada",
        "last": "Lovelace",
        "born": 1815
    })
    print(f"数据已写入命名数据库 '{firestore_client_named.database_id}' 中的 'users/alovelace'。")

    # 示例：从命名数据库中读取数据
    doc = doc_ref_write.get()
    if doc.exists:
        print(f"从命名数据库 '{firestore_client_named.database_id}' 读取到数据: {doc.to_dict()}")
    else:
        print(f"命名数据库 '{firestore_client_named.database_id}' 中的文档不存在。")

except Exception as e:
    print(f"访问命名数据库时发生错误: {e}")

# 您也可以同时初始化默认数据库的客户端
try:
    firestore_client_default = firestore.Client()
    doc_ref_default = firestore_client_default.collection("default_collection").document("data")
    # 尝试写入或读取默认数据库
    doc_ref_default.set({"message": "Hello from default database"})
    doc_default = doc_ref_default.get()
    if doc_default.exists:
        print(f"从默认数据库 '{firestore_client_default.database_id}' 读取到数据: {doc_default.to_dict()}")
    else:
        print(f"默认数据库 '{firestore_client_default.database_id}' 中的文档不存在。")
except Exception as e:
    print(f"访问默认数据库时发生错误: {e}")

在上面的示例中，firestore.Client(database="my-custom-db")明确指示客户端连接到名为my-custom-db的Firestore实例。

扣子编程

扣子推出的AI编程开发工具

下载

与firebase-admin SDK的集成与兼容性

许多Python项目使用firebase-admin SDK来初始化Firebase应用并访问其服务。firebase-admin SDK内部也依赖于google-cloud-firestore库。因此，即使您通过firebase_admin.initialize_app()初始化了应用，仍然可以通过以下方式来访问命名数据库：

1. 结合firebase-admin进行凭证管理

您可以使用firebase-admin来处理凭证和应用初始化，然后利用google.cloud.firestore.Client来创建针对特定数据库的客户端实例。

import firebase_admin
from firebase_admin import credentials
from google.cloud import firestore # 注意：这里是google.cloud.firestore

# 初始化Firebase Admin SDK，用于凭证管理和项目ID
# 如果您已经设置了GOOGLE_APPLICATION_CREDENTIALS环境变量，ApplicationDefault()会自动找到
# 否则，您可能需要提供 serviceAccountKey.json 路径
cred = credentials.ApplicationDefault()
# 确保projectId是您的Firebase/GCP项目ID
firebase_admin.initialize_app(cred, options={"projectId": "your-gcp-project-id"})

# 现在，使用google.cloud.firestore.Client来创建针对命名数据库的客户端
# 这里的projectId可以省略，因为firebase_admin.initialize_app已经设置了默认项目
try:
    firestore_client_named_via_admin = firestore.Client(database="my-another-db")

    # 示例：在命名数据库中查询数据
    docs = firestore_client_named_via_admin.collection("cities").stream()
    print(f"从命名数据库 '{firestore_client_named_via_admin.database_id}' 读取 'cities' 集合中的文档:")
    for doc in docs:
        print(f"  {doc.id} => {doc.to_dict()}")

except Exception as e:
    print(f"通过Firebase Admin SDK访问命名数据库时发生错误: {e}")

# 您仍然可以通过firebase_admin.firestore来获取默认数据库客户端
from firebase_admin import firestore as admin_firestore
default_db_client = admin_firestore.client()
print(f"\n默认数据库客户端的数据库ID: {default_db_client.database_id}")

在这种方法中，firebase_admin.initialize_app()负责设置全局的Firebase应用上下文和凭证，而google.cloud.firestore.Client(database="...")则利用这些凭证和项目信息，创建了一个指向特定命名数据库的Firestore客户端。

注意事项与最佳实践

1. 库版本: 始终确保您的google-cloud-firestore库版本为2.17.0或更高，以支持database参数。
2. 数据库名称: 数据库名称是您在Google Cloud控制台中创建命名数据库时指定的ID。它不包含(default)字样。请确保名称拼写正确。
3. 凭证管理: 无论您是直接使用google-cloud-firestore还是结合firebase-admin，都需要正确配置您的Google Cloud凭证。推荐使用服务账号密钥或Workload Identity。
4. 项目ID: 即使指定了database参数，客户端仍然需要知道它属于哪个Google Cloud项目。通常，这通过凭证或firebase_admin.initialize_app的projectId选项来隐式或显式提供。
5. 错误处理: 在实际应用中，务必添加适当的错误处理机制，例如try-except块，以应对网络问题、权限不足或数据库不存在等情况。
6. 资源管理: Firestore客户端通常是轻量级的，但在高并发或长时间运行的应用中，考虑客户端的生命周期管理。通常情况下，创建一次客户端并在整个应用生命周期中重用是最佳实践。

总结

在Python中访问Google Firestore的命名数据库，主要通过google-cloud-firestore SDK的firestore.Client()构造函数中新增的database参数实现。确保您的库版本为2.17.0或更高，并正确导入google.cloud.firestore模块，即可轻松连接并操作非默认数据库。结合firebase-admin SDK使用时，可以利用其便捷的凭证管理功能，同时创建指向特定命名数据库的google.cloud.firestore.Client实例。掌握这一方法，将使您在构建复杂的、多数据库支持的Firestore应用时更加灵活和高效。