LuaSQLite3

Check-in [80be7a8591]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update wiki doc for new Online Backup API support.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 80be7a8591b4eec7e0f3bfeeb71cd2d02b3d1190
User & Date: e 2016-11-03 21:20:51
Context
2016-11-03
21:41
Handle backup_init returning NULL, and add unit test for it. check-in: 3a1789e967 user: e tags: trunk
21:20
Update wiki doc for new Online Backup API support. check-in: 80be7a8591 user: e tags: trunk
16:13
Add GC test for Online Backup API. check-in: 1c355fc530 user: e tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to doc/lsqlite3.wiki.

13
14
15
16
17
18
19
20

21
22
23
24
25
26
27
..
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100









101
102
103
104
105
106
107
...
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
...
199
200
201
202
203
204
205



















206
207
208
209
210
211
212
...
968
969
970
971
972
973
974





























































975
976
977
978
979
980
981
...
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
	<li><a href="#reference">REFERENCE</a></li>
	<li><a href="#sqlite3_functions">SQLite3 functions</a></li>
	<ul>

		<li><a href="#sqlite3_complete">sqlite3.complete</a></li>
        <li><a href="#sqlite3_lversion">sqlite3.lversion</a></li>
		<li><a href="#sqlite3_open">sqlite3.open</a></li>
		<li><a href="#sqlite3_open_memory">sqlite3.open_memory</a></li>

		<li><a href="#sqlite3_temp_directory">sqlite3.temp_directory</a></li>
		<li><a href="#sqlite3_version">sqlite3.version</a></li>
	</ul>

	<li><a href="#database_methods">Database methods</a></li>
	<ul>

................................................................................
		<li><a href="#stmt_nrows">stmt:nrows</a></li>
		<li><a href="#stmt_reset">stmt:reset</a></li>
		<li><a href="#stmt_rows">stmt:rows</a></li>
		<li><a href="#stmt_step">stmt:step</a></li>
        <li><a href="#stmt_urows">stmt:urows</a></li>
	</ul>

	<li><a href="#methods_for_callback_contexts">Methods for callback contexts</a></li>
	<ul>

		<li><a href="#context_aggregate_count">context:aggregate_count</a></li>
		<li><a href="#context_get_aggregate_data">context:get_aggregate_data</a></li>
		<li><a href="#context_set_aggregate_data">context:set_aggregate_data</a></li>
		<li><a href="#context_result">context:result</a></li>
		<li><a href="#context_result_null">context:result_null</a></li>
		<li><a href="#context_result_number">context:result_number</a></li>
		<li><a href="#context_result_int">context:result_int</a></li>
		<li><a href="#context_result_text">context:result_text</a></li>
		<li><a href="#context_result_blob">context:result_blob</a></li>
		<li><a href="#context_result_error">context:result_error</a></li>
		<li><a href="#context_user_data">context:user_data</a></li>
	</ul>










	<li><a href="#numerical_error_and_result_codes">Numerical error and result codes</a></li>
	<li><a href="#version">VERSION</a></li>
	<li><a href="#credits">CREDITS</a></li>
	<li><a href="#license">LICENSE</a></li>
</ul>

................................................................................
<hr />
<h1><a name="verification_tests">VERIFICATION TESTS</a></h1>
<p>The distribution contains a <em>tests</em> directory with some units tests using 
an enhanced version of Michael Roth's <code>lunit</code> called <code>lunitx</code>. Some of the 
tests were also derived from Michael's <strong>lua-sqlite3</strong> module, and more unit tests 
added by Doug Currie. Get <code>lunitx</code> using Luarocks.</p>
<p>The distribution also contains some functional tests by Tiago.</p>
<p>This version of <code>lsqlite3</code> was tested with SQLite 3.8.7.4.</p>
<p>
</p>
<hr />
<h1><a name="reference">REFERENCE</a></h1>
<p>
</p>
<hr />
................................................................................
        sqlite3.open_memory()</pre>
<p>Opens an SQLite database <strong>in memory</strong> and returns its handle as
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.)</p>
<p>
</p>



















<h2><a name="sqlite3_temp_directory">sqlite3.temp_directory</a></h2>
<pre>
        sqlite3.temp_directory([temp])</pre>
<p>Sets or queries the directory used by SQLite for temporary files. If
string <code>temp</code> is a directory name or nil, the temporary directory is 
set accordingly and the old value is returned. If <code>temp</code> is missing, 
the function simply returns the current temporary directory.</p>
................................................................................
<h2><a name="context_user_data">context:user_data</a></h2>
<pre>
        context:user_data()</pre>
<p>Returns the userdata parameter given in the call to install the callback
function (see <a href="#db_create_aggregate"><code>db:create_aggregate()</code></a> and 
<a href="#db_create_function"><code>db:create_function()</code></a> for details).</p>
<p>





























































</p>
<hr />
<h1><a name="numerical_error_and_result_codes">Numerical error and result codes</a></h1>
<p>The following constants are defined by module sqlite3:</p>
<pre>
        OK: 0          ERROR: 1       INTERNAL: 2    PERM: 3        ABORT: 4
        BUSY: 5        LOCKED: 6      NOMEM: 7       READONLY: 8    INTERRUPT: 9
................................................................................
</pre>
<p>For details about their exact meaning please see the <strong>SQLite3
documentation</strong> <a href="http://www.sqlite.org/">http://www.sqlite.org/</a>.</p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>This is <code>lsqlite3</code> version &quot;0.9.3&quot;, also tagged as <code>fsl_9w</code>.</p>
<p>
</p>
<hr />
<h1><a name="credits">CREDITS</a></h1>
<p><code>lsqlite3</code> was developed by Tiago Dionizio and Doug Currie with 
contributions from Thomas Lauer and Michael Roth.</p>
<p>This documentation is based on the &quot;(very) preliminary&quot; documents
for the Idle-SQLite3 database module. Thanks to Thomas Lauer for
making it available.</p>
<p>
</p>
<hr />
<h1><a name="license">LICENSE</a></h1>
<pre>
    /************************************************************************
    * lsqlite3                                                              *
    * Copyright (C) 2002-2015 Tiago Dionizio, Doug Currie                   *
    * All rights reserved.                                                  *
    * Author    : Tiago Dionizio &lt;tiago.dionizio@ist.utl.pt&gt;                *
    * Author    : Doug Currie &lt;doug.currie@alum.mit.edu&gt;                    *
    * Library   : lsqlite3 - a 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       *
    * &quot;Software&quot;), to deal in the Software without restriction, including   *
    * without limitation the rights to use, copy, modify, merge, publish,   *
    * distribute, sublicense, and/or sell copies of the Software, and to    *
    * permit persons to whom the Software is furnished to do so, subject to *







|
>







 







|
|

|
|
|
|
|
|
|
|
|
|
|
|
>
>
>
>
>
>
>
>
>







 







|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|





|










|



|







13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
..
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
...
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
...
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
...
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
....
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
	<li><a href="#reference">REFERENCE</a></li>
	<li><a href="#sqlite3_functions">SQLite3 functions</a></li>
	<ul>

		<li><a href="#sqlite3_complete">sqlite3.complete</a></li>
        <li><a href="#sqlite3_lversion">sqlite3.lversion</a></li>
		<li><a href="#sqlite3_open">sqlite3.open</a></li>
        <li><a href="#sqlite3_open_memory">sqlite3.open_memory</a></li>
        <li><a href="#sqlite3_backup_init">sqlite3.backup_init</a></li>
		<li><a href="#sqlite3_temp_directory">sqlite3.temp_directory</a></li>
		<li><a href="#sqlite3_version">sqlite3.version</a></li>
	</ul>

	<li><a href="#database_methods">Database methods</a></li>
	<ul>

................................................................................
		<li><a href="#stmt_nrows">stmt:nrows</a></li>
		<li><a href="#stmt_reset">stmt:reset</a></li>
		<li><a href="#stmt_rows">stmt:rows</a></li>
		<li><a href="#stmt_step">stmt:step</a></li>
        <li><a href="#stmt_urows">stmt:urows</a></li>
	</ul>

    <li><a href="#methods_for_callback_contexts">Methods for callback contexts</a></li>
    <ul>

        <li><a href="#context_aggregate_count">context:aggregate_count</a></li>
        <li><a href="#context_get_aggregate_data">context:get_aggregate_data</a></li>
        <li><a href="#context_set_aggregate_data">context:set_aggregate_data</a></li>
        <li><a href="#context_result">context:result</a></li>
        <li><a href="#context_result_null">context:result_null</a></li>
        <li><a href="#context_result_number">context:result_number</a></li>
        <li><a href="#context_result_int">context:result_int</a></li>
        <li><a href="#context_result_text">context:result_text</a></li>
        <li><a href="#context_result_blob">context:result_blob</a></li>
        <li><a href="#context_result_error">context:result_error</a></li>
        <li><a href="#context_user_data">context:user_data</a></li>
    </ul>

    <li><a href="#methods_for_online_backup">Methods for Online Backup</a></li>
    <ul>

        <li><a href="#bu_step">backup:step</a></li>
        <li><a href="#bu_remaining">backup:remaining</a></li>
        <li><a href="#bu_pagecount">backup:pagecount</a></li>
        <li><a href="#bu_finish">backup:finish</a></li>
    </ul>

	<li><a href="#numerical_error_and_result_codes">Numerical error and result codes</a></li>
	<li><a href="#version">VERSION</a></li>
	<li><a href="#credits">CREDITS</a></li>
	<li><a href="#license">LICENSE</a></li>
</ul>

................................................................................
<hr />
<h1><a name="verification_tests">VERIFICATION TESTS</a></h1>
<p>The distribution contains a <em>tests</em> directory with some units tests using 
an enhanced version of Michael Roth's <code>lunit</code> called <code>lunitx</code>. Some of the 
tests were also derived from Michael's <strong>lua-sqlite3</strong> module, and more unit tests 
added by Doug Currie. Get <code>lunitx</code> using Luarocks.</p>
<p>The distribution also contains some functional tests by Tiago.</p>
<p>This version of <code>lsqlite3</code> was tested with SQLite 3.11.0 and 3.15.0.</p>
<p>
</p>
<hr />
<h1><a name="reference">REFERENCE</a></h1>
<p>
</p>
<hr />
................................................................................
        sqlite3.open_memory()</pre>
<p>Opens an SQLite database <strong>in memory</strong> and returns its handle as
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.)</p>
<p>
</p>

<h2><a name="sqlite3_backup_init">sqlite3.backup_init</a></h2>
<pre>
        sqlite3.backup_init(target_db, target_name, source_db, source_name)</pre>
<p>Starts an SQLite Online Backup from <code>source_db</code> to <code>target_db</code> and 
returns its handle as userdata. The <code>source_db</code> and <code>target_db</code> are
open databases; they may be in-memory or file-based databases. The <code>target_name</code> and
<code>source_name</code> 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.</p>
<p>The source and target databases must be different, or else the init call will fail with an 
error. A call to <code>sqlite3.backup_init</code> will fail, returning NULL, if there is already 
a read or read-write transaction open on the target database.
</p>
<p>If an error occurs within <code>sqlite3.backup_init</code>, then NULL is returned, and an 
error code and error message are stored in <code>target_db</code>. The error code and message 
for the failed call can be retrieved using the <a href="#db_errcode"><code>db:errcode</code></a>, 
or <a href="#db_errmsg"><code>db:errmsg</code></a>.</p>
<p>
</p>
<h2><a name="sqlite3_temp_directory">sqlite3.temp_directory</a></h2>
<pre>
        sqlite3.temp_directory([temp])</pre>
<p>Sets or queries the directory used by SQLite for temporary files. If
string <code>temp</code> is a directory name or nil, the temporary directory is 
set accordingly and the old value is returned. If <code>temp</code> is missing, 
the function simply returns the current temporary directory.</p>
................................................................................
<h2><a name="context_user_data">context:user_data</a></h2>
<pre>
        context:user_data()</pre>
<p>Returns the userdata parameter given in the call to install the callback
function (see <a href="#db_create_aggregate"><code>db:create_aggregate()</code></a> and 
<a href="#db_create_function"><code>db:create_function()</code></a> for details).</p>
<p>
</p>
<hr />
<h1><a name="methods_for_online_backup">Methods for Online Backup</a></h1>
<p>A backup userdata is created using <code>backup = </code>
<a href="#sqlite3_backup_init"><code>sqlite3.backup_init(...)</code></a>. It is then 
used to step the backup, or inquire about its progress.</p>
<p>
</p>
<h2><a name="bu_step">backup:step</a></h2>
<pre>
        backup:step(nPages)</pre>
<p>Returns the status of the backup after stepping <code>nPages</code>. It is called one or more 
times to transfer the data between the two databases.</p>
<p><code>backup:step(nPages)</code> will copy up to <code>nPages</code> pages between the 
source and destination databases specified by <code>backup</code> userdata. 
If <code>nPages</code> is negative, all remaining source pages are copied. 
</p>
<p> If <code>backup:step(nPages)</code> successfully copies <code>nPages</code> pages and there 
are still more pages to be copied, then the function returns <code>sqlite3.OK</code>. 
If <code>backup:step(nPages)</code> successfully finishes copying all pages from source to 
destination, then it returns <code>sqlite3.DONE</code>. If an error occurs during the step, then 
an error code is returned. such as <code>sqlite3.READONLY</code>, <code>sqlite3.NOMEM</code>, 
<code>sqlite3.BUSY</code>, <code>sqlite3.LOCKED</code>, or an <code>sqlite3.IOERR_XXX</code> 
extended error code.
</p>
<p>
</p>
<h2><a name="bu_remaining">backup:remaining</a></h2>
<pre>
        backup:remaining()</pre>
<p>Returns the number of pages still to be backed up at the conclusion of the most recent step.
</p>
<p>
</p>
<h2><a name="bu_pagecount">backup:pagecount</a></h2>
<pre>
        backup:pagecount()</pre>
<p>Returns the total number of pages in the source database at the conclusion of the most recent
step.</p>
<p>
</p>
<h2><a name="bu_finish">backup:finish</a></h2>
<pre>
        backup:finish()</pre>
<p>When <code>backup:step(nPages)</code> has returned <code>sqlite3.DONE</code>, or when the 
application wishes to abandon the backup operation, the application should destroy the backup 
by calling <code>backup:finish()</code>. This releases all resources associated with the backup. 
If <code>backup:step(nPages)</code> has not yet returned <code>sqlite3.DONE</code>, 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.
</p>
<p>The value returned by <code>backup:finish()</code> is <code>sqlite3.OK</code> 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 <code>backup:finish()</code> 
returns the corresponding error code.
</p>
<p>A return of <code>sqlite3.BUSY</code> or <code>sqlite3.LOCKED</code> from 
<code>backup:step(nPages)</code> is not a permanent error and does not affect the return value 
of <code>backup:finish()</code>.
</p>
<p>
</p>
<hr />
<h1><a name="numerical_error_and_result_codes">Numerical error and result codes</a></h1>
<p>The following constants are defined by module sqlite3:</p>
<pre>
        OK: 0          ERROR: 1       INTERNAL: 2    PERM: 3        ABORT: 4
        BUSY: 5        LOCKED: 6      NOMEM: 7       READONLY: 8    INTERRUPT: 9
................................................................................
</pre>
<p>For details about their exact meaning please see the <strong>SQLite3
documentation</strong> <a href="http://www.sqlite.org/">http://www.sqlite.org/</a>.</p>
<p>
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
<p>This is <code>lsqlite3</code> version &quot;0.9.4&quot;, also tagged as <code>fsl_9x</code>.</p>
<p>
</p>
<hr />
<h1><a name="credits">CREDITS</a></h1>
<p><code>lsqlite3</code> was developed by Tiago Dionizio and Doug Currie with 
contributions from Thomas Lauer, Michael Roth, and Wolfgang Oertl.</p>
<p>This documentation is based on the &quot;(very) preliminary&quot; documents
for the Idle-SQLite3 database module. Thanks to Thomas Lauer for
making it available.</p>
<p>
</p>
<hr />
<h1><a name="license">LICENSE</a></h1>
<pre>
    /************************************************************************
    * lsqlite3                                                              *
    * Copyright (C) 2002-2016 Tiago Dionizio, Doug Currie                   *
    * All rights reserved.                                                  *
    * Author    : Tiago Dionizio &lt;tiago.dionizio@ist.utl.pt&gt;                *
    * Author    : Doug Currie &lt;doug.currie@alum.mit.edu&gt;                    *
    * 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       *
    * &quot;Software&quot;), to deal in the Software without restriction, including   *
    * without limitation the rights to use, copy, modify, merge, publish,   *
    * distribute, sublicense, and/or sell copies of the Software, and to    *
    * permit persons to whom the Software is furnished to do so, subject to *