zkk 2f184c317d 合并最新内容,适配开门检测机型
# Conflicts:
#	moonraker/components/file_manager/metadata.py   resolved by ada08d4574e13099a392bba4b3ebe34485807c0a version
2025-03-31 11:37:27 +08:00

774 lines
23 KiB
Markdown

# 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`. |^
///