# 数据库 (/docs/api/native/database/databases)



[指南 →](/docs/cloud/services/database/quickstart)

[基础地址与鉴权](/docs/api/native/database)

## 创建库 [#创建库]

`POST /database/v1/databases`

### 请求体 [#请求体]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 名称 |
| labels | object | 否 | 标签 |

返回: `Database`.

### 响应 [#响应]

#### HTTP 201 [#http-201]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walk-lib-r1-DOC-5320-tasks","labels":{"purpose":"docs","sample":"walk-lib-r1-doc-5320-"}}'
```

响应示例 — HTTP 201

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-tasks",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:41.488Z",
  "deleted_at": null,
  "purge_at": null
}
```

## 列出库 [#列出库]

`GET /database/v1/databases`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| cursor | query | 上一页返回的 next_cursor。 |
| limit | query | 最多返回的条数。 (default: 20) (1–100) |
| labels | query | 精确匹配标签，例如 labels[purpose]=docs。 |
| status | query | 库状态：active 或 deleting；省略时只列出 active。 |

返回: `Page + object`.

### 响应 [#响应-1]

#### HTTP 200 [#http-200]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | Databases on this page, newest first (created_at descending, ties by id). Deleting databases are excluded unless status=deleting. |
| data[].id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| data[].name | string | Display name given at creation or by the last update; it is not an identifier. |
| data[].labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| data[].status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| data[].table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| data[].size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| data[].created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| data[].updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| data[].deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| data[].purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |
| next_cursor | string | null | Opaque cursor for the next page, or null when there are no more items. Databases list: pass it as cursor. Events list: pass it as after_seq (order asc) or before_seq (order desc). |

```bash
curl -g -X GET "https://api.deepraxis.ai/database/v1/databases?limit=10&labels[purpose]=docs&labels[sample]=walk-lib-r1-doc-5320-" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "data": [
    {
      "id": "db_d6f0d743d5a645e8",
      "name": "walk-lib-r1-DOC-5320-tasks",
      "labels": {
        "purpose": "docs",
        "sample": "walk-lib-r1-doc-5320-"
      },
      "status": "active",
      "table_count": 0,
      "size_bytes": 53248,
      "created_at": "2026-10-11T17:41:40.620Z",
      "updated_at": "2026-10-11T17:41:41.488Z",
      "deleted_at": null,
      "purge_at": null
    }
  ],
  "next_cursor": null
}
```

## 读取库 [#读取库]

`GET /database/v1/databases/{database_id}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |

返回: `Database`.

### 响应 [#响应-2]

#### HTTP 200 [#http-200-1]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-tasks",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:41.488Z",
  "deleted_at": null,
  "purge_at": null
}
```

## 更新库 [#更新库]

`PATCH /database/v1/databases/{database_id}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |

### 请求体 [#请求体-1]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| name | string | 否 | 名称 |
| labels | object | 否 | 标签 |

返回: `Database`.

### 响应 [#响应-3]

#### HTTP 200 [#http-200-2]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walk-lib-r1-DOC-5320-notes"}'
```

响应示例 — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:43.514Z",
  "deleted_at": null,
  "purge_at": null
}
```

## 删除库 [#删除库]

`DELETE /database/v1/databases/{database_id}`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |

返回: `Database`.

### 响应 [#响应-4]

#### HTTP 200 [#http-200-3]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "deleting",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:51.868Z",
  "deleted_at": "2026-10-11T17:41:51.868Z",
  "purge_at": "2026-10-18T17:41:51.868Z"
}
```

## 恢复库 [#恢复库]

`POST /database/v1/databases/{database_id}/restore`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |

返回: `Database`.

### 响应 [#响应-5]

#### HTTP 200 [#http-200-4]

Success

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:51.528Z",
  "deleted_at": null,
  "purge_at": null
}
```

## 清除库 [#清除库]

`POST /database/v1/databases/{database_id}/purge`

| 参数 | 位置 | 说明 |
| --- | --- | --- |
| database_id | path | 库 ID。 |

返回: `object`.

### 响应 [#响应-6]

#### HTTP 200 [#http-200-5]

Permanently purged

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Id (db_…) of the database that was permanently purged; it no longer resolves. |
| object | string | Resource type of the purged object; always database. |
| purged | boolean | Always true: the database and all of its data were permanently removed and cannot be recovered. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/purge" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

响应示例 — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "object": "database",
  "purged": true
}
```

## Database [#database]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | string | 是 | 资源 ID; ^db_ |
| name | string | 是 | 名称 |
| labels | object | 是 | 标签 |
| status | "provisioning" / "active" / "deleting" / "deleted" / "failed" | 是 | 库状态 |
| table_count | integer | 是 | 表数量 |
| size_bytes | integer | 是 | 占用字节数 |
| created_at | date-time | 是 | 创建时间 |
| updated_at | date-time | 是 | 更新时间 |
| deleted_at | date-time / null | 是 | 删除时间；未删除时为 null |
| purge_at | date-time / null | 是 | — |

## Page [#page]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| data | JSON[] | 是 | 资源数组 |
| next_cursor | string / null | 是 | 下一页游标；没有后续时为 null |