diff options
author | Emanuele Gaifas <lelegaifax@gmail.com> | 2018-03-10 22:08:31 (GMT) |
---|---|---|
committer | Berker Peksag <berker.peksag@gmail.com> | 2018-03-10 22:08:31 (GMT) |
commit | d7aed4102d2a40c74553240c7f03585624d27aea (patch) | |
tree | f65be332675189f8a73fbfdf543c28a23f96a795 /Doc/library | |
parent | c10b288f345aaef66d2c844924b9a576f9ea4f8b (diff) | |
download | cpython-d7aed4102d2a40c74553240c7f03585624d27aea.zip cpython-d7aed4102d2a40c74553240c7f03585624d27aea.tar.gz cpython-d7aed4102d2a40c74553240c7f03585624d27aea.tar.bz2 |
bpo-27645: Add support for native backup facility of SQLite (GH-4238)
Diffstat (limited to 'Doc/library')
-rw-r--r-- | Doc/library/sqlite3.rst | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index e7676a9..d7eaea6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -532,6 +532,56 @@ Connection Objects f.write('%s\n' % line) + .. method:: backup(target, *, pages=0, progress=None, name="main", sleep=0.250) + + This method makes a backup of a SQLite database even while it's being accessed + by other clients, or concurrently by the same connection. The copy will be + written into the mandatory argument *target*, that must be another + :class:`Connection` instance. + + By default, or when *pages* is either ``0`` or a negative integer, the entire + database is copied in a single step; otherwise the method performs a loop + copying up to *pages* pages at a time. + + If *progress* is specified, it must either be ``None`` or a callable object that + will be executed at each iteration with three integer arguments, respectively + the *status* of the last iteration, the *remaining* number of pages still to be + copied and the *total* number of pages. + + The *name* argument specifies the database name that will be copied: it must be + a string containing either ``"main"``, the default, to indicate the main + database, ``"temp"`` to indicate the temporary database or the name specified + after the ``AS`` keyword in an ``ATTACH DATABASE`` statement for an attached + database. + + The *sleep* argument specifies the number of seconds to sleep by between + successive attempts to backup remaining pages, can be specified either as an + integer or a floating point value. + + Example 1, copy an existing database into another:: + + import sqlite3 + + def progress(status, remaining, total): + print(f'Copied {total-remaining} of {total} pages...') + + con = sqlite3.connect('existing_db.db') + with sqlite3.connect('backup.db') as bck: + con.backup(bck, pages=1, progress=progress) + + Example 2, copy an existing database into a transient copy:: + + import sqlite3 + + source = sqlite3.connect('existing_db.db') + dest = sqlite3.connect(':memory:') + source.backup(dest) + + Availability: SQLite 3.6.11 or higher + + .. versionadded:: 3.7 + + .. _sqlite3-cursor-objects: Cursor Objects |