# Databases

URL: https://docs.vaultpanel.net/api-reference/databases

> API reference for MariaDB databases and database users, linking them to apps and websites, the SQL interface and one-click phpMyAdmin sign-in.

Databases and database users live on the MariaDB server of one of your servers (the one the installer set up for websites and apps, on port 3306). Passwords are generated for you, stored encrypted, and added to an app's environment in one step. See [Databases](https://docs.vaultpanel.net/guides/databases).

Hosting customers can use these endpoints for their own databases, within their plan.

## How changes work

Creating, deleting and changing databases and users returns `202 Accepted` with the record and the `job` that carries the change out. A record's `status` is `creating`, `updating` or `deleting` while its job runs; another change meanwhile answers `409 DATABASE_BUSY` with `details.jobId`. MariaDB must be installed on the server.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/databases` | [List databases](https://docs.vaultpanel.net/api-reference/databases#list-databases) |
| POST | `/api/v1/databases` | [Create a database](https://docs.vaultpanel.net/api-reference/databases#create-a-database) |
| GET | `/api/v1/databases/:id` | [Get a database](https://docs.vaultpanel.net/api-reference/databases#get-a-database) |
| PATCH | `/api/v1/databases/:id` | [Link a database](https://docs.vaultpanel.net/api-reference/databases#link-a-database) |
| DELETE | `/api/v1/databases/:id` | [Delete a database](https://docs.vaultpanel.net/api-reference/databases#delete-a-database) |
| POST | `/api/v1/databases/:id/retry` | [Retry creating a database](https://docs.vaultpanel.net/api-reference/databases#retry-creating-a-database) |
| POST | `/api/v1/databases/:id/tables` | [List tables](https://docs.vaultpanel.net/api-reference/databases#list-tables) |
| POST | `/api/v1/databases/:id/rows` | [Browse a table](https://docs.vaultpanel.net/api-reference/databases#browse-a-table) |
| POST | `/api/v1/databases/:id/query` | [Run SQL](https://docs.vaultpanel.net/api-reference/databases#run-sql) |
| POST | `/api/v1/databases/:id/phpmyadmin` | [Open in phpMyAdmin](https://docs.vaultpanel.net/api-reference/databases#open-in-phpmyadmin) |
| GET | `/api/v1/database-users` | [List database users](https://docs.vaultpanel.net/api-reference/databases#list-database-users) |
| POST | `/api/v1/database-users` | [Create a database user](https://docs.vaultpanel.net/api-reference/databases#create-a-database-user) |
| PATCH | `/api/v1/database-users/:id` | [Update a database user](https://docs.vaultpanel.net/api-reference/databases#update-a-database-user) |
| DELETE | `/api/v1/database-users/:id` | [Delete a database user](https://docs.vaultpanel.net/api-reference/databases#delete-a-database-user) |
| POST | `/api/v1/database-users/:id/password` | [Reveal a user's password](https://docs.vaultpanel.net/api-reference/databases#reveal-a-users-password) |

## The database object

```json
{
  "id": "8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9",
  "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
  "serverName": "web-1",
  "customerId": null,
  "engine": "mariadb",
  "name": "shop",
  "charset": "utf8mb4",
  "collation": "utf8mb4_unicode_ci",
  "status": "active",
  "sizeBytes": 52428800,
  "sizeCheckedAt": "2026-11-10T11:00:00.000Z",
  "application": { "id": "5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c", "name": "api" },
  "website": null,
  "users": [{ "id": "b1a2c3d4-…", "username": "shop", "privileges": "all" }],
  "lastJobId": "…",
  "lastError": null,
  "createdAt": "2026-11-02T09:10:00.000Z",
  "updatedAt": "2026-11-02T09:10:20.000Z"
}
```

`status` is `creating`, `active`, `updating`, `deleting` or `failed`. `application` and `website` are the app and website that use the database; a website's backups can include its linked databases.

## The database user object

```json
{
  "id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
  "serverName": "web-1",
  "customerId": null,
  "engine": "mariadb",
  "username": "shop",
  "privileges": "all",
  "status": "active",
  "hosts": ["localhost", "127.0.0.1"],
  "databases": [{ "id": "8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9", "name": "shop" }],
  "lastJobId": "…",
  "lastError": null,
  "createdAt": "2026-11-02T09:10:00.000Z",
  "updatedAt": "2026-11-02T09:10:20.000Z"
}
```

`privileges` is `all` (read, write and change the structure) or `readonly` (`SELECT` only). Users connect from the server itself, by socket or TCP.

## List databases

`GET /api/v1/databases` — Permission: databases.read — Token scope: read

Databases, by name. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Matches the name. |
| `serverId` | string | No | Databases on one server. |
| `applicationId` | string | No | Databases linked to one app. |
| `websiteId` | string | No | Databases linked to one website. |
| `sort` | string | No | `name` (default, ascending), `createdAt` or `size`. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/databases?serverId=1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.databases.list({ serverId });
```

**Response** `200 OK`: `{ items: [database], pagination }`.

## Create a database

`POST /api/v1/databases` — Permission: databases.manage — Token scope: manage

Creates a database (`CREATE_DATABASE`) and, by default, a user with access to it, named like the database. The user's generated password is returned only in this response. With `applicationId` and `addToAppEnv` (the default), the connection settings are added to the app's environment as `DATABASE_URL`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER` and `DB_PASSWORD`, only those it does not have yet (needs `applications.manage`).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string | Yes | The server to create it on. |
| `name` | string | Yes | 2 to 64 lowercase letters, digits and underscores, starting with a letter. Not a name reserved by the database server. |
| `applicationId` | string or null | No | The app that uses it, on the same server and account. |
| `websiteId` | string or null | No | The website that uses it, so its backups can include it. |
| `createUser` | boolean | No | Also create a user. Default `true`. |
| `username` | string | No | 2 to 32 lowercase letters, digits and underscores. Defaults to the database name. |
| `privileges` | string | No | The user's access: `all` (default) or `readonly`. |
| `addToAppEnv` | boolean | No | Add the connection settings to the app. Default `true`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/databases \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"serverId":"1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b","name":"shop","applicationId":"5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c"}'
```

**JavaScript**

```js
const { database, user, password, envAdded } = await panel.databases.create({
  serverId,
  name: 'shop',
  applicationId: appId,
});
```

**Response** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "database": { "id": "8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9", "name": "shop", "status": "creating" },
    "job": { "id": "…", "type": "CREATE_DATABASE", "status": "queued" },
    "user": { "id": "b1a2c3d4-…", "username": "shop", "privileges": "all", "status": "creating" },
    "password": "k2Vb9…",
    "envAdded": ["DATABASE_URL", "DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"]
  },
  "message": "Creating the database on the server",
  "requestId": "…"
}
```

`user` and `password` are `null` when no user was created. Apply the app's settings (or deploy it) for new environment variables to take effect.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | Adding to an app's environment without `applications.manage`. |
| 409 | `SERVER_NOT_READY` | The server has no connected agent yet. |
| 409 | `DATABASE_SERVER_NOT_INSTALLED` | Install MariaDB on the server first. |
| 409 | `AGENT_OUTDATED` | The agent is too old to manage databases. |
| 409 | `QUOTA_REACHED` | A hosting customer's plan allows no more databases or users. |
| 422 | `VALIDATION_ERROR` | An invalid or reserved name, a name already used on the server, or an app or website not on the same server and account. |

## Get a database

`GET /api/v1/databases/:id` — Permission: databases.read — Token scope: read

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9 \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const database = await panel.databases.get(databaseId);
```

**Response** `200 OK` with [the database object](https://docs.vaultpanel.net/api-reference/databases#the-database-object). `404 NOT_FOUND` when there is no such database, or it is not yours.

## Link a database

`PATCH /api/v1/databases/:id` — Permission: databases.manage — Token scope: manage

Links the database to the app and the website that use it, on the same server and account. `null` unlinks; a field left out keeps its link. Nothing changes on the server.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `applicationId` | string or null | No | The app that uses it. |
| `websiteId` | string or null | No | The website that uses it. |

**Example request**

**cURL**

```bash
curl -X PATCH https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9 \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"websiteId":"0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a"}'
```

**JavaScript**

```js
const { database } = await panel.databases.update(databaseId, { websiteId });
```

**Response** `200 OK` with `{ database }`, message `Saved`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 422 | `VALIDATION_ERROR` | Nothing to update, or the app or website is not on the same server and account. |

## Delete a database

`DELETE /api/v1/databases/:id` — Permission: databases.manage — Token scope: manage

Drops the database on the server (`DELETE_DATABASE`). Users stay; delete them separately.

**Example request**

**cURL**

```bash
curl -X DELETE https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9 \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { job } = await panel.databases.remove(databaseId);
```

**Response** `202 Accepted` with `{ database, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `DATABASE_BUSY` | Another change is running. |

## Retry creating a database

`POST /api/v1/databases/:id/retry` — Permission: databases.manage — Token scope: manage

Queues `CREATE_DATABASE` again for a database whose creation failed.

**Response** `202 Accepted` with `{ database, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `DATABASE_READY` | The database already exists on its server. |

## The SQL interface

[List tables](https://docs.vaultpanel.net/api-reference/databases#list-tables), [Browse a table](https://docs.vaultpanel.net/api-reference/databases#browse-a-table) and [Run SQL](https://docs.vaultpanel.net/api-reference/databases#run-sql) power the panel's database page. Each queues a routine job; the result arrives in the job's `output`. The agent runs them as an account that can reach only this database, read-only unless you allow changes. Statements stop after 30 seconds, results are cut at 1000 rows, and long cells at 5000 characters. All three need `databases.manage` and a database that is not being created, deleted or failed (`409 DATABASE_NOT_READY`). See [SQL client](https://docs.vaultpanel.net/guides/databases/sql-client).

## List tables

`POST /api/v1/databases/:id/tables` — Permission: databases.manage — Token scope: manage

**Example request**

**cURL**

```bash
curl -X POST https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9/tables \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const job = await panel.request('POST', `/databases/${databaseId}/tables`);
const { job: done } = await panel.jobs.wait(job.id, { intervalMs: 500 });
```

**Response** `202 Accepted` with the job. Its output:

```json
{
  "name": "shop",
  "tables": [
    {
      "name": "orders",
      "type": "table",
      "engine": "InnoDB",
      "rowEstimate": 12840,
      "dataBytes": 2637824,
      "indexBytes": 1589248,
      "collation": "utf8mb4_unicode_ci",
      "comment": null,
      "updatedAt": "2026-11-10 11:28:04"
    }
  ]
}
```

## Browse a table

`POST /api/v1/databases/:id/rows` — Permission: databases.manage — Token scope: manage

One page of a table's rows, with its columns, indexes and `CREATE` statement.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `table` | string | Yes | The table or view. |
| `page` | integer | No | From 1. Default 1. |
| `pageSize` | integer | No | 1 to 500. Default 50. |
| `orderBy` | string | No | A column to sort by. |
| `order` | string | No | `asc` (default) or `desc`. |

**Example request**

```bash
curl https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9/rows \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"table":"orders","pageSize":20,"orderBy":"id","order":"desc"}'
```

**Response** `202 Accepted` with the job. Its output:

```json
{
  "name": "shop",
  "table": "orders",
  "columns": [
    { "name": "id", "type": "int(10) unsigned", "nullable": false, "key": "PRI", "default": null, "extra": "auto_increment", "comment": null }
  ],
  "indexes": [{ "name": "PRIMARY", "unique": true, "type": "BTREE", "columns": ["id"] }],
  "isView": false,
  "createStatement": "CREATE TABLE `orders` (…)",
  "page": 1,
  "pageSize": 20,
  "orderBy": "id",
  "order": "desc",
  "rows": [["12840", "…"]],
  "hasMore": true,
  "truncated": false
}
```

## Run SQL

`POST /api/v1/databases/:id/query` — Permission: databases.manage — Token scope: manage

Runs one or more statements. Without `allowChanges` they run read-only; statements that change data or structure are refused by the database server, and the error carries a `hint`. Queries run with `allowChanges` are recorded in the audit log (the first 1000 characters).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sql` | string | Yes | Up to 100000 characters. |
| `allowChanges` | boolean | No | Run with write access. Default `false`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/databases/8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9/query \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"sql":"SELECT status, COUNT(*) AS n FROM orders GROUP BY status;"}'
```

**JavaScript**

```js
const job = await panel.request('POST', `/databases/${databaseId}/query`, {
  body: { sql: 'SELECT status, COUNT(*) AS n FROM orders GROUP BY status;' },
});
const { job: done } = await panel.jobs.wait(job.id, { intervalMs: 500 });
console.log(done.output.statements, done.output.error);
```

**Response** `202 Accepted` with the job. Its output has `name`, `allowChanges`, `elapsedMs`, one entry per statement in `statements` (each with its `sql` and its result), and `error` when a statement failed: `{ code, sqlState, line, message }`, plus `hint` for a change refused in read-only mode.

## Open in phpMyAdmin

`POST /api/v1/databases/:id/phpmyadmin` — Permission: databases.manage — Token scope: manage

One-click phpMyAdmin sign-in. The agent leaves a one-time ticket, valid for two minutes, for a fresh token; open phpMyAdmin with the token to be signed in as the database's own full-access account. Only the token's SHA-256 goes into the job; the token itself is returned only to you. phpMyAdmin must be set up on the server (`PHPMYADMIN_SETUP`). See [phpMyAdmin](https://docs.vaultpanel.net/guides/databases/phpmyadmin).

**Response** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "job": { "id": "…", "type": "PHPMYADMIN_SIGNON", "status": "queued" },
    "token": "…",
    "phpmyadmin": { "port": 8081, "domain": null, "host": "203.0.113.10", "isLocal": false }
  },
  "message": "OK",
  "requestId": "…"
}
```

Wait for the job to succeed before opening phpMyAdmin with the token.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `PHPMYADMIN_NOT_SET_UP` | phpMyAdmin is not set up on this server. |
| 409 | `DATABASE_NOT_READY` | The database is not ready on its server. |

## List database users

`GET /api/v1/database-users` — Permission: databases.read — Token scope: read

Users, by username, each with the databases it can reach. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Matches the username. |
| `serverId` | string | No | Users on one server. |
| `sort` | string | No | `username` (default, ascending) or `createdAt`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/database-users \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.databases.users.list();
```

**Response** `200 OK`: `{ items: [user], pagination }`.

## Create a database user

`POST /api/v1/database-users` — Permission: databases.manage — Token scope: manage

Creates a user (`CREATE_DATABASE_USER`) with access to the given databases on the same server.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string | Yes | The server. |
| `username` | string | Yes | 2 to 32 lowercase letters, digits and underscores, starting with a letter. |
| `password` | string | No | 12 to 72 letters, digits or the symbols `! # % + , . : = ? @ ^ _ ~ -`. Generated when left out. |
| `privileges` | string | No | `all` (default) or `readonly`. |
| `databaseIds` | string[] | No | Up to 50 databases on the same server. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/database-users \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"serverId":"1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b","username":"reports","privileges":"readonly","databaseIds":["8d7c6b5a-4938-4271-a6b5-c4d3e2f1a0b9"]}'
```

**JavaScript**

```js
const { user, password } = await panel.databases.users.create({
  serverId,
  username: 'reports',
  privileges: 'readonly',
  databaseIds: [databaseId],
});
```

**Response** `202 Accepted` with `{ user, job, password }`. `password` is the generated password, shown once, or `null` when you gave one.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `SERVER_NOT_READY`, `DATABASE_SERVER_NOT_INSTALLED`, `AGENT_OUTDATED` | As for [Create a database](https://docs.vaultpanel.net/api-reference/databases#create-a-database). |
| 409 | `QUOTA_REACHED` | A hosting customer's plan allows no more database users. |
| 422 | `VALIDATION_ERROR` | An invalid or taken username, an invalid password, or a database on another server. |

## Update a database user

`PATCH /api/v1/database-users/:id` — Permission: databases.manage — Token scope: manage

Changes a user's password, access or databases (`UPDATE_DATABASE_USER`). `databaseIds` replaces the list. Send at least one field, and not both `password` and `generatePassword`.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | string | No | A new password, with the same rules as for create. |
| `generatePassword` | boolean | No | Generate a new password and return it once. |
| `privileges` | string | No | `all` or `readonly`. |
| `databaseIds` | string[] | No | Up to 50 databases on the same server. |

**Example request**

**cURL**

```bash
curl -X PATCH https://panel.example.com/api/v1/database-users/b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"generatePassword":true}'
```

**JavaScript**

```js
const { password } = await panel.databases.users.update(userId, { generatePassword: true });
```

**Response** `202 Accepted` with `{ user, job, password }`. `password` is set only with `generatePassword`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `DATABASE_USER_NOT_READY` | The user was never created on the server. Delete it and create it again. |
| 409 | `DATABASE_BUSY` | Another change to this user is running. |
| 422 | `VALIDATION_ERROR` | Nothing to update, both password fields, or an invalid value. |

## Delete a database user

`DELETE /api/v1/database-users/:id` — Permission: databases.manage — Token scope: manage

Drops the user on the server (`DELETE_DATABASE_USER`). Its databases stay.

**Example request**

**cURL**

```bash
curl -X DELETE https://panel.example.com/api/v1/database-users/b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.databases.users.remove(userId);
```

**Response** `202 Accepted` with `{ user, job }`.

## Reveal a user's password

`POST /api/v1/database-users/:id/password` — Permission: databases.manage — Token scope: manage

The user's current password and how to connect, decrypted on request. Every reveal is recorded in the audit log.

**Example request**

**cURL**

```bash
curl -X POST https://panel.example.com/api/v1/database-users/b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/password \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { connectionUrl } = await panel.databases.users.password(userId);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "username": "shop",
    "password": "k2Vb9…",
    "host": "127.0.0.1",
    "port": 3306,
    "connectionUrl": "mysql://shop:k2Vb9…@127.0.0.1:3306/shop"
  },
  "message": "OK",
  "requestId": "…"
}
```

`connectionUrl` names the user's first database, or is `null` when it has none.
