Get database connection information for the current workspace¶
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.
GET https://api.moi.matrixorigin.cn/v5/user/me/db-connection
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.
Request¶
curl --fail-with-body "$MOI_ENDPOINT/user/me/db-connection" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID"
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.
Successful response¶
{
"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"
}
}
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.
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.