The distribution contains a tests directory with some units tests using
an enhanced version of Michael Roth's lunit called lunitx. Some of the
tests were also derived from Michael's lua-sqlite3 module, and more unit tests
added by Doug Currie. Get lunitx using Luarocks.
The distribution also contains some functional tests by Tiago.
-This version of lsqlite3 was tested with SQLite 3.8.7.4.
This version of lsqlite3 was tested with SQLite 3.11.0 and 3.15.0.
@@ -201,10 +211,29 @@ userdata. In case of an error, the function returns nil, an error code and an error message. (In-memory databases are volatile as they are never stored on disk.)
+ +
+ sqlite3.backup_init(target_db, target_name, source_db, source_name)+
Starts an SQLite Online Backup from source_db to target_db and
+returns its handle as userdata. The source_db and target_db are
+open databases; they may be in-memory or file-based databases. The target_name and
+source_name are "main" for the main database, "temp" for the temporary database, or
+the name specified after the AS keyword in an ATTACH statement for an attached database.
The source and target databases must be different, or else the init call will fail with an
+error. A call to sqlite3.backup_init will fail, returning NULL, if there is already
+a read or read-write transaction open on the target database.
+
If an error occurs within sqlite3.backup_init, then NULL is returned, and an
+error code and error message are stored in target_db. The error code and message
+for the failed call can be retrieved using the db:errcode,
+or db:errmsg.
+
sqlite3.temp_directory([temp])
Sets or queries the directory used by SQLite for temporary files. If
string temp is a directory name or nil, the temporary directory is
@@ -970,10 +999,71 @@
context:user_data()
Returns the userdata parameter given in the call to install the callback
function (see db:create_aggregate() and
db:create_function() for details).
+
+A backup userdata is created using backup =
+sqlite3.backup_init(...). It is then
+used to step the backup, or inquire about its progress.
+
++ backup:step(nPages)+
Returns the status of the backup after stepping nPages. It is called one or more
+times to transfer the data between the two databases.
backup:step(nPages) will copy up to nPages pages between the
+source and destination databases specified by backup userdata.
+If nPages is negative, all remaining source pages are copied.
+
If backup:step(nPages) successfully copies nPages pages and there
+are still more pages to be copied, then the function returns sqlite3.OK.
+If backup:step(nPages) successfully finishes copying all pages from source to
+destination, then it returns sqlite3.DONE. If an error occurs during the step, then
+an error code is returned. such as sqlite3.READONLY, sqlite3.NOMEM,
+sqlite3.BUSY, sqlite3.LOCKED, or an sqlite3.IOERR_XXX
+extended error code.
+
+
++ backup:remaining()+
Returns the number of pages still to be backed up at the conclusion of the most recent step. +
++
++ backup:pagecount()+
Returns the total number of pages in the source database at the conclusion of the most recent +step.
++
++ backup:finish()+
When backup:step(nPages) has returned sqlite3.DONE, or when the
+application wishes to abandon the backup operation, the application should destroy the backup
+by calling backup:finish(). This releases all resources associated with the backup.
+If backup:step(nPages) has not yet returned sqlite3.DONE, then any
+active write-transaction on the destination database is rolled back. After the call, the backup
+userdata corresponds to a completed backup, and should not be used.
+
The value returned by backup:finish() is sqlite3.OK if no errors
+occurred, regardless or whether or not the backup completed. If an out-of-memory condition or IO
+error occurred during any prior step on the same backup, then backup:finish()
+returns the corresponding error code.
+
A return of sqlite3.BUSY or sqlite3.LOCKED from
+backup:step(nPages) is not a permanent error and does not affect the return value
+of backup:finish().
+
The following constants are defined by module sqlite3:
@@ -999,17 +1089,17 @@ documentation http://www.sqlite.org/.
VERSION
-This is
+lsqlite3version "0.9.3", also tagged asfsl_9w.This is
lsqlite3version "0.9.4", also tagged asfsl_9x.
CREDITS
+contributions from Thomas Lauer, Michael Roth, and Wolfgang Oertl.
lsqlite3was developed by Tiago Dionizio and Doug Currie with -contributions from Thomas Lauer and Michael Roth.This documentation is based on the "(very) preliminary" documents for the Idle-SQLite3 database module. Thanks to Thomas Lauer for making it available.
@@ -1016,15 +1106,15 @@
LICENSE
/************************************************************************ * lsqlite3 * - * Copyright (C) 2002-2015 Tiago Dionizio, Doug Currie * + * Copyright (C) 2002-2016 Tiago Dionizio, Doug Currie * * All rights reserved. * * Author : Tiago Dionizio <tiago.dionizio@ist.utl.pt> * * Author : Doug Currie <doug.currie@alum.mit.edu> * - * Library : lsqlite3 - a SQLite 3 database binding for Lua 5 * + * Library : lsqlite3 - an SQLite 3 database binding for Lua 5 * * * * Permission is hereby granted, free of charge, to any person obtaining * * a copy of this software and associated documentation files (the * * "Software"), to deal in the Software without restriction, including * * without limitation the rights to use, copy, modify, merge, publish, *