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 Side-by-Side Diffs Ignore Whitespace Patch

Changes to doc/lsqlite3.wiki.

    13     13   	<li><a href="#reference">REFERENCE</a></li>
    14     14   	<li><a href="#sqlite3_functions">SQLite3 functions</a></li>
    15     15   	<ul>
    16     16   
    17     17   		<li><a href="#sqlite3_complete">sqlite3.complete</a></li>
    18     18           <li><a href="#sqlite3_lversion">sqlite3.lversion</a></li>
    19     19   		<li><a href="#sqlite3_open">sqlite3.open</a></li>
    20         -		<li><a href="#sqlite3_open_memory">sqlite3.open_memory</a></li>
           20  +        <li><a href="#sqlite3_open_memory">sqlite3.open_memory</a></li>
           21  +        <li><a href="#sqlite3_backup_init">sqlite3.backup_init</a></li>
    21     22   		<li><a href="#sqlite3_temp_directory">sqlite3.temp_directory</a></li>
    22     23   		<li><a href="#sqlite3_version">sqlite3.version</a></li>
    23     24   	</ul>
    24     25   
    25     26   	<li><a href="#database_methods">Database methods</a></li>
    26     27   	<ul>
    27     28   
................................................................................
    79     80   		<li><a href="#stmt_nrows">stmt:nrows</a></li>
    80     81   		<li><a href="#stmt_reset">stmt:reset</a></li>
    81     82   		<li><a href="#stmt_rows">stmt:rows</a></li>
    82     83   		<li><a href="#stmt_step">stmt:step</a></li>
    83     84           <li><a href="#stmt_urows">stmt:urows</a></li>
    84     85   	</ul>
    85     86   
    86         -	<li><a href="#methods_for_callback_contexts">Methods for callback contexts</a></li>
    87         -	<ul>
           87  +    <li><a href="#methods_for_callback_contexts">Methods for callback contexts</a></li>
           88  +    <ul>
           89  +
           90  +        <li><a href="#context_aggregate_count">context:aggregate_count</a></li>
           91  +        <li><a href="#context_get_aggregate_data">context:get_aggregate_data</a></li>
           92  +        <li><a href="#context_set_aggregate_data">context:set_aggregate_data</a></li>
           93  +        <li><a href="#context_result">context:result</a></li>
           94  +        <li><a href="#context_result_null">context:result_null</a></li>
           95  +        <li><a href="#context_result_number">context:result_number</a></li>
           96  +        <li><a href="#context_result_int">context:result_int</a></li>
           97  +        <li><a href="#context_result_text">context:result_text</a></li>
           98  +        <li><a href="#context_result_blob">context:result_blob</a></li>
           99  +        <li><a href="#context_result_error">context:result_error</a></li>
          100  +        <li><a href="#context_user_data">context:user_data</a></li>
          101  +    </ul>
          102  +
          103  +    <li><a href="#methods_for_online_backup">Methods for Online Backup</a></li>
          104  +    <ul>
    88    105   
    89         -		<li><a href="#context_aggregate_count">context:aggregate_count</a></li>
    90         -		<li><a href="#context_get_aggregate_data">context:get_aggregate_data</a></li>
    91         -		<li><a href="#context_set_aggregate_data">context:set_aggregate_data</a></li>
    92         -		<li><a href="#context_result">context:result</a></li>
    93         -		<li><a href="#context_result_null">context:result_null</a></li>
    94         -		<li><a href="#context_result_number">context:result_number</a></li>
    95         -		<li><a href="#context_result_int">context:result_int</a></li>
    96         -		<li><a href="#context_result_text">context:result_text</a></li>
    97         -		<li><a href="#context_result_blob">context:result_blob</a></li>
    98         -		<li><a href="#context_result_error">context:result_error</a></li>
    99         -		<li><a href="#context_user_data">context:user_data</a></li>
   100         -	</ul>
          106  +        <li><a href="#bu_step">backup:step</a></li>
          107  +        <li><a href="#bu_remaining">backup:remaining</a></li>
          108  +        <li><a href="#bu_pagecount">backup:pagecount</a></li>
          109  +        <li><a href="#bu_finish">backup:finish</a></li>
          110  +    </ul>
   101    111   
   102    112   	<li><a href="#numerical_error_and_result_codes">Numerical error and result codes</a></li>
   103    113   	<li><a href="#version">VERSION</a></li>
   104    114   	<li><a href="#credits">CREDITS</a></li>
   105    115   	<li><a href="#license">LICENSE</a></li>
   106    116   </ul>
   107    117   
................................................................................
   157    167   <hr />
   158    168   <h1><a name="verification_tests">VERIFICATION TESTS</a></h1>
   159    169   <p>The distribution contains a <em>tests</em> directory with some units tests using 
   160    170   an enhanced version of Michael Roth's <code>lunit</code> called <code>lunitx</code>. Some of the 
   161    171   tests were also derived from Michael's <strong>lua-sqlite3</strong> module, and more unit tests 
   162    172   added by Doug Currie. Get <code>lunitx</code> using Luarocks.</p>
   163    173   <p>The distribution also contains some functional tests by Tiago.</p>
   164         -<p>This version of <code>lsqlite3</code> was tested with SQLite 3.8.7.4.</p>
          174  +<p>This version of <code>lsqlite3</code> was tested with SQLite 3.11.0 and 3.15.0.</p>
   165    175   <p>
   166    176   </p>
   167    177   <hr />
   168    178   <h1><a name="reference">REFERENCE</a></h1>
   169    179   <p>
   170    180   </p>
   171    181   <hr />
................................................................................
   199    209           sqlite3.open_memory()</pre>
   200    210   <p>Opens an SQLite database <strong>in memory</strong> and returns its handle as
   201    211   userdata. In case of an error, the function returns nil, an error code
   202    212   and an error message. (In-memory databases are volatile as they are
   203    213   never stored on disk.)</p>
   204    214   <p>
   205    215   </p>
          216  +
          217  +<h2><a name="sqlite3_backup_init">sqlite3.backup_init</a></h2>
          218  +<pre>
          219  +        sqlite3.backup_init(target_db, target_name, source_db, source_name)</pre>
          220  +<p>Starts an SQLite Online Backup from <code>source_db</code> to <code>target_db</code> and 
          221  +returns its handle as userdata. The <code>source_db</code> and <code>target_db</code> are
          222  +open databases; they may be in-memory or file-based databases. The <code>target_name</code> and
          223  +<code>source_name</code> are "main" for the main database, "temp" for the temporary database, or 
          224  +the name specified after the AS keyword in an ATTACH statement for an attached database.</p>
          225  +<p>The source and target databases must be different, or else the init call will fail with an 
          226  +error. A call to <code>sqlite3.backup_init</code> will fail, returning NULL, if there is already 
          227  +a read or read-write transaction open on the target database.
          228  +</p>
          229  +<p>If an error occurs within <code>sqlite3.backup_init</code>, then NULL is returned, and an 
          230  +error code and error message are stored in <code>target_db</code>. The error code and message 
          231  +for the failed call can be retrieved using the <a href="#db_errcode"><code>db:errcode</code></a>, 
          232  +or <a href="#db_errmsg"><code>db:errmsg</code></a>.</p>
          233  +<p>
          234  +</p>
   206    235   <h2><a name="sqlite3_temp_directory">sqlite3.temp_directory</a></h2>
   207    236   <pre>
   208    237           sqlite3.temp_directory([temp])</pre>
   209    238   <p>Sets or queries the directory used by SQLite for temporary files. If
   210    239   string <code>temp</code> is a directory name or nil, the temporary directory is 
   211    240   set accordingly and the old value is returned. If <code>temp</code> is missing, 
   212    241   the function simply returns the current temporary directory.</p>
................................................................................
   968    997   <h2><a name="context_user_data">context:user_data</a></h2>
   969    998   <pre>
   970    999           context:user_data()</pre>
   971   1000   <p>Returns the userdata parameter given in the call to install the callback
   972   1001   function (see <a href="#db_create_aggregate"><code>db:create_aggregate()</code></a> and 
   973   1002   <a href="#db_create_function"><code>db:create_function()</code></a> for details).</p>
   974   1003   <p>
         1004  +</p>
         1005  +<hr />
         1006  +<h1><a name="methods_for_online_backup">Methods for Online Backup</a></h1>
         1007  +<p>A backup userdata is created using <code>backup = </code>
         1008  +<a href="#sqlite3_backup_init"><code>sqlite3.backup_init(...)</code></a>. It is then 
         1009  +used to step the backup, or inquire about its progress.</p>
         1010  +<p>
         1011  +</p>
         1012  +<h2><a name="bu_step">backup:step</a></h2>
         1013  +<pre>
         1014  +        backup:step(nPages)</pre>
         1015  +<p>Returns the status of the backup after stepping <code>nPages</code>. It is called one or more 
         1016  +times to transfer the data between the two databases.</p>
         1017  +<p><code>backup:step(nPages)</code> will copy up to <code>nPages</code> pages between the 
         1018  +source and destination databases specified by <code>backup</code> userdata. 
         1019  +If <code>nPages</code> is negative, all remaining source pages are copied. 
         1020  +</p>
         1021  +<p> If <code>backup:step(nPages)</code> successfully copies <code>nPages</code> pages and there 
         1022  +are still more pages to be copied, then the function returns <code>sqlite3.OK</code>. 
         1023  +If <code>backup:step(nPages)</code> successfully finishes copying all pages from source to 
         1024  +destination, then it returns <code>sqlite3.DONE</code>. If an error occurs during the step, then 
         1025  +an error code is returned. such as <code>sqlite3.READONLY</code>, <code>sqlite3.NOMEM</code>, 
         1026  +<code>sqlite3.BUSY</code>, <code>sqlite3.LOCKED</code>, or an <code>sqlite3.IOERR_XXX</code> 
         1027  +extended error code.
         1028  +</p>
         1029  +<p>
         1030  +</p>
         1031  +<h2><a name="bu_remaining">backup:remaining</a></h2>
         1032  +<pre>
         1033  +        backup:remaining()</pre>
         1034  +<p>Returns the number of pages still to be backed up at the conclusion of the most recent step.
         1035  +</p>
         1036  +<p>
         1037  +</p>
         1038  +<h2><a name="bu_pagecount">backup:pagecount</a></h2>
         1039  +<pre>
         1040  +        backup:pagecount()</pre>
         1041  +<p>Returns the total number of pages in the source database at the conclusion of the most recent
         1042  +step.</p>
         1043  +<p>
         1044  +</p>
         1045  +<h2><a name="bu_finish">backup:finish</a></h2>
         1046  +<pre>
         1047  +        backup:finish()</pre>
         1048  +<p>When <code>backup:step(nPages)</code> has returned <code>sqlite3.DONE</code>, or when the 
         1049  +application wishes to abandon the backup operation, the application should destroy the backup 
         1050  +by calling <code>backup:finish()</code>. This releases all resources associated with the backup. 
         1051  +If <code>backup:step(nPages)</code> has not yet returned <code>sqlite3.DONE</code>, then any 
         1052  +active write-transaction on the destination database is rolled back. After the call, the backup 
         1053  +userdata corresponds to a completed backup, and should not be used.
         1054  +</p>
         1055  +<p>The value returned by <code>backup:finish()</code> is <code>sqlite3.OK</code> if no errors 
         1056  +occurred, regardless or whether or not the backup completed. If an out-of-memory condition or IO 
         1057  +error occurred during any prior step on the same backup, then <code>backup:finish()</code> 
         1058  +returns the corresponding error code.
         1059  +</p>
         1060  +<p>A return of <code>sqlite3.BUSY</code> or <code>sqlite3.LOCKED</code> from 
         1061  +<code>backup:step(nPages)</code> is not a permanent error and does not affect the return value 
         1062  +of <code>backup:finish()</code>.
         1063  +</p>
         1064  +<p>
   975   1065   </p>
   976   1066   <hr />
   977   1067   <h1><a name="numerical_error_and_result_codes">Numerical error and result codes</a></h1>
   978   1068   <p>The following constants are defined by module sqlite3:</p>
   979   1069   <pre>
   980   1070           OK: 0          ERROR: 1       INTERNAL: 2    PERM: 3        ABORT: 4
   981   1071           BUSY: 5        LOCKED: 6      NOMEM: 7       READONLY: 8    INTERRUPT: 9
................................................................................
   997   1087   </pre>
   998   1088   <p>For details about their exact meaning please see the <strong>SQLite3
   999   1089   documentation</strong> <a href="http://www.sqlite.org/">http://www.sqlite.org/</a>.</p>
  1000   1090   <p>
  1001   1091   </p>
  1002   1092   <hr />
  1003   1093   <h1><a name="version">VERSION</a></h1>
  1004         -<p>This is <code>lsqlite3</code> version &quot;0.9.3&quot;, also tagged as <code>fsl_9w</code>.</p>
         1094  +<p>This is <code>lsqlite3</code> version &quot;0.9.4&quot;, also tagged as <code>fsl_9x</code>.</p>
  1005   1095   <p>
  1006   1096   </p>
  1007   1097   <hr />
  1008   1098   <h1><a name="credits">CREDITS</a></h1>
  1009   1099   <p><code>lsqlite3</code> was developed by Tiago Dionizio and Doug Currie with 
  1010         -contributions from Thomas Lauer and Michael Roth.</p>
         1100  +contributions from Thomas Lauer, Michael Roth, and Wolfgang Oertl.</p>
  1011   1101   <p>This documentation is based on the &quot;(very) preliminary&quot; documents
  1012   1102   for the Idle-SQLite3 database module. Thanks to Thomas Lauer for
  1013   1103   making it available.</p>
  1014   1104   <p>
  1015   1105   </p>
  1016   1106   <hr />
  1017   1107   <h1><a name="license">LICENSE</a></h1>
  1018   1108   <pre>
  1019   1109       /************************************************************************
  1020   1110       * lsqlite3                                                              *
  1021         -    * Copyright (C) 2002-2015 Tiago Dionizio, Doug Currie                   *
         1111  +    * Copyright (C) 2002-2016 Tiago Dionizio, Doug Currie                   *
  1022   1112       * All rights reserved.                                                  *
  1023   1113       * Author    : Tiago Dionizio &lt;tiago.dionizio@ist.utl.pt&gt;                *
  1024   1114       * Author    : Doug Currie &lt;doug.currie@alum.mit.edu&gt;                    *
  1025         -    * Library   : lsqlite3 - a SQLite 3 database binding for Lua 5          *
         1115  +    * Library   : lsqlite3 - an SQLite 3 database binding for Lua 5         *
  1026   1116       *                                                                       *
  1027   1117       * Permission is hereby granted, free of charge, to any person obtaining *
  1028   1118       * a copy of this software and associated documentation files (the       *
  1029   1119       * &quot;Software&quot;), to deal in the Software without restriction, including   *
  1030   1120       * without limitation the rights to use, copy, modify, merge, publish,   *
  1031   1121       * distribute, sublicense, and/or sell copies of the Software, and to    *
  1032   1122       * permit persons to whom the Software is furnished to do so, subject to *