PolarDB PostgreSQL Agentic Database基本概念与集群管理

Agentic Database 基本概念

PolarDB PostgreSQL Agentic Database 按照集群 → 租户 → 项目 → 分支的层级组织数据库资源。通过 MCP Server 访问时，使用 API Key 认证租户身份。

• 集群（Cluster）：Agentic Database 的顶层逻辑容器。一个集群内可以包含多个租户。

• 租户（Tenant）：集群内的隔离单元。一个租户可以创建多个项目，不同租户之间的数据库集群互不可见。

• API Key：通过 MCP Server 访问和管理数据库资源时使用的身份认证凭证。每个租户对应一个 API Key。申请新的 API Key 时，系统会在集群内创建对应的新租户。

• 项目（Project）：组织和管理同一个数据库的多个分支的逻辑单元。创建项目时，系统会自动创建默认的 main 分支及其对应的数据库集群。

• 分支（Branch）：项目内一个实际的数据库集群。通过 MCP，可以基于已有分支创建新分支，使用方式类似 Git 的分支操作。新分支以源分支在创建时的数据为起点。每个项目最多创建 10 个分支。

例如，一个租户可以创建一个电商项目，并在项目内使用 main 分支开展主线工作，再基于它创建 dev 分支用于开发。

访问地址

• 默认地址：使用 PostgreSQL 协议连接数据库的访问地址，适用于 PostgreSQL 客户端、数据库管理工具以及应用程序中的数据库驱动。

• API 地址：使用 WebSocket 协议访问数据库的连接地址，适用于通过 WebSocket 建立连接的客户端或应用程序。

步骤一：创建集群

1. 登录PolarDB控制台。

2. 在左侧导航栏，选择AgenticDB 集群列表 > PostgreSQL，进入AgenticDB 集群列表页面。

3. 单击创建 AgenticDB 集群，跳转到购买页。

4. 根据业务需求配置以下核心参数，其余参数保持默认或按向导提示填写。

   参数	说明
   地域	选择集群部署地域。地域一旦选定，后续无法修改。请就近选择业务所在地域以降低访问延迟。
   引擎	选择PostgreSQL兼容的版本。
   网络和可用区	选择集群创建的专有网络与可用区。
   资源数量	选择需要创建的集群数量，默认是1，可以调整。后续也可在集群生产后进行修改。

5. 阅读并勾选服务协议，单击立即购买，按向导完成订单支付。订单支付成功后，系统将在数分钟内完成集群创建，可返回AgenticDB 集群列表页面查看集群状态。

步骤二：创建和管理API Key

PolarDB PostgreSQL Agentic Database MCP Server采用API Key认证机制，确保使用者身份可信、操作范围可控。API Key中内嵌了PolarDB PostgreSQL Agentic Database集群和租户信息，MCP Server在首次连接时自动完成三层校验（格式校验→Payload解析→远程验证），验证通过后创建Session，后续调用在该Session上下文中执行，AI Agent和使用者全程不接触任何数据库地址、账号或密码。

1. 登录PolarDB控制台。

2. 在左侧导航栏，选择AgenticDB 集群列表 > PostgreSQL，进入AgenticDB 集群列表页面。

3. 单击目标集群ID/名称，进入集群详情页。

4. 在左侧导航栏单击配置与管理 > API Key 管理，进入API Key管理页面。

5. 单击创建 API Key，在弹出面板中填写以下信息。

   参数	说明
   选择已有租户	输入Tenant名称，用于标识该API Key绑定的租户。每个API Key仅可访问其绑定的集群和租户下的资源，不能跨租户访问。
   描述	自定义描述，建议按使用方标注（例如Qoder-team-A、Cursor-dev-01），便于后续审计和轮转。

6. 单击确定，系统生成一条API Key。弹出的API Key 创建成功对话框中会展示租户名称、租户 ID及完整的API Key明文，单击复制完整 Key保存到本地。

   警告

   API Key仅在创建时展示一次，请立即复制并妥善保存到安全位置（例如密码管理器）。关闭对话框后无法再次查看完整Key，如果遗失需要重新创建。

7. API Key管理页面的列表中，可查看每条Key的Tenant、API Key、描述、状态（可用、创建中、轮转中、已过期、）与创建时间，按需在操作列执行重置或删除。

步骤三：修改配额

每个PolarDB PostgreSQL Agentic Database逻辑集群下可创建的数据库集群数量称为连接资源配额（在基本信息页面显示为资源数字段）。默认配额为1，即最多可创建1个数据库集群。业务规模扩大时，可通过以下任一入口调整。

1. 入口一：集群列表页：在AgenticDB 集群列表页面找到目标集群，在操作列单击增减资源。

2. 入口二：集群详情页：在集群详情页的基本信息区域找到资源数字段（显示格式为已用 / 配额），单击右侧的修改配额。

两种入口均会打开修改连接资源配额对话框。在目标配额输入框中填写新配额（不可小于当前已用数），单击确定提交，配额立即生效。

步骤四：开通LakeBase文件系统访问

PolarDB PostgreSQL Agentic Database集成LakeBase文件系统，为AI Agent提供POSIX兼容的对象存储访问能力。开通后，AI Agent可通过标准文件系统接口在PolarDB PostgreSQL Agentic Database环境中直接读写非结构化文件，支撑文档处理、模型输入输出、日志归档等场景。

1. 在集群详情页左侧导航栏单击基本信息。

2. 在基本信息区域找到文件系统访问字段，单击开通。

3. 在开通文件系统访问确认对话框中单击确定。系统开始为当前PolarDB PostgreSQL Agentic Database集群创建LakeBase文件系统集群，字段依次显示开通中...与已开通。

4. 开通完成后，可在基本信息页面的Lakebase算子页签中查看S3 Gateway连接地址、Meta URL、默认账号等连接信息，并按需通过开通公网访问入口开通公网连接。