1
.. Automatically generated by code2rst.py
2
code2rst.py src/backup.c doc/backup.rst
3
Edit src/backup.c not this file!
5
.. currentmodule:: apsw
12
A backup object encapsulates copying one database to another. You
13
call :meth:`Connection.backup` on the destination database to get the
14
backup object. Call :meth:`~backup.step` to copy some pages
15
repeatedly dealing with errors as appropriate. Finally
16
:meth:`~backup.finish` cleans up committing or rolling back and
19
Here is an example usage using the **with** statement to ensure
20
:meth:`~backup.finish` is called::
22
# copies source.main into db
23
with db.backup("main", source, "main") as b:
26
print b.remaining, b.pagecount, "\r",
28
If you are not using **with** then you'll need to ensure
29
:meth:`~backup.finish` is called::
31
# copies source.main into db
32
b=db.backup("main", source, "main")
36
print b.remaining, b.pagecount, "\r",
43
The database is copied page by page. This means that there is not a
44
round trip via SQL. All pages are copied including free ones.
46
The destination database is locked during the copy. You will get a
47
:exc:`ThreadingViolationError` if you attempt to use it.
54
You create a backup instance by calling :meth:`Connection.backup`.
56
.. method:: backup.__enter__() -> self
58
You can use the backup object as a `context manager
59
<http://docs.python.org/reference/datamodel.html#with-statement-context-managers>`_
60
as defined in :pep:`0343`. The :meth:`~backup.__exit__` method ensures that backup
61
is :meth:`finished <backup.finish>`.
63
.. method:: backup.__exit__() -> False
65
Implements context manager in conjunction with :meth:`~backup.__enter__` ensuring
66
that the copy is :meth:`finished <backup.finish>`.
68
.. method:: backup.close([force=False])
70
Does the same thing as :meth:`~backup.finish`. This extra api is
71
provided to give the same api as other APSW objects such as
72
:meth:`Connection.close`, :meth:`blob.close` and
73
:meth:`Cursor.close`. It is safe to call this method multiple
76
:param force: If true then any exceptions are ignored.
78
.. attribute:: backup.done
80
A boolean that is True if the copy completed in the last call to :meth:`~backup.step`.
82
.. index:: sqlite3_backup_finish
84
.. method:: backup.finish()
86
Completes the copy process. If all pages have been copied then the
87
transaction is committed on the destination database, otherwise it
88
is rolled back. This method must be called for your backup to take
89
effect. The backup object will always be finished even if there is
90
an exception. It is safe to call this method multiple times.
92
Calls: :sqliteapi:`sqlite3_backup_finish <backup_finish>`
94
.. index:: sqlite3_backup_pagecount
96
.. attribute:: backup.pagecount
98
Read only. How many pages were in the source database after the last
99
step. If you haven't called :meth:`~backup.step` or the backup
100
object has been :meth:`finished <backup.finish>` then zero is
103
Calls: :sqliteapi:`sqlite3_backup_pagecount <backup_finish>`
105
.. index:: sqlite3_backup_remaining
107
.. attribute:: backup.remaining
109
Read only. How many pages were remaining to be copied after the last
110
step. If you haven't called :meth:`~backup.step` or the backup
111
object has been :meth:`finished <backup.finish>` then zero is
114
Calls: :sqliteapi:`sqlite3_backup_remaining <backup_finish>`
116
.. index:: sqlite3_backup_step
118
.. method:: backup.step([npages=All]) -> bool
120
Copies *npages* pages from the source to destination database. The source database is locked during the copy so
121
using smaller values allows other access to the source database. The destination database is always locked until the
122
backup object is :meth:`finished <backup.finish>`.
124
:param npages: How many pages to copy. If the parameter is omitted
125
or negative then all remaining pages are copied. The default page
126
size is 1024 bytes (1kb) which can be changed before database
127
creation using a `pragma
128
<http://www.sqlite.org/pragma.html#modify>`_.
130
This method may throw a :exc:`BusyError` or :exc:`LockedError` if
131
unable to lock the source database. You can catch those and try
134
:returns: True if this copied the last remaining outstanding pages, else false. This is the same value as :attr:`~backup.done`
136
Calls: :sqliteapi:`sqlite3_backup_step <backup_finish>`
added
removed
doc/_sources/backup.txt
