Add documentation for backup engine

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.

docs/api/index.rst

@@ -8,3 +8,4 @@ Python driver for RocksDB
     Options <options>
     Database <database>
     Interfaces <interfaces>
+    Backup <backup>

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")