Databases (per-website)¶

Per-website databases - create, clone, delete, export/import, user permissions. Backend selects MySQL/MariaDB/PostgreSQL/MongoDB per webapp config.

All endpoints below are mounted under /api. Authentication: Authorization: Bearer <token> unless noted as public.

Endpoint count: 30

Endpoints¶

Method	Path	Handler	Guards
`DELETE`	`/api/databases/:id`	`deleteDatabase`	RequirePermission(db, "websites_management")
`GET`	`/api/databases/:id/download`	`downloadDatabaseExport`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/:id/duplicate`	`duplicateDatabase`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/:id/export`	`exportDatabase`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/:id/import`	`importDatabase`	RequirePermission(db, "websites_management")
`GET`	`/api/databases/:id/users`	`func`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/:id/users`	`createDBUser`	RequirePermission(db, "websites_management")
`DELETE`	`/api/databases/:id/users/:username`	`deleteDBUser`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/:id/users/:username/reset-password`	`resetDBUserPassword`	RequirePermission(db, "websites_management")
`DELETE`	`/api/databases/mongo/:id`	`deleteMongoDatabase`	RequirePermission(db, "websites_management")
`GET`	`/api/databases/mongo/:id/download`	`downloadMongoExport`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/mongo/:id/export`	`exportMongoDatabase`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/mongo/:id/import`	`importMongoDatabase`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/mongo/:id/users`	`createMongoDBUser`	RequirePermission(db, "websites_management")
`DELETE`	`/api/databases/mongo/:id/users/:username`	`deleteMongoDBUser`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/mongo/:id/users/:username/reset-password`	`resetMongoDBUserPassword`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/mongo/admin/associate`	`associateMongoDatabase`	RequirePermission(db, "administrative_operations")
`GET`	`/api/databases/mongo/admin/unassociated`	`listUnassociatedMongoDatabases`	RequirePermission(db, "administrative_operations")
`GET`	`/api/databases/mongo/check-name`	`checkMongoNameAvailable`	RequirePermission(db, "websites_management")
`GET`	`/api/databases/mysql-host`	`func`	RequirePermission(db, "websites_management")
`DELETE`	`/api/databases/pg/:id`	`deletePgDatabase`	RequirePermission(db, "websites_management")
`GET`	`/api/databases/pg/:id/download`	`downloadPgDatabaseExport`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/pg/:id/export`	`exportPgDatabase`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/pg/:id/import`	`importPgDatabase`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/pg/:id/users`	`createPgDBUser`	RequirePermission(db, "websites_management")
`DELETE`	`/api/databases/pg/:id/users/:username`	`deletePgDBUser`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/pg/:id/users/:username/reset-password`	`resetPgDBUserPassword`	RequirePermission(db, "websites_management")
`POST`	`/api/databases/pg/admin/associate`	`associatePgDatabase`	RequirePermission(db, "administrative_operations")
`GET`	`/api/databases/pg/admin/unassociated`	`listUnassociatedPgDatabases`	RequirePermission(db, "administrative_operations")
`GET`	`/api/databases/pg/check-name`	`checkPgNameAvailable`	RequirePermission(db, "websites_management")

Source¶

Handlers for this section live in api/routes/handlers_*.go in the StarkOne source. Each handler binds its request body with gin.ShouldBindJSON(&req) and responds with the standard envelope:

{ "data": { ... } }

On error:

{ "error": { "code": "string", "message": "string" } }

Reference¶

`DELETE /api/databases/:id`¶

Deletes the MySQL/MariaDB database identified by its panel record id (drops the database and removes the panel record via databases.Delete).

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the database to delete.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`bad_request`	`id` path param is not a valid integer.
`500`	`delete_failed`	The underlying delete operation failed.

Side effects

Drops the MySQL/MariaDB database on the server and deletes the panel record (databases.Delete).

Example

curl -X DELETE https://panel.example.com:2087/api/databases/42 \
  -H "Authorization: Bearer $TOKEN"

`GET /api/databases/:id/download`¶

Serves a previously exported MySQL dump file (gzipped SQL) for download, after verifying the file lives inside the owning site user's db directory.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the database the export belongs to.

Query parameters

Name	Type	Optional	Description
`file`	string	no	Absolute path of the export file. Must start with `/home/<site_user>/db/`.

Response - 200 OK

Streams the file as an attachment. Headers: Content-Disposition: attachment; filename=<name>, Content-Type: application/gzip. Not a JSON envelope.

Errors

Status	Code	Meaning
`400`	`bad_request`	`id` not a valid integer.
`400`	`bad_request`	`file` query parameter is missing.
`404`	`not_found`	Database, website, or file not found.
`403`	`forbidden`	`file` path is outside the site user's `db` directory.

Example

curl -X GET "https://panel.example.com:2087/api/databases/42/download?file=/home/user1/db/user1_blog.sql.gz" \
  -H "Authorization: Bearer $TOKEN" -OJ

`POST /api/databases/:id/duplicate`¶

Duplicates an existing MySQL database into a new database (with its own name, user, and password) under the given website (databases.Duplicate).

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the source database to copy.

Request body

{
  "name": "string (required)",
  "username": "string (required)",
  "password": "string (required)",
  "website_id": "integer (required)"
}

Field	Type	Required	Description
`name`	string	yes	Name of the new (target) database.
`username`	string	yes	Username for the new database's user.
`password`	string	yes	Password for the new user.
`website_id`	integer	yes	Website the new database belongs to.

Response - 201 Created

{ "data": { "id": 0, "name": "string", "website_id": 0, "users": [], "...": "Database struct from databases.Duplicate" } }

Errors

Status	Code	Meaning
`400`	`bad_request`	`id` not a valid integer, or request body invalid / missing required fields.
`500`	`duplicate_failed`	The duplicate operation failed.

Side effects

Creates a new MySQL database, copies the source data into it, and creates the new user (databases.Duplicate).

Example

curl -X POST https://panel.example.com:2087/api/databases/42/duplicate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"user1_blog_copy","username":"user1_copy","password":"s3cret","website_id":7}'

`POST /api/databases/:id/export`¶

Exports a MySQL database to a gzipped SQL dump in the site user's db directory, streaming progress over Server-Sent Events; optionally uploads the dump to a transfer.sh-style host.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the database to export.

Request body (optional; both default to false)

{ "save_to_server": false, "upload_to_cloud": false }

Field	Type	Required	Description
`save_to_server`	boolean	no	If true, chowns the output file to the site user for persistence.
`upload_to_cloud`	boolean	no	If true, uploads the dump to the configured transfer host (`transfersh_url` setting, default `https://wget.co.il`).

Response - 200 OK

Server-Sent Events stream (Content-Type: text/event-stream). Each event is data: {json}. Progress events: {"type":"progress","message":"..."}. Errors: {"type":"error","message":"..."}. Final event:

{ "type": "done", "download_url": "/api/databases/42/download?file=...", "file_path": "/home/user1/db/user1_blog.sql.gz", "cloud_url": "" }

Side effects

Creates /home/<site_user>/db if missing and chowns it to the site user.
Runs mysqldump (with the panel's safe-args set) piped through gzip -c into /home/<site_user>/db/<dbname>.sql.gz.
Optionally chowns the file (when save_to_server) and uploads it via curl --upload-file (when upload_to_cloud).

Example

curl -N -X POST https://panel.example.com:2087/api/databases/42/export \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"save_to_server":true,"upload_to_cloud":false}'

`POST /api/databases/:id/import`¶

Imports a SQL file (local path or downloaded URL) into a MySQL database, streaming progress over Server-Sent Events; auto-decompresses .gz/.zip and validates the file looks like SQL before importing.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the target database.

Request body (one of file or url is required)

{ "file": "string", "url": "string" }

Field	Type	Required	Description
`file`	string	conditional	Absolute path of a SQL file already on the server.
`url`	string	conditional	URL to download the SQL file from (saved into the site user's `db` directory via `wget`).

At least one of file or url must be supplied.

Response - 200 OK

Server-Sent Events stream. Progress events {"type":"progress","message":"..."}, errors {"type":"error","message":"..."}, and a final {"type":"done","message":"Import successful"}.

Errors

Status	Code	Meaning
`400`	`bad_request`	`id` invalid, body invalid, or neither `file` nor `url` provided.
`404`	`not_found`	Database not found.

Note: once the SSE stream has started, failures (download failure, empty/binary/HTML file, MySQL errors) are reported as {"type":"error",...} events rather than HTTP status codes.

Side effects

Optionally downloads the file with wget into /home/<site_user>/db and chowns it.
Decompresses .gz via gunzip or .zip via unzip (detected by extension or magic bytes).
Imports with mysql --defaults-file=/etc/starkone/.mysql.conf <dbname>.
Removes temporary download/extraction files afterward.

Example

curl -N -X POST https://panel.example.com:2087/api/databases/42/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/dumps/blog.sql.gz"}'

`GET /api/databases/:id/users`¶

Stub endpoint: returns a static message directing callers to use /api/webapps/:id/databases for listing database users. It is an inline handler that does not query the database.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Present in the path but not used by the handler.

Response - 200 OK

{ "data": { "message": "use /api/webapps/:id/databases" } }

Example

curl -X GET https://panel.example.com:2087/api/databases/42/users \
  -H "Authorization: Bearer $TOKEN"

`POST /api/databases/:id/users`¶

Creates a new MySQL user with access to the given database, defaulting the host to localhost when not specified (databases.CreateUserWithHost).

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the database to attach the user to.

Request body

{ "username": "string (required)", "password": "string (required)", "host": "string (optional)" }

Field	Type	Required	Description
`username`	string	yes	MySQL username to create.
`password`	string	yes	Password for the new user.
`host`	string	no	Host the user may connect from; defaults to `localhost`.

Response - 201 Created

{ "data": { "...": "user record from databases.CreateUserWithHost" } }

Errors

Status	Code	Meaning
`400`	`bad_request`	`id` invalid or body missing required fields.
`500`	`create_failed`	User creation failed.

Side effects

Creates the MySQL user and grants it on the database (databases.CreateUserWithHost).

Example

curl -X POST https://panel.example.com:2087/api/databases/42/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"user1_app","password":"s3cret","host":"localhost"}'

`DELETE /api/databases/:id/users/:username`¶

Removes a MySQL user from the given database (databases.DeleteUser).

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the database.
`username`	string	MySQL username to remove.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`bad_request`	`id` not a valid integer.
`500`	`delete_failed`	User deletion failed.

Side effects

Drops the MySQL user / revokes grants (databases.DeleteUser).

Example

curl -X DELETE https://panel.example.com:2087/api/databases/42/users/user1_app \
  -H "Authorization: Bearer $TOKEN"

`POST /api/databases/:id/users/:username/reset-password`¶

Resets the password of an existing MySQL user on the given database (databases.ResetUserPassword).

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the database.
`username`	string	MySQL username whose password is reset.

Request body

{ "password": "string (required)" }

Field	Type	Required	Description
`password`	string	yes	New password for the user.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`bad_request`	`id` invalid or body missing `password`.
`500`	`reset_failed`	Password reset failed.

Side effects

Updates the MySQL user's password (databases.ResetUserPassword).

Example

curl -X POST https://panel.example.com:2087/api/databases/42/users/user1_app/reset-password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password":"n3wsecret"}'

`DELETE /api/databases/mongo/:id`¶

Deletes a MongoDB database identified by its panel record id (mongodatabases.Delete). Requires the MongoDB plugin to be enabled.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the MongoDB database.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`id` not a valid integer.
`500`	`delete_failed`	Delete operation failed.

Side effects

Drops the MongoDB database and removes the panel record (mongodatabases.Delete).

Example

curl -X DELETE https://panel.example.com:2087/api/databases/mongo/12 \
  -H "Authorization: Bearer $TOKEN"

`GET /api/databases/mongo/:id/download`¶

Serves a previously exported MongoDB archive for download, after verifying the file lives in the owning site user's db directory. Requires the MongoDB plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the MongoDB database.

Query parameters

Name	Type	Optional	Description
`file`	string	no	Absolute path of the export file. Must start with `/home/<site_user>/db/`.

Response - 200 OK

Streams the file as an attachment. Headers: Content-Disposition: attachment; filename=<name>, Content-Type: application/octet-stream. Not a JSON envelope.

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`id` invalid or `file` missing.
`404`	`not_found`	MongoDB database or file not found.
`403`	`forbidden`	`file` path outside the site user's `db` directory.

Example

curl -X GET "https://panel.example.com:2087/api/databases/mongo/12/download?file=/home/user1/db/user1_app.archive.gz" \
  -H "Authorization: Bearer $TOKEN" -OJ

`POST /api/databases/mongo/:id/export`¶

Exports a MongoDB database to a gzipped archive in the site user's db directory using mongodump, streaming progress over Server-Sent Events. Requires the MongoDB plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the MongoDB database.

Response - 200 OK

Server-Sent Events stream. Progress events {"type":"progress","message":"..."}, error events {"type":"error","message":"..."}, and a final event:

{ "type": "done", "download_url": "/api/databases/mongo/12/download?file=...", "file_path": "/home/user1/db/user1_app.archive.gz" }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`id` not a valid integer.
`404`	`not_found`	MongoDB database not found.

Side effects

Creates /home/<site_user>/db if missing and chowns it.
Runs mongodump --archive=<file> --gzip and chowns the resulting archive to the site user.

Example

curl -N -X POST https://panel.example.com:2087/api/databases/mongo/12/export \
  -H "Authorization: Bearer $TOKEN"

`POST /api/databases/mongo/:id/import`¶

Imports data into a MongoDB database from a local path or downloaded URL, streaming progress over Server-Sent Events. Chooses mongorestore (directories, archives, .gz) or mongoimport (.json) based on the input. Requires the MongoDB plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the target MongoDB database.

Request body (one of file or url is required)

{ "file": "string", "url": "string" }

Field	Type	Required	Description
`file`	string	conditional	Absolute path of an archive/dump/JSON file on the server.
`url`	string	conditional	URL to download the import file from (via `wget`).

At least one of file or url must be supplied.

Response - 200 OK

Server-Sent Events stream. Progress events, error events, and a final {"type":"done","message":"Import successful"}.

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`id` invalid, body invalid, or neither `file` nor `url` provided.
`404`	`not_found`	MongoDB database not found.

Side effects

Optionally downloads the file with wget into /home/<site_user>/db and chowns it.
Runs mongorestore (with --drop for archive/dir restores) or mongoimport against the target database.
Removes the temporary downloaded file afterward.

Example

curl -N -X POST https://panel.example.com:2087/api/databases/mongo/12/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/dumps/app.archive.gz"}'

`POST /api/databases/mongo/:id/users`¶

Creates a MongoDB user for the given database. Unless full_name is set, the username is prefixed with the site username (<site>_<username>) and truncated to 38 chars (mongodatabases.CreateUser). Requires the MongoDB plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the MongoDB database.

Request body

{ "username": "string (required)", "password": "string (optional)", "full_name": false }

Field	Type	Required	Description
`username`	string	yes	Username (letters, numbers, underscore only).
`password`	string	no	Password for the user.
`full_name`	boolean	no	If true, use `username` verbatim (no site prefix); otherwise prefix with the site username.

Response - 201 Created

{ "data": { "...": "user record from mongodatabases.CreateUser" } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`id` invalid or body invalid.
`400`	`invalid_username`	Username contains characters other than letters, numbers, underscore.
`404`	`not_found`	MongoDB database not found (when resolving the site prefix).
`500`	`create_failed`	User creation failed.

Side effects

Creates the MongoDB user with access to the database (mongodatabases.CreateUser).

Example

curl -X POST https://panel.example.com:2087/api/databases/mongo/12/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"app","password":"s3cret","full_name":false}'

`DELETE /api/databases/mongo/:id/users/:username`¶

Removes a MongoDB user from the given database (mongodatabases.DeleteUser). Requires the MongoDB plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the MongoDB database.
`username`	string	MongoDB username to remove.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`id` not a valid integer.
`500`	`delete_failed`	User deletion failed.

Side effects

Drops the MongoDB user (mongodatabases.DeleteUser).

Example

curl -X DELETE https://panel.example.com:2087/api/databases/mongo/12/users/user1_app \
  -H "Authorization: Bearer $TOKEN"

`POST /api/databases/mongo/:id/users/:username/reset-password`¶

Resets the password of an existing MongoDB user on the given database (mongodatabases.ResetUserPassword). Requires the MongoDB plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the MongoDB database.
`username`	string	MongoDB username whose password is reset.

Request body

{ "password": "string (required)" }

Field	Type	Required	Description
`password`	string	yes	New password for the user.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`id` invalid or body missing `password`.
`500`	`reset_failed`	Password reset failed.

Side effects

Updates the MongoDB user's password (mongodatabases.ResetUserPassword).

Example

curl -X POST https://panel.example.com:2087/api/databases/mongo/12/users/user1_app/reset-password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password":"n3wsecret"}'

`POST /api/databases/mongo/admin/associate`¶

Associates an existing (unmanaged) MongoDB database with a website, creating a panel record for it (mongodatabases.AssociateToWebsite). Requires the MongoDB plugin.

Guards: RequirePermission(db, "administrative_operations")

Request body

{ "db_name": "string (required)", "website_id": "integer (required)" }

Field	Type	Required	Description
`db_name`	string	yes	Name of the existing MongoDB database to associate.
`website_id`	integer	yes	Website to associate the database with.

Response - 201 Created

{ "data": { "...": "MongoDatabase record from mongodatabases.AssociateToWebsite" } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	Body invalid or missing required fields.
`500`	`associate_failed`	Association failed.

Side effects

Inserts a panel record linking the MongoDB database to the website (mongodatabases.AssociateToWebsite).

Example

curl -X POST https://panel.example.com:2087/api/databases/mongo/admin/associate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"db_name":"legacy_app","website_id":7}'

`GET /api/databases/mongo/admin/unassociated`¶

Lists MongoDB databases present on the server that are not yet associated with any website (mongodatabases.ListUnassociated). Requires the MongoDB plugin.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

{ "data": { "databases": ["legacy_app", "old_data"] } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`500`	`server_error`	Listing failed.

Example

curl -X GET https://panel.example.com:2087/api/databases/mongo/admin/unassociated \
  -H "Authorization: Bearer $TOKEN"

`GET /api/databases/mongo/check-name`¶

Checks whether a MongoDB database or user name is available (not already recorded in the panel). Requires the MongoDB plugin.

Guards: RequirePermission(db, "websites_management")

Query parameters

Name	Type	Optional	Description
`name`	string	no	The name to check.
`type`	string	yes	`user` to check usernames, anything else (or omitted) checks database names.

Response - 200 OK

{ "data": { "available": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	MongoDB plugin is not enabled.
`400`	`bad_request`	`name` query parameter is missing.

Example

curl -X GET "https://panel.example.com:2087/api/databases/mongo/check-name?name=app&type=db" \
  -H "Authorization: Bearer $TOKEN"

`GET /api/databases/mysql-host`¶

Returns the MySQL host the panel uses for client connections, read from /etc/starkone/.mysql.conf (defaults to localhost). Inline handler.

Guards: RequirePermission(db, "websites_management")

Response - 200 OK

{ "data": { "host": "localhost" } }

Example

curl -X GET https://panel.example.com:2087/api/databases/mysql-host \
  -H "Authorization: Bearer $TOKEN"

`DELETE /api/databases/pg/:id`¶

Deletes a PostgreSQL database identified by its panel record id (pgdatabases.Delete). Requires the PostgreSQL plugin to be enabled.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the PostgreSQL database.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`id` not a valid integer.
`500`	`delete_failed`	Delete operation failed.

Side effects

Drops the PostgreSQL database and removes the panel record (pgdatabases.Delete).

Example

curl -X DELETE https://panel.example.com:2087/api/databases/pg/9 \
  -H "Authorization: Bearer $TOKEN"

`GET /api/databases/pg/:id/download`¶

Serves a previously exported PostgreSQL dump for download, after verifying the file lives in the owning site user's db directory. Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the PostgreSQL database.

Query parameters

Name	Type	Optional	Description
`file`	string	no	Absolute path of the export file. Must start with `/home/<site_user>/db/`.

Response - 200 OK

Streams the file as an attachment. Headers: Content-Disposition: attachment; filename=<name>, Content-Type: application/octet-stream. Not a JSON envelope.

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`id` invalid or `file` missing.
`404`	`not_found`	PostgreSQL database or file not found.
`403`	`forbidden`	`file` path outside the site user's `db` directory.

Example

curl -X GET "https://panel.example.com:2087/api/databases/pg/9/download?file=/home/user1/db/user1_app.sql" \
  -H "Authorization: Bearer $TOKEN" -OJ

`POST /api/databases/pg/:id/export`¶

Exports a PostgreSQL database to a SQL file in the site user's db directory using pg_dump, streaming progress over Server-Sent Events. Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the PostgreSQL database.

Response - 200 OK

Server-Sent Events stream. Progress events {"type":"progress","message":"..."}, error events, and a final event:

{ "type": "done", "download_url": "/api/databases/pg/9/download?file=...", "file_path": "/home/user1/db/user1_app.sql" }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`id` not a valid integer.
`404`	`not_found`	PostgreSQL database not found.

Side effects

Creates /home/<site_user>/db if missing and chowns it.
Runs pg_dump (as the postgres role, with PGPASSWORD when a password is configured, otherwise via sudo -u postgres) writing to <dbname>.sql, then chowns it to the site user.

Example

curl -N -X POST https://panel.example.com:2087/api/databases/pg/9/export \
  -H "Authorization: Bearer $TOKEN"

`POST /api/databases/pg/:id/import`¶

Imports a SQL file (local path or downloaded URL) into a PostgreSQL database via psql, streaming progress over Server-Sent Events; auto-decompresses .gz/.zip. Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the target PostgreSQL database.

Request body (one of file or url is required)

{ "file": "string", "url": "string" }

Field	Type	Required	Description
`file`	string	conditional	Absolute path of a SQL file on the server.
`url`	string	conditional	URL to download the SQL file from (via `wget`).

At least one of file or url must be supplied.

Response - 200 OK

Server-Sent Events stream. Progress events, error events, and a final {"type":"done","message":"Import successful"}.

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`id` invalid, body invalid, or neither `file` nor `url` provided.
`404`	`not_found`	PostgreSQL database not found.

Side effects

Optionally downloads the file with wget into /home/<site_user>/db and chowns it.
Decompresses .gz via gunzip or .zip via unzip (by extension or magic bytes).
Imports with psql ... -f <file> (as the postgres role, with PGPASSWORD when configured, otherwise via sudo -u postgres).
Removes temporary download/extraction files afterward.

Example

curl -N -X POST https://panel.example.com:2087/api/databases/pg/9/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/dumps/app.sql.gz"}'

`POST /api/databases/pg/:id/users`¶

Creates a PostgreSQL role/user for the given database. Unless full_name is set, the username is prefixed with the site username (<site>_<username>) and truncated to 63 chars (pgdatabases.CreateUser). Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the PostgreSQL database.

Request body

{ "username": "string (required)", "password": "string (optional)", "full_name": false }

Field	Type	Required	Description
`username`	string	yes	Username (letters, numbers, underscore only).
`password`	string	no	Password for the role.
`full_name`	boolean	no	If true, use `username` verbatim (no site prefix); otherwise prefix with the site username.

Response - 201 Created

{ "data": { "...": "user record from pgdatabases.CreateUser" } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`id` invalid or body invalid.
`400`	`invalid_username`	Username contains characters other than letters, numbers, underscore.
`404`	`not_found`	PostgreSQL database not found (when resolving the site prefix).
`500`	`create_failed`	Role creation failed.

Side effects

Creates the PostgreSQL role and grants it on the database (pgdatabases.CreateUser).

Example

curl -X POST https://panel.example.com:2087/api/databases/pg/9/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"app","password":"s3cret","full_name":false}'

`DELETE /api/databases/pg/:id/users/:username`¶

Removes a PostgreSQL role from the given database (pgdatabases.DeleteUser). Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the PostgreSQL database.
`username`	string	PostgreSQL role to remove.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`id` not a valid integer.
`500`	`delete_failed`	Role deletion failed.

Side effects

Drops the PostgreSQL role (pgdatabases.DeleteUser).

Example

curl -X DELETE https://panel.example.com:2087/api/databases/pg/9/users/user1_app \
  -H "Authorization: Bearer $TOKEN"

`POST /api/databases/pg/:id/users/:username/reset-password`¶

Resets the password of an existing PostgreSQL role on the given database (pgdatabases.ResetUserPassword). Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "websites_management")

Path parameters

Name	Type	Description
`id`	integer	Panel record id of the PostgreSQL database.
`username`	string	PostgreSQL role whose password is reset.

Request body

{ "password": "string (required)" }

Field	Type	Required	Description
`password`	string	yes	New password for the role.

Response - 200 OK

{ "data": { "success": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`id` invalid or body missing `password`.
`500`	`reset_failed`	Password reset failed.

Side effects

Updates the PostgreSQL role's password (pgdatabases.ResetUserPassword).

Example

curl -X POST https://panel.example.com:2087/api/databases/pg/9/users/user1_app/reset-password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password":"n3wsecret"}'

`POST /api/databases/pg/admin/associate`¶

Associates an existing (unmanaged) PostgreSQL database with a website, creating a panel record for it (pgdatabases.AssociateToWebsite). Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "administrative_operations")

Request body

{ "db_name": "string (required)", "website_id": "integer (required)" }

Field	Type	Required	Description
`db_name`	string	yes	Name of the existing PostgreSQL database to associate.
`website_id`	integer	yes	Website to associate the database with.

Response - 201 Created

{ "data": { "...": "PgDatabase record from pgdatabases.AssociateToWebsite" } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	Body invalid or missing required fields.
`500`	`associate_failed`	Association failed.

Side effects

Inserts a panel record linking the PostgreSQL database to the website (pgdatabases.AssociateToWebsite).

Example

curl -X POST https://panel.example.com:2087/api/databases/pg/admin/associate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"db_name":"legacy_app","website_id":7}'

`GET /api/databases/pg/admin/unassociated`¶

Lists PostgreSQL databases present on the server that are not yet associated with any website (pgdatabases.ListUnassociated). Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

{ "data": { "databases": ["legacy_app", "old_data"] } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`500`	`server_error`	Listing failed.

Example

curl -X GET https://panel.example.com:2087/api/databases/pg/admin/unassociated \
  -H "Authorization: Bearer $TOKEN"

`GET /api/databases/pg/check-name`¶

Checks whether a PostgreSQL database or role name is available (not already recorded in the panel). Requires the PostgreSQL plugin.

Guards: RequirePermission(db, "websites_management")

Query parameters

Name	Type	Optional	Description
`name`	string	no	The name to check.
`type`	string	yes	`user` to check role names, anything else (or omitted) checks database names.

Response - 200 OK

{ "data": { "available": true } }

Errors

Status	Code	Meaning
`400`	`plugin_disabled`	PostgreSQL plugin is not enabled.
`400`	`bad_request`	`name` query parameter is missing.

Example

curl -X GET "https://panel.example.com:2087/api/databases/pg/check-name?name=app&type=db" \
  -H "Authorization: Bearer $TOKEN"

Databases (per-website)¶

Endpoints¶

Source¶

Reference¶

DELETE /api/databases/:id¶

GET /api/databases/:id/download¶

POST /api/databases/:id/duplicate¶

POST /api/databases/:id/export¶

POST /api/databases/:id/import¶

GET /api/databases/:id/users¶

POST /api/databases/:id/users¶

DELETE /api/databases/:id/users/:username¶

POST /api/databases/:id/users/:username/reset-password¶

DELETE /api/databases/mongo/:id¶

GET /api/databases/mongo/:id/download¶

POST /api/databases/mongo/:id/export¶

POST /api/databases/mongo/:id/import¶

POST /api/databases/mongo/:id/users¶

DELETE /api/databases/mongo/:id/users/:username¶

POST /api/databases/mongo/:id/users/:username/reset-password¶

POST /api/databases/mongo/admin/associate¶

GET /api/databases/mongo/admin/unassociated¶

GET /api/databases/mongo/check-name¶

GET /api/databases/mysql-host¶

DELETE /api/databases/pg/:id¶

GET /api/databases/pg/:id/download¶

POST /api/databases/pg/:id/export¶

POST /api/databases/pg/:id/import¶

POST /api/databases/pg/:id/users¶

DELETE /api/databases/pg/:id/users/:username¶

POST /api/databases/pg/:id/users/:username/reset-password¶

POST /api/databases/pg/admin/associate¶

GET /api/databases/pg/admin/unassociated¶

GET /api/databases/pg/check-name¶

`DELETE /api/databases/:id`¶

`GET /api/databases/:id/download`¶

`POST /api/databases/:id/duplicate`¶

`POST /api/databases/:id/export`¶

`POST /api/databases/:id/import`¶

`GET /api/databases/:id/users`¶

`POST /api/databases/:id/users`¶

`DELETE /api/databases/:id/users/:username`¶

`POST /api/databases/:id/users/:username/reset-password`¶

`DELETE /api/databases/mongo/:id`¶

`GET /api/databases/mongo/:id/download`¶

`POST /api/databases/mongo/:id/export`¶

`POST /api/databases/mongo/:id/import`¶

`POST /api/databases/mongo/:id/users`¶

`DELETE /api/databases/mongo/:id/users/:username`¶

`POST /api/databases/mongo/:id/users/:username/reset-password`¶

`POST /api/databases/mongo/admin/associate`¶

`GET /api/databases/mongo/admin/unassociated`¶

`GET /api/databases/mongo/check-name`¶

`GET /api/databases/mysql-host`¶

`DELETE /api/databases/pg/:id`¶

`GET /api/databases/pg/:id/download`¶

`POST /api/databases/pg/:id/export`¶

`POST /api/databases/pg/:id/import`¶

`POST /api/databases/pg/:id/users`¶

`DELETE /api/databases/pg/:id/users/:username`¶

`POST /api/databases/pg/:id/users/:username/reset-password`¶

`POST /api/databases/pg/admin/associate`¶

`GET /api/databases/pg/admin/unassociated`¶

`GET /api/databases/pg/check-name`¶