开启和使用文档数据库兼容功能-PolarDB PostgreSQL版-阿里云

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

适用范围

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

内核版本：PostgreSQL 16，且修订版本需为2.0.16.10.10.0及以上。
数据库代理版本：需为2.3.60.1及以上。
PolarDB PostgreSQL分布式版与Serverless集群暂不支持文档数据库兼容能力。

说明

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

开启兼容文档数据库能力

您可以通过以下两种方式为集群开启文档数据库兼容功能。

已有集群

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

创建新集群

若您的集群不满足适用范围或希望在新的集群中使用当前功能，则可以在PolarDB控制台上创建一个新的集群。

前往PolarDB集群自定义购买页面。
将数据库引擎设置为PostgreSQL 16，并勾选文档数据库兼容。
根据业务需求配置地域、可用区和节点规格等其他选项。

配置文档数据库访问地址

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

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

创建文档数据库专用账号

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

在集群的配置与管理 > 账号管理页面，单击创建账号。
将账号类型选择为文档数据库高权限账号，并设置账号名和密码。

配置网络访问

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

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

连接并验证

完成以上配置后，可使用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，端口为 5432
mongosh "mongodb://doc_user:YourPassword123!@pe-****************.rwlb.rds.aliyuncs.com:5432"
```
连接成功后，命令行提示符会变为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('6925cf77a25e57c0bxxx'),
    '1': ObjectId('6925cf77a25e57c0bxxx'),
    '2': ObjectId('6925cf77a25e57c0bxxx')
  }
}

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