# 获取当前工作区数据库连接资料

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

获取当前身份和有效角色的数据库连接资料。成功响应包含凭据及同一连接必须执行的初始化语句，应限制结果的存储与日志输出。

```text
GET https://api.moi.matrixorigin.cn/v5/user/me/db-connection
```

## 调用前准备

`MOI_ENDPOINT` 使用产品 API 前缀 `https://api.moi.matrixorigin.cn/v5`；专有部署填写对应的产品 API 地址。

需要产品身份及单个非空X-Workspace-ID。按规范取得当前唯一有效角色；不要从工作区Owner身份或角色绑定并集推导数据权限。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --fail-with-body "$MOI_ENDPOINT/user/me/db-connection" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} 参数说明

| 参数 | 位置 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| X-Workspace-ID | header | 是 | 目标工作区ID |

无业务请求体或分页。凭据或角色未准备好时不能继续建连。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "host": "db.example.test",
    "port": 6001,
    "database": "sales",
    "account_name": "account-example",
    "username": "user-example",
    "password": "<示例密码>",
    "session_init_sqls": [
      "SET ROLE `moi_role_1`",
      "SET enable_remap_hint = 1"
    ],
    "effective_role_id": "1",
    "effective_role_db_role": "moi_role_1",
    "effective_role_source": "default_role",
    "effective_role_version": "2"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.host | string | 数据库地址，可被部署公开地址配置覆盖 |
| data.port | integer | 数据库端口，可被公开端口配置覆盖 |
| data.database | string | 目标数据库 |
| data.account_name | string | MatrixOne账号 |
| data.username / password | string | 此连接的用户与密码，不在公开日志保留 |
| data.session_init_sqls | string[]（字符串数组） | 在同一物理连接按顺序逐条执行，全部成功后执行业务SQL |
| data.effective_role_id | string | 此次唯一有效角色ID |
| data.effective_role_db_role | string | 对应数据库角色名 |
| data.effective_role_source | string | default_role或explicit_override；完整运行期合同仍待核验 |
| data.effective_role_version | string | Role生命周期版本，不是所有binding/user/workspace永久有效证明 |

每条新连接都要初始化，任一步失败就关闭。新的逻辑请求重新获取连接资料，标签与角色设置不通过长期保留的外部连接自动刷新。原生MatrixOne会话主动切换角色不会改变Application IAM的有效角色。返回资料不证明网络可达或数据库建连成功。

:::::
::::::
:::::::

## 错误响应

| HTTP | code | 条件 |
| --- | --- | --- |
| 200 | ErrGetDBConnection | 工作区头或通用连接资料读取失败 |
| 200 | ErrWorkspaceNotFound / ErrUserNotSynced | 工作区不存在或身份未同步 |
| 200 | ErrWorkspaceOwnerRequired | Owner凭据归属不匹配 |
| 200 | ErrWorkspaceOwnerCredentialInitializing / ErrWorkspaceOwnerCredentialFailed | 凭据准备中或失败 |
| 403 | PERMISSION_DENIED | 工作区访问或授权被拒绝 |
| 500 | ErrServer | 错误提示本地化失败 |

工作区准入与身份中间件还有独立映射，完整错误矩阵待验。只有外层code=OK且资料完整才继续。服务支持合规成员凭据分支，不能把历史Owner错误码写成“仅Owner可用”。
