sql.sqlite.backup

import sql.sqlite.backup

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.sqlite.backup.* needs import sql.sqlite.backup.

Copying a live SQLite database without stopping it.

Copying the file with the filesystem is only safe when nothing is writing, which for a running application is never guaranteed. SQLite’s backup interface copies page by page and notices when the source changes underneath, restarting the copy rather than producing a file that is half of one state and half of another.

db.native().backup_to('./snapshot.db')

That copies everything in one call. For a large database where the pause matters, Backup copies in steps so other work can happen in between.

Constants

DEFAULT_PAGES

sql.sqlite.backup.DEFAULT_PAGES = 256

How many pages a step copies when no size is given.

Classes

Backup

class sql.sqlite.Backup

A copy in progress between two connections.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.sqlite.Backup(handle)

Parameters

• ptr — handle The native backup handle.

Backup.step()

sql.sqlite.Backup.step(pages) -> string

Copies up to pages pages.

Parameters

• pages (number|nil) — How many, or nil for DEFAULT_PAGES. A negative number copies everything remaining.

Returns string — 'done' when the copy is complete, 'ok' when more remains, and 'busy' or 'locked' when the source moved and the step should be tried again.

Backup.remaining()

sql.sqlite.Backup.remaining() -> number

Pages still to copy, as of the last step.

Returns number

Backup.total()

sql.sqlite.Backup.total() -> number

Pages in the source, as of the last step.

Returns number

Backup.progress()

sql.sqlite.Backup.progress() -> number

How much of the copy is done, from 0 to 1.

Returns number

Backup.run()

sql.sqlite.Backup.run(pages, attempts)

Runs the copy to completion, retrying the steps the source interrupts.

Parameters

• pages (number|nil) — How many pages per step.
• attempts (number|nil) — How many times to retry a busy step before giving up. 100 when nil.

Raises SqlError if the source stays busy for that many attempts.

Backup.close()

sql.sqlite.Backup.close()

Ends the copy. Safe to call more than once, and legitimate on an unfinished copy, which abandons it and leaves the destination as it was.

Backup.is_closed()

sql.sqlite.Backup.is_closed() -> bool

Whether this backup has finished or been abandoned.

Returns bool

Backup.to_string()

sql.sqlite.Backup.to_string()

2026, Richard Ore and Zuri contributors