<span id="获取当前工作区数据库连接资料"></span>

# Get database connection information for the current workspace

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

Get database connection information for the current identity and effective role. Success includes credentials and initialization statements required on the same connection. Restrict storage and logging of the result.

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

<span id="调用前准备"></span>

## Before you call this API

Set `MOI_ENDPOINT` to the product API prefix `https://api.moi.matrixorigin.cn/v5`; use the corresponding product API URL for a dedicated deployment.

Requires product identity and exactly one nonempty X-Workspace-ID. Resolve the single current effective role according to the contract. Do not infer data privileges from workspace Owner status or the union of role bindings.

<span id="请求"></span>

## Request

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

| Parameter | Location | Required | Description |
| --- | --- | --- | --- |
| X-Workspace-ID | header | Yes | Target workspace ID |

No business request body or pagination. Do not connect until credentials and role are ready.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| data.host | string | Database address; deployment public-address configuration may override it. |
| data.port | integer | Database port; public-port configuration may override it. |
| data.database | string | Target database. |
| data.account_name | string | MatrixOne account. |
| data.username / password | string | User and password for this connection; exclude from public logs. |
| data.session_init_sqls | string[] | Execute each statement in order on the same physical connection. Run business SQL only after all succeed. |
| data.effective_role_id | string | Single effective role ID for this request. |
| data.effective_role_db_role | string | Corresponding database role name. |
| data.effective_role_source | string | default_role or explicit_override; the full runtime contract remains to be verified. |
| data.effective_role_version | string | Role lifecycle version, not permanent proof of validity for every binding/user/workspace. |

Initialize every new connection and close it if any step fails. Retrieve connection information again for a new logical request. Tags and role settings do not automatically refresh through long-lived external connections. Switching roles within a native MatrixOne session does not change the Application IAM effective role. Returned information does not establish network reachability or successful database connection.

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

<span id="错误响应"></span>

## Error responses

| HTTP | code | Condition |
| --- | --- | --- |
| 200 | ErrGetDBConnection | Workspace header or general connection-information read failed. |
| 200 | ErrWorkspaceNotFound / ErrUserNotSynced | Workspace does not exist or identity has not synchronized. |
| 200 | ErrWorkspaceOwnerRequired | Owner credential ownership mismatch. |
| 200 | ErrWorkspaceOwnerCredentialInitializing / ErrWorkspaceOwnerCredentialFailed | Credentials are preparing or failed. |
| 403 | PERMISSION_DENIED | Workspace access or authorization denied. |
| 500 | ErrServer | Error-message localization failed. |

Workspace admission and identity middleware have separate mappings; the full error matrix remains unverified. Continue only with outer code=OK and complete information. The service supports eligible member credentials. A historical Owner error code does not mean Owner-only access.
