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.

Last updated on