快速入门文档数据库兼容功能-PolarDB-阿里云

本文将引导您完成从创建集群到首次成功访问的全过程，帮助您快速上手使用PolarDB MySQL版的文档数据库兼容功能。

适用范围

在使用文档数据库兼容能力前，请确保您的集群版本满足以下要求：

内核版本：MySQL 8.0.2。
其他限制：
- 多主集群（Limitless）与Serverless集群暂不支持文档数据库兼容功能。
- 开启Orca（兼容Redis协议）的集群不支持文档数据库兼容功能。

说明

您可前往PolarDB控制台，在集群的配置与管理 > 版本管理页面中查看对应的版本。若版本不满足要求，请升级对应的小版本。

开启兼容文档数据库能力

您可以通过以下方式为集群开启文档数据库兼容功能。若您的集群满足适用范围，则可以在集群的基本信息页面中，找到文档数据库兼容配置项，单击开启。

配置文档数据库访问地址

开启文档数据库兼容功能后，系统会自动创建一个默认的文档数据库兼容访问地址。您也可以创建自定义地址以满足特定需求。

在集群基本信息页面的数据库连接区域，可以找到系统默认创建的文档数据库兼容地址。
（可选）单击创建自定义地址并选择地址类型为文档数据库兼容地址。

创建文档数据库专用账号

您需要创建一个专用的文档数据库账号来连接文档数据库。

在集群的配置与管理 > 账号管理页面，单击创建账号。
将账号类型选择为文档数据库高权限账号，账号名固定为doc_root，随后设置密码。
创建成功后，在账号列表中可看到该账号。
说明
- 文档数据库账号是在特定数据库的上下文中创建的，不同数据库中可能有名字相同的账号，因此PolarDB MySQL版中对应的账号会有一个前缀用来区分不同的数据库。您在登录时使用的账号名仍然为doc_root，不需要添加前缀。
- 控制台仅支持创建文档数据库高权限账号，普通文档数据库账号请连接到文档数据库地址后使用createUser命令进行创建。

配置网络访问

根据您的服务器或客户端位置，选择合适的网络连接方式。

私网连接（推荐）
如果您的应用程序部署在阿里云ECS上，请确保ECS与PolarDB集群位于同一VPC内，并已将ECS的IP地址或安全组添加到集群的设置集群白名单中。
公网连接
如需在本地环境进行开发与测试，或当ECS与PolarDB集群不位于同一VPC内时，您可以在集群基本信息页面的数据库连接区域，为文档数据库兼容地址申请一个公网地址。
说明
公网地址访问会增加安全风险。建议仅用于临时开发测试，完成后请及时释放公网地址。

连接并验证

完成以上配置后，可使用应用程序或者mongosh等客户端工具连接数据库并验证功能。

`mongosh`客户端

安装mongosh客户端：mongosh是MongoDB官方推荐的命令行交互工具。本文将以ECS实例及Alibaba Cloud Linux release 3操作系统为例，演示如何进行安装。
1. 运行以下命令，创建YUM仓库文件。
```
sudo vim /etc/yum.repos.d/mongodb-org-6.repo
```
2. 将以下内容粘贴至文档中。
```
[mongodb-org-6.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/6.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://pgp.mongodb.com/server-6.0.asc
```
3. 运行以下安装命令。
```
sudo yum install -y mongodb-org
```
连接数据库：使用以下命令格式，并将占位符替换为实际信息。
```
mongosh "mongodb://<username>:<password>@<polardb_endpoint>:<port>"
```
参数说明：
- <username>：文档数据库账号名。
- <password>：文档数据库账号名对应的密码。如果密码中包含@、#或$等特殊字符，请先进行UrlEncode编码，以避免连接字符串解析错误。
- <polardb_endpoint>：文档数据库访问地址。
- <port>：文档数据库访问地址对应的端口号。
连接示例：
```
# 假设账号为 doc_user，密码为 YourPassword123!，地址为 pe-****************.rwlb.rds.aliyuncs.com，端口为 3306
mongosh "mongodb://doc_user:YourPassword123!@pe-****************.rwlb.rds.aliyuncs.com:3306"
```
连接成功后，命令行提示符会变为test>或类似形式。

验证读写操作。

执行以下命令插入多条文档数据。

db.users.insertMany([
  { name: "Alice", age: 25, email: "alice@example.com" },
  { name: "Bob", age: 30, email: "bob@example.com" },
  { name: "Charlie", age: 22, email: "charlie@example.com" }
])

如果操作成功，系统会返回确认信息和插入文档的ObjectId。

{
  acknowledged: true,
  insertedIds: {
    '0': ObjectId('6926c9a36625af7c339xxx'),
    '1': ObjectId('6926c9a36625af7c339xxx'),
    '2': ObjectId('6926c9a36625af7c339xxx')
  }
}

执行以下命令查询已插入的数据。
```
db.users.find({
  age: {
    $gt: 25 
  } 
})
```
如果成功查询到Bob的数据记录，则表明PolarDB MySQL版集群已成功开启并配置文档数据库兼容功能，且读写操作均正常。
```
[
  {
    name: 'Bob',
    age: 30,
    email: 'bob@example.com',
    _id: ObjectId('6926c9a36625af7c339xxx')
  }
]
```

Python示例

使用以下Python示例代码，通过pymongo SDK验证您的配置是否正确。以下内容以ECS实例，Alibaba Cloud Linux 3.2104 LTS 64位操作系统为例进行说明。

根据实际业务需求，进入指定的项目目录。此处以/home/testMongoDB为例。
```
mkdir /home/testMongoDB
cd /home/testMongoDB
```
在/home/testMongoDB目录中，创建虚拟环境（venv）隔离项目依赖，避免全局污染。
```
python3 -m venv myenv
```
激活虚拟环境。
```
source myenv/bin/activate
```
安装所需的Python依赖库。
```
pip3 install pymongo
```

创建一个Python文件，并复制以下代码。请将endpoint_url、username和password替换为PolarDB集群的文档数据库访问地址和文档数据库专用账号。

vim main.py

from pymongo import MongoClient

# 1. Configure your connection details
# Endpoint URL from Step 2
endpoint_url = "mongodb://<your-polardb-documentdb-endpoint>:<port>"
# username from Step 3
username = "<your-username>"
# password from Step 3
password = "<your-password>"


def insert_data(userinfo):
    """Insert data into collection"""
    users = [
        {"_id": 1, "userid": "user01", "name": "Alice", "age": 18},
        {"_id": 2, "userid": "user02", "name": "Bob", "age": 25},
        {"_id": 3, "userid": "user03", "name": "Charlie", "age": 20},
    ]
    userinfo.insert_many(users)
    print("Inserted %d documents into the collection" % len(users))


def find_data(userinfo):
    """Find data from collection"""
    users = userinfo.find()
    print("Found user info from collection")
    for user in users:
        print(user)


def find_data_by_age(userinfo):
    """Find data by age from collection"""
    users = userinfo.find({"age": {"$gte": 20}})
    print("Found user info with age >= 25 from collection")
    for user in users:
        print(user)


# Run the verification process
if __name__ == "__main__":
    try:
        # 2. Create a MongoDB client
        client = MongoClient(endpoint_url, username=username, password=password)
        print("Connected to PolarDB DocumentDB successfully")

        database = client.get_database("test")
        userinfo = database.get_collection("userinfo")

        # 3. Insert some data and verify it
        insert_data(userinfo)
        find_data(userinfo)
        find_data_by_age(userinfo)

    finally:
        # Ensure the table is cleaned up even if errors occur
        userinfo.drop()
        print("Collection deleted successfully")
        client.close()

执行该脚本后，您应该会看到类似以下的输出：

python3 main.py

Connected to PolarDB DocumentDB successfully
Inserted 3 documents into the collection
Found user info from collection
{'_id': 1, 'userid': 'user01', 'name': 'Alice', 'age': 18}
{'_id': 2, 'userid': 'user02', 'name': 'Bob', 'age': 25}
{'_id': 3, 'userid': 'user03', 'name': 'Charlie', 'age': 20}
Found user info with age >= 25 from collection
{'_id': 2, 'userid': 'user02', 'name': 'Bob', 'age': 25}
{'_id': 3, 'userid': 'user03', 'name': 'Charlie', 'age': 20}
Collection deleted successfully

看到以上输出，表明您已成功连接并操作文档数据库，所有配置均已生效。