diff --git a/docs/api/backup.rst b/docs/api/backup.rst new file mode 100644 index 0000000..bf79481 --- /dev/null +++ b/docs/api/backup.rst @@ -0,0 +1,68 @@ +Backup and Restore +****************** + +BackupEngine +============ + +.. py:class:: rocksdb.BackupEngine + + .. py:method:: __init__(backup_dir) + + Creates a object to manage backup of a single database. + + :param unicode backup_dir: Where to keep the backup files. + Has to be different than db.db_name. + For example db.db_name + '/backups'. + + .. py:method:: create_backup(db, flush_before_backup=False) + + Triggers the creation of a backup. + + :param db: Database object to backup. + :type db: :py:class:`rocksdb.DB` + + :param bool flush_before_backup: If ``True`` the current memtable is flushed. + + .. py:method:: restore_backup(backup_id, db_dir, wal_dir) + + Restores the backup from the given id. + + :param int backup_id: id of the backup to restore. + :param unicode db_dir: Target directory to restore backup. + :param unicode wal_dir: Target directory to restore backuped WAL files. + + .. py:method:: restore_latest_backup(db_dir, wal_dir) + + Restores the latest backup. + + :param unicode db_dir: see :py:meth:`restore_backup` + :param unicode wal_dir: see :py:meth:`restore_backup` + + .. py:method:: stop_backup() + + Can be called from another thread to stop the current backup process. + + .. py:method:: purge_old_backups(num_backups_to_keep) + + Deletes all backups (oldest first) until "num_backups_to_keep" are left. + + :param int num_backups_to_keep: Number of backupfiles to keep. + + .. py:method:: delete_backup(backup_id) + + :param int backup_id: Delete the backup with the given id. + + .. py:method:: get_backup_info() + + Returns infomration about all backups. + + It returns a list of dict's where each dict as the following keys. + + ``backup_id`` + (int): id of this backup. + + ``timestamp`` + (int): Seconds since epoch, when the backup was created. + + ``size`` + (int): Size in bytes of the backup. diff --git a/docs/api/index.rst b/docs/api/index.rst index 8d13b20..e06dc63 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -8,3 +8,4 @@ Python driver for RocksDB Options Database Interfaces + Backup diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 2e471f4..31d2ba2 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -241,3 +241,32 @@ So always the first 5 bytes are used as the prefix :: # prints {b'00002.z': b'z', b'00002.y': b'y', b'00002.x': b'x'} print dict(it) + + +Backup And Restore +================== + +Backup and Restore is done with a separate :py:class:`rocksdb.BackupEngine` object. + +A backup can only be created on a living database object :: + + import rocksdb + + db = rocksdb.DB("test.db", rocksdb.Options(create_if_missing=True)) + db.put(b'a', b'v1') + db.put(b'b', b'v2') + db.put(b'c', b'v3') + +Backup is created like this. +You can choose any path for the backup destination except the db path itself. +If ``flush_before_backup`` is ``True`` the current memtable is flushed to disk +before backup :: + + backup = rocksdb.BackupEngine("test.db/backups") + backup.create_backup(db, flush_before_backup=True) + +Restore is done like this. +The two arguments are the db_dir and wal_dir, which are mostly the same :: + + backup = rocksdb.BackupEngine("test.db/backups") + backup.restore_latest_backup("test.db", "test.db")