Schedule a new backup.
Backups are created using tar and gzip. Once a backup is made, the .tar.gz backup
file can be used to recover ThingsDB, or can be used to load the ThingsDB into another node.
The result value is a backup Id. This Id can be used by backup_info(..) for details
about the backup schedule job, or can be used to delete the backup schedule.
If Google Cloud Storage is configured then it is possible to create backups directly into Google Cloud Storage.
To use Google Cloud Storage simply create the backup with a file_template argument like gs://my_bucket/my_backup_{DATE}{TIME}.tar.gz.
Restoring from a backup file can be done with either the restore(..) function or by starting the node from a backup file. See the example recovery section below on how to start a node from a backup file.
Before v0.9.5 it was not possible to schedule a backup when having just a single node. The underlying reason for this restriction used to be that a single node will not enter away mode which is required for creating a backup. A scheduled backup is now the exception for a single to enter away mode.
This function does not generate a change.
new_backup(file_template, [start_ts, [repeat, [max_files]]])
| Argument | Type | Description |
|---|---|---|
file_template |
str | Backup schedule file template. See file-template for more information. |
start_ts |
nil/datetime/timeval (optional) | Start date/time of the backup. If no start_ts is given, the backup starts as soon as possible. |
repeat |
int (optional) | Repeat the backup schedule every repeat seconds. If no repeat value is set, the backup job will run only once. |
max_files |
int (optional) | As soon as max_files successful backups are created, the first backup (including the file on disk) will be removed. Default is 7. |
Backup file templates should end with .tar.gz. They may contain some template variable
for creating unique file names.
| Variable | description |
|---|---|
{DATE} |
Current date using format %Y%m%d, for example 20191209. |
{TIME} |
Current time using format %H%M%S, for example 165730. |
{CHANGE_ID} |
Last committed change Id, for example 123456. |
An example file-name could be /tmp/backup_{CHANGE_ID}.tar.gz.
Returns the backup Id for the scheduled backup.
Use new_backup to schedule a ThingsDB backup:
// Create a new backup immediately (because 2000-01-01 is in the past), then at 23:00 and repeat each day
new_backup('/var/backup/thingsdb_{DATE}{TIME}.tar.gz', datetime(2000, 1, 1), 24*3600);
Example result in JSON format:
0
There are two options to restore data from a ThingsDB backup file. One option is to use the restore(..) function and the other option is explained in the steps below:
# Unpack a backup file in some storage directory.
tar -xzf backup.tar.gz
# Start ThingsDB with the current path as storage path
THINGSDB_STORAGE_PATH=./ thingsdb --forget-nodes
Confirm with
yesso we can start with a single node
Warning: all nodes information will be lost!!
Type `yes` + ENTER if you really want to continue: yes
Done!