CreatBot/CreatBotMoonraker
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
CreatBotMoonraker/docs/external_api/database.md
Eric Callahan 9c550a8f9a docs: complete API documentation rework 
Moonraker's external API documentation has been significantly
overhauled in an effort to improve clarity and readability.
All parameters and responses are documented with specifications.
Tables and other elements are used to make documentation more
visible and less verbose.

Spelling and other corrections have also been added.

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
2025-02-06 19:15:38 -05:00

774 lines
23 KiB
Markdown
Raw Blame History

# Database Management
The following endpoints provide access to Moonraker's internal sqlite database.
The primary table exposed to clients is divided into `namespaces`. Each client
may define its own namespace to store information. From the client's point of
view, a namespace is an `object`. Items in the database are accessed by providing
a namespace and a key. A key may be specified as string, where a "." is a
delimiter to access nested fields. Alternatively the key may be specified
as an array of strings, where each string references a nested field.
This is useful for scenarios where a namespace contains fields that include
a "." character, such as a file name.
/// note
Moonraker reserves several namespaces for internal use. Clients may read from
these namespaces but they may not modify them.
///
For example, assume the following object is stored in the "superclient"
namespace:
```json
{
"settings": {
"console": {
"enable_autocomplete": true
}
},
"theme": {
"background_color": "black"
}
}
```
One may access the `enable_autocomplete` field by supplying `superclient` as
the `namespace` argument and `settings.console.enable_autocomplete` or
`["settings", "console", "enable_autocomplete"]` as the `key` argument for
the request. The entire settings object could be accessed by providing
`settings` or `["settings"]` as the `key` argument. The entire namespace
may be read by omitting the `key` argument, however as explained below it
is not possible to modify a namespace without specifying a key.
## List Database Info
Lists all namespaces with read and/or write access. Also lists database
backup files.
```{.http .apirequest title="HTTP Request"}
GET /server/database/list
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.list",
"id": 8694
}
```
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"namespaces": [
"gcode_metadata",
"webcams",
"update_manager",
"announcements",
"database",
"moonraker"
],
"backups": [
"sqldb-backup-20240513-134542.db",
"testbackup.db",
"testbackup2.db"
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ------------ | :------: | ---------------------------------------------------- |
| `namespaces` | [string] | An array of namespaces registered with the database |
| | | that may be read by clients. |^
| `backups` | [string] | An array of database backup filenames that have been |
| | | created. |^
///
## Get Database Item
Retrieves an item from a specified namespace. The `key` argument may be
omitted, in which case an object representing the entire namespace will
be returned in the `value` field. If the `key` is provided and does not
exist in the database an error will be returned.
```{.http .apirequest title="HTTP Request"}
GET /server/database/item?namespace={namespace}&key={key}
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.get_item",
"params": {
"namespace": "{namespace}",
"key": "{key}"
},
"id": 5644
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ----------- | :----------------: | ------------ | ------------------------------------------ |
| `namespace` | string | **REQUIRED** | The namespace of the item to retrieve. |
| `key` | string \| [string] | null | The key indicating the field or fields |
| | \| null | | within the namespace to retrieve. May |^
| | | | be a string, where nested fields are |^
| | | | separated by a ".", or a list of strings. |^
| | | | If the key is omitted the entire namespace |^
| | | | will be returned. |^
///
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"namespace": "moonraker",
"key": "file_manager.metadata_version",
"value": 2
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ----------- | :----------------: | ------------------------------------------------- |
| `namespace` | string | The namespace of the returned item. |
| `key` | string \| [string] | The key indicating the requested field(s). |
| | \| null | |^
| `value` | any | The value of the requested item. This can be any |
| | | valid JSON type. |^
///
## Add Database Item
Inserts an item into the database. If the `namespace` does not exist
it will be created. If the `key` specifies a nested field, all parents
will be created if they do not exist. If the key exists it will be
overwritten with the provided `value`. The `key` parameter must be provided,
as it is not possible to assign a value directly to a namespace.
/// note
If the request parameters are placed in the query string and the `value`
is not a string type, then `value` argument must provide a
[type hint](./introduction.md#query-string-type-hints). It is strongly
recommended to put parameters in the body of the request wrapped in a
JSON object.
///
```{.http .apirequest title="HTTP Request"}
POST /server/database/item
Content-Type: application/json
{
"namespace": "my_client",
"key": "settings.some_count",
"value": 100
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ----------- | :----------------: | ------------ | ----------------------------------------- |
| `namespace` | string | **REQUIRED** | The namespace where the value |
| | | | should be inserted. |^
| `key` | string \| [string] | **REQUIRED** | The key indicating the field or fields |
| | | | where the value should be inserted. |^
| `value` | any | **REQUIRED** | The value to insert in the database. May |
| | | | be any valid JSON type. |^
///
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.post_item",
"params": {
"namespace": "{namespace}",
"key": "{key}",
"value": 100
},
"id": 4654
}
```
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"namespace": "test",
"key": "settings.some_count",
"value": 9001
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ----------- | :----------------: | ------------------------------------------- |
| `namespace` | string | The namespace where the value was inserted. |
| `key` | string \| [string] | The key indicating the field or fields |
| | | where the value was inserted. |^
| `value` | any | The value inserted into the database. May |
| | | be any valid JSON type. |^
///
## Delete Database Item
Deletes an item from a `namespace` at the specified `key`. If the key does not
exist in the namespace an error will be returned. If the deleted item results
in an empty namespace, the namespace will be removed from the database.
```{.http .apirequest title="HTTP Request"}
DELETE /server/database/item?namespace={namespace}&key={key}
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.delete_item",
"params": {
"namespace": "{namespace}",
"key": "{key}"
},
"id": 4654
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ----------- | :----------------: | ------------ | -------------------------------------- |
| `namespace` | string | **REQUIRED** | The namespace where the item should be |
| | | | should be removed. |^
| `key` | string \| [string] | **REQUIRED** | The key indicating the field or fields |
| | | | where the item should be removed. |^
///
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"namespace": "test",
"key": "settings.some_count",
"value": 9001
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ----------- | :----------------: | ------------------------------------------ |
| `namespace` | string | The namespace containing the item removed. |
| `key` | string \| [string] | The key indicating the field or fields |
| | | where the item was removed. |^
| `value` | any | The of the item at the removed field. May |
| | | be any valid JSON type. |^
///
## Compact Database
Compacts and defragments the the sqlite database using the `VACUUM` command.
This endpoint cannot be requested when Klipper is printing.
```{.http .apirequest title="HTTP Request"}
POST /server/database/compact
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.compact",
"id": 4654
}
```
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"previous_size": 139264,
"new_size": 122880
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| --------------- | :--: | -------------------------------------------------- |
| `previous_size` | int | Size in bytes of the database prior to compaction. |
| `new_size` | int | Size in bytes of the database after compaction. |
///
## Backup Database
Creates a backup of the current database. The backup will be
created in the `<data_path>/backup/database/<filename>`.
This API cannot be requested when Klipper is printing.
```{.http .apirequest title="HTTP Request"}
POST /server/database/backup
Content-Type: application/json
{
"filename": "sql-db-backup.db"
}
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.post_backup",
"params": {
"filename": "sql-db-backup.db"
},
"id": 4654
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ---------- | :----: | -------------------------- | -------------------------- |
| `filename` | string | sqldb-backup-{timespec}.db | The file name of the saved |
| | | | backup file. |^
//// note
The `{timespec}` of the default `filename` is in the following format:
`<year><month><day>-<hour><minute><second>`
////
///
```{.json .apiresponse title="Example Response"}
{
"backup_path": "/home/test/printer_data/backup/database/sql-db-backup.db"
}
```
/// api-response-spec
open: True
| Field | Type | Description |
| ------------- | :----: | ------------------------------------------------------ |
| `backup_path` | string | The complete absolute path where the backup was saved. |
///
## Delete a backup
Deletes a previously backed up database.
```{.http .apirequest title="HTTP Request"}
DELETE /server/database/backup?filename=sql-db-backup.db
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.delete_backup",
"params": {
"filename": "sql-db-backup.db"
},
"id": 4654
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ---------- | :----: | ------------ | ---------------------------------------------- |
| `filename` | string | **REQUIRED** | The name of the backup file to delete. Must be |
| | | | a valid filename reported by the |^
| | | | [database list endpoint](#list-database-info). |^
///
```{.json .apiresponse title="Example Response"}
{
"backup_path": "/home/test/printer_data/backup/database/sql-db-backup.db"
}
```
/// api-response-spec
open: True
| Field | Type | Description |
| ------------- | :----: | -------------------------------------------------------- |
| `backup_path` | string | The complete absolute path where the backup was removed. |
///
## Restore Database
Restores a previously backed up sqlite database file. The backup
must be located at `<data_path>/backup/database/<filename>`. The
`<filename>` must be a valid filename reported in by the
[database list](#list-database-info) API.
This API cannot be requested when Klipper is printing.
/// Note
Moonraker will restart immediately after this request is processed.
///
```{.http .apirequest title="HTTP Request"}
POST /server/database/restore
Content-Type: application/json
{
"filename": "sql-db-backup.db"
}
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "server.database.restore",
"params": {
"filename": "sql-db-backup.db"
},
"id": 4654
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ---------- | :----: | ------------ | ----------------------------------------------- |
| `filename` | string | **REQUIRED** | The name of the backup file to restore. Must be |
| | | | a valid filename reported by the |^
| | | | [database list endpoint](#list-database-info). |^
///
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"restored_tables": [
"table_registry",
"namespace_store",
"authorized_users",
"job_history",
"job_totals"
],
"restored_namespaces": [
"database",
"fluidd",
"gcode_metadata",
"mainsail",
"moonraker",
"update_manager",
"webcams"
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| --------------------- | :------: | ------------------------------------------- |
| `restored_tables` | [string] | An array of table names that were recovered |
| | | after the restore operation. |^
| `restored_namespaces` | [string] | An array of namespaces that were recovered |
| | | after the restore operation. |^
///
## Debug endpoints
Below are a number of debug endpoints available when Moonraker has been
launched with [debug features enabled](../installation.md#command-line-usage).
Front ends should not rely on these endpoints in production releases, however
they may be useful during development. Developers writing extensions and/or
additions to Moonraker may also find these endpoints useful.
/// Warning
Debug endpoints may expose security vulnerabilities. They should only be
enabled by developers on secured machines.
///
### List Database Info (debug)
Debug version of the [List Database Info](#list-database-info) endpoint.
Returns all namespaces, including those exclusively reserved for Moonraker.
In addition all registered SQL tables are reported.
```{.http .apirequest title="HTTP Request"}
GET /debug/database/list
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "debug.database.list",
"id": 8694
}
```
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"namespaces": [
"gcode_metadata",
"webcams",
"update_manager",
"announcements",
"database",
"moonraker"
],
"backups": [
"sqldb-backup-20240513-134542.db",
"testbackup.db",
"testbackup2.db"
],
"tables": [
"job_history",
"job_totals",
"namespace_store",
"table_registry",
"authorized_users"
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ------------ | :------: | -------------------------------------------------------- |
| `namespaces` | [string] | An array of all namespaces registered with the database. |
| `backups` | [string] | An array of database backup filenames that have been |
| | | created. |^
| `tables` | [string] | An array of tables created within the database. |
///
### Get Database Item (debug)
Debug version of the [Get Database Item](#get-database-item) endpoint.
Keys within protected and forbidden namespaces may be read.
```http title="HTTP Request"
GET /debug/database/item?namespace={namespace}&key={key}
```
```json title="JSON-RPC Request"
{
"jsonrpc": "2.0",
"method": "debug.database.get_item",
"params": {
"namespace": "{namespace}",
"key": "{key}"
},
"id": 5644
}
```
See the [Get Database Item](#get-database-item) endpoint for the
`Parameter Specification`, `Example Response`, and `Response Specification`.
### Add Database Item (debug)
Debug version of the [Add Database Item](#add-database-item) endpoint.
Keys within protected and forbidden namespaces may be inserted.
/// Warning
Modifying protected namespaces outside of Moonraker can result in
broken functionality and is not supported for production environments.
Issues opened with reports/queries related to this endpoint will be
redirected to this documentation and closed.
///
```{.http .apirequest title="HTTP Request"}
POST /debug/database/item
Content-Type: application/json
{
"namespace": "my_client",
"key": "settings.some_count",
"value": 100
}
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "debug.database.post_item",
"params": {
"namespace": "{namespace}",
"key": "{key}",
"value": 100
},
"id": 4654
}
```
See the [Add Database Item](#add-database-item) endpoint for the
`Parameter Specification`, `Example Response`, and `Response Specification`.
### Delete Database Item (debug)
Debug version of [Delete Database Item](#delete-database-item). Keys within
protected and forbidden namespaces may be removed.
/// Warning
Modifying protected namespaces outside of Moonraker can result in
broken functionality and is not supported for production environments.
Issues opened with reports/queries related to this endpoint will be
redirected to this documentation and closed.
///
```{.http .apirequest title="HTTP Request"}
DELETE /debug/database/item?namespace={namespace}&key={key}
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "debug.database.delete_item",
"params": {
"namespace": "{namespace}",
"key": "{key}"
},
"id": 4654
}
```
See the [Delete Database Item](#delete-database-item) endpoint for the
`Parameter Specification`, `Example Response`, and `Response Specification`.
### Get Database Table
Requests all the contents of a specified table.
```{.http .apirequest title="HTTP Request"}
GET /debug/database/table?table=job_history
```
```{.json .apirequest title="JSON-RPC Request"}
{
"jsonrpc": "2.0",
"method": "debug.database.table",
"params": {
"table": "job_history"
},
"id": 4654
}
```
/// api-parameters
open: True
| Name | Type | Default | Description |
| ------- | :----: | ------------ | --------------------------------- |
| `table` | string | **REQUIRED** | The name of the table to request. |
///
Returns:
An object with the table's name and a list of all rows contained
within the table. The `rowid` will always be included for each
row, however it may be represented by an alias. In the example
below the alias for `rowid` is `job_id`.
/// collapse-code
```{.json .apiresponse title="Example Response"}
{
"table_name": "job_history",
"rows": [
{
"job_id": 1,
"user": "No User",
"filename": "active_test.gcode",
"status": "completed",
"start_time": 1690749153.2661753,
"end_time": 1690749173.076986,
"print_duration": 0.0,
"total_duration": 19.975574419135228,
"filament_used": 0.0,
"metadata": {
"size": 211,
"modified": 1635771217.0,
"uuid": "627371e0-faa5-4ced-8bb4-7017d29226fa",
"slicer": "Unknown",
"gcode_start_byte": 8,
"gcode_end_byte": 211
},
"auxiliary_data": [],
"instance_id": "default"
},
{
"job_id": 2,
"user": "No User",
"filename": "active_test.gcode",
"status": "completed",
"start_time": 1701262034.9242446,
"end_time": 1701262054.7332363,
"print_duration": 0.0,
"total_duration": 19.990913168992847,
"filament_used": 0.0,
"metadata": {
"size": 211,
"modified": 1635771217.0,
"uuid": "627371e0-faa5-4ced-8bb4-7017d29226fa",
"slicer": "Unknown",
"gcode_start_byte": 8,
"gcode_end_byte": 211
},
"auxiliary_data": {
"spool_ids": [
2
]
},
"instance_id": "default"
}
]
}
```
///
/// api-response-spec
open: True
| Field | Type | Description |
| ------------ | :------: | -------------------------------------------------- |
| `table_name` | string | The name of the table requested. |
| `rows` | [object] | An array of row objects. The fields for each |
| | | object are columns defined by the table schema. |^
| | | The `rowid` will always be included for each row, |^
| | | however it may be represented by an alias. In the |^
| | | example above, `job_id` is an alias for `rowid`. |^
///
Reference in New Issue View Git Blame Copy Permalink