Add SQLite chapter

1 files changed, 593 insertions, 29 deletions

diff --git a/doc/manual.xhtml b/doc/manual.xhtml
index b586bf9..e0d5177 100644
--- a/doc/manual.xhtml
+++ b/doc/manual.xhtml
@@ -8,8 +8,8 @@
   <meta name="copyright" content="&copy; 2009-2011 Code Synthesis Tools CC"/>
   <meta name="keywords" content="odb,c++,object,persistence,ORM,relational,database,RDBMS,ODBMS,OODBMS"/>
   <meta name="description" content="C++ Object Persistence with ODB"/>
-  <meta name="revision" content="1.2"/>
-  <meta name="version" content="1.2.0"/>
+  <meta name="revision" content="1.3.b1"/>
+  <meta name="version" content="1.3.0.b1"/>
 
 <!--
 
@@ -263,8 +263,8 @@ for consistency.
     no Front-Cover Texts and no Back-Cover Texts.</p>
 
     <!-- REMEMBER TO CHANGE VERSIONS IN THE META TAGS ABOVE! -->
-    <p id="revision">Revision 1.2, March 2011</p>
-    <p>This revision of the manual describes ODB 1.2.0 and is available
+    <p id="revision">Revision 1.3.b1, March 2011</p>
+    <p>This revision of the manual describes ODB 1.3.0.b1 and is available
     in the following formats:
     <a href="http://www.codesynthesis.com/products/odb/doc/manual.xhtml">XHTML</a>,
     <a href="http://www.codesynthesis.com/products/odb/doc/odb-manual.pdf">PDF</a>, and
@@ -467,29 +467,50 @@ for consistency.
         <table class="toc">
           <tr><th>10.1</th><td><a href="#10.1">MySQL Type Mapping</a></td></tr>
           <tr><th>10.2</th><td><a href="#10.2">MySQL Database Class</a></td></tr>
-          <tr><th>10.3</th><td><a href="#10.3">Connection Factory</a></td></tr>
+          <tr><th>10.3</th><td><a href="#10.3">MySQL Connection Factory</a></td></tr>
 	  <tr><th>10.4</th><td><a href="#10.4">MySQL Exceptions</a></td></tr>
         </table>
       </td>
     </tr>
 
     <tr>
+      <th>11</th><td><a href="#11">SQLite Database</a>
+        <table class="toc">
+          <tr><th>11.1</th><td><a href="#11.1">SQLite Type Mapping</a></td></tr>
+          <tr><th>11.2</th><td><a href="#11.2">SQLite Database Class</a></td></tr>
+          <tr><th>11.3</th><td><a href="#11.3">SQLite Connection Factory</a></td></tr>
+	  <tr><th>11.4</th><td><a href="#11.4">SQLite Exceptions</a></td></tr>
+          <tr>
+            <th>11.5</th><td><a href="#11.5">SQLite Limitations</a>
+              <table class="toc">
+                <tr><th>11.5.1</th><td><a href="#11.5.1">Query Result Caching</a></td></tr>
+		<tr><th>11.5.2</th><td><a href="#11.5.2">Automatic Assignment of Object Ids</a></td></tr>
+		<tr><th>11.5.3</th><td><a href="#11.5.3">Constraint Violations</a></td></tr>
+		<tr><th>11.5.4</th><td><a href="#11.5.4">Sharing of Queries</a></td></tr>
+              </table>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+
+    <tr>
       <th colspan="2"><a href="#III">PART III PROFILES</a></th>
     </tr>
 
     <tr>
-      <th>11</th><td><a href="#11">Profiles Introduction</a></td>
+      <th>12</th><td><a href="#12">Profiles Introduction</a></td>
     </tr>
 
     <tr>
-      <th>12</th><td><a href="#12">Boost Profile</a>
+      <th>13</th><td><a href="#13">Boost Profile</a>
         <table class="toc">
-          <tr><th>12.1</th><td><a href="#12.1">Smart Pointers Library</a></td></tr>
-          <tr><th>12.2</th><td><a href="#12.2">Unordered Containers Library</a></td></tr>
+          <tr><th>13.1</th><td><a href="#13.1">Smart Pointers Library</a></td></tr>
+          <tr><th>13.2</th><td><a href="#13.2">Unordered Containers Library</a></td></tr>
           <tr>
-	    <th>12.3</th><td><a href="#12.3">Date Time Library</a>
+	    <th>13.3</th><td><a href="#13.3">Date Time Library</a>
 	      <table class="toc">
-	        <tr><th>12.3.1</th><td><a href="#12.3.1">MySQL Database Type Mapping</a></td></tr>
+	        <tr><th>13.3.1</th><td><a href="#13.3.1">MySQL Database Type Mapping</a></td></tr>
 	      </table>
 	    </td>
 	  </tr>
@@ -6458,6 +6479,7 @@ aCC +W2161 ...
      as well as the default mapping between basic C++ value types
      and native database types.</p>
 
+
   <!-- CHAPTER -->
 
 
@@ -6714,25 +6736,25 @@ namespace odb
   <p>The static <code>print_usage()</code> function prints the list of options
      with short descriptions that are recognized by this constructor.</p>
 
-  <p>The last argument to all of the constructors is the
+  <p>The last argument to all of the constructors is a
      pointer to the connection factory. If we pass a
      non-<code>NULL</code> value, the database instance assumes
      ownership of the factory instance. The connection factory
      interface as well as the available implementations are described
      in the next section.</p>
 
-  <p>The set of accessor functions following the constructors allow us
+  <p>The set of accessor functions following the constructors allows us
      to query the parameters of the <code>database</code> instance.</p>
 
   <p>The <code>connection()</code> function returns the MySQL database
      connection encapsulated by the <code>odb::mysql::connection</code>
-     class. Normally, you wouldn't call this function directly and
+     class. Normally, we wouldn't call this function directly and
      instead let the ODB runtime manage the database connections. However,
      if for some reason you need to access the underlying MySQL connection
      handle, refer to the MySQL ODB runtime source code for the interface
      of the <code>connection</code> class.</p>
 
-  <h2><a name="10.3">10.3 Connection Factory</a></h2>
+  <h2><a name="10.3">10.3 MySQL Connection Factory</a></h2>
 
   <p>The <code>connection_factory</code> abstract class has the
      following interface:</p>
@@ -6763,7 +6785,7 @@ namespace odb
 
   <p>The two implementations of the <code>connection_factory</code>
      interface provided by the MySQL ODB runtime are
-     the <code>new_connection_factory</code> and
+     <code>new_connection_factory</code> and
      <code>connection_pool_factory</code>. You will need to include
      the <code>&lt;odb/mysql/connection-factory.hxx></code>
      header file to make the <code>connection_factory</code> interface
@@ -6773,7 +6795,23 @@ namespace odb
   <p>The <code>new_connection_factory</code> class creates a new
      connection whenever one is requested. When a connection is no
      longer needed, it is released and closed. The
-     <code>connection_pool_factory</code> class implements a
+     <code>new_connection_factory</code> class has the following
+     interface:</p>
+
+  <pre class="c++">
+namespace odb
+{
+  namespace mysql
+  {
+    class new_connection_factory: public connection_factory
+    {
+    public:
+      new_connection_factory ();
+    };
+};
+  </pre>
+
+  <p>The <code>connection_pool_factory</code> class implements a
      connection pool. It has the following interface:</p>
 
   <pre class="c++">
@@ -6783,6 +6821,7 @@ namespace odb
   {
     class connection_pool_factory: public connection_factory
     {
+    public:
       connection_pool_factory (std::size_t max_connections = 0,
                                std::size_t min_connections = 0,
                                bool ping = true)
@@ -6804,24 +6843,24 @@ namespace odb
      <code>max_connections</code> value to see if a new connection
      can be created. If the total number of connections maintained
      by the pool is less than this value, then a new connection is
-     created and returned. Otherwise, the calling thread is blocked
-     until a connection becomes available.</p>
+     created and returned. Otherwise, the caller is blocked until
+     a connection becomes available.</p>
 
   <p>When a connection is released, the pool factory first checks
-     if there are blocked threads waiting for a connection. If so,
+     if there are blocked callers waiting for a connection. If so, then
      one of them is unblocked and is given the connection. Otherwise,
      the pool factory checks whether the total number of connections
      maintained by the pool is greater than the <code>min_connections</code>
      value. If that's the case, the connection is closed. Otherwise, the
      connection is added to the pool of available connections to be
      returned on the next request. In other words, if the number of
-     connections maintained by the pool exceeds the <code>min_connections</code>
-     number and there are no threads waiting for a new connection,
+     connections maintained by the pool exceeds <code>min_connections</code>
+     and there are no caller waiting for a new connection,
      then the pool will close the excess connections.</p>
 
   <p>If the <code>max_connections</code> value is 0, then the pool will
      create a new connection whenever all of the existing connections
-     are in use.  If the <code>min_connections</code> value is 0, then
+     are in use. If the <code>min_connections</code> value is 0, then
      the pool will never close a connection and instead maintain all
      the connections that were ever created.</p>
 
@@ -6910,6 +6949,531 @@ namespace odb
      of an error.</p>
 
 
+  <!-- CHAPTER -->
+
+
+  <hr class="page-break"/>
+  <h1><a name="11">11 SQLite Database</a></h1>
+
+  <p>To generate support code for the SQLite database you will need
+     to pass the "<code>--database&nbsp;sqlite</code>"
+     (or "<code>-d&nbsp;sqlite</code>") option to the ODB compiler.
+     Your application will also need to link to the SQLite ODB runtime
+     library (<code>libodb-sqlite</code>). All SQLite-specific ODB
+     classes are defined in the <code>odb::sqlite</code> namespace.</p>
+
+  <h2><a name="11.1">11.1 SQLite Type Mapping</a></h2>
+
+  <p>The following table summarizes the default mapping between basic
+     C++ value types and SQLite database types. This mapping can be
+     customized on the per-type and per-member basis using the ODB
+     Pragmas Language (<a href="#9">Chapter 9, "ODB Pragma
+     Language"</a>).</p>
+
+  <!-- border="1" is necessary for html2ps -->
+  <table id="mapping" border="1">
+    <tr>
+      <th>C++ Type</th>
+      <th>SQLite type</th>
+    </tr>
+
+    <tr>
+      <td><code>bool</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>char</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>signed char</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>unsigned char</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>short</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>unsigned short</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>int</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>unsigned int</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>long</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>unsigned long</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>long long</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>unsigned long long</code></td>
+      <td><code>INTEGER NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>float</code></td>
+      <td><code>REAL NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>double</code></td>
+      <td><code>REAL NOT NULL</code></td>
+    </tr>
+
+    <tr>
+      <td><code>std::string</code></td>
+      <td><code>TEXT NOT NULL</code></td>
+    </tr>
+  </table>
+
+  <p>Note that SQLite only operates with signed integers and the largest
+     value that an SQLite database can store is a signed 64-bit integer. As
+     a result, greater <code>unsigned&nbsp;long&nbsp;long</code> values will be
+     represented in the database as negative values.</p>
+
+  <h2><a name="11.2">11.2 SQLite Database Class</a></h2>
+
+  <p>The SQLite <code>database</code> class has the following
+     interface:</p>
+
+  <pre class="c++">
+namespace odb
+{
+  namespace sqlite
+  {
+    class database: public odb::database
+    {
+    public:
+      database (const std::string&amp; name,
+                int flags = SQLITE_OPEN_READWRITE,
+                std::auto_ptr&lt;connection_factory> = 0);
+
+      database (int&amp; argc,
+                char* argv[],
+                bool erase = false,
+                int flags = SQLITE_OPEN_READWRITE,
+                std::auto_ptr&lt;connection_factory> = 0);
+
+      static void
+      print_usage (std::ostream&amp;);
+
+    public:
+      const std::string&amp;
+      name () const;
+
+      int
+      flags () const;
+
+    public:
+      transaction_impl*
+      begin_immediate ();
+
+      transaction_impl*
+      begin_exclusive ();
+
+    public:
+      details::shared_ptr&amp;lt;sqlite::connection>
+      connection ();
+    };
+  }
+}
+  </pre>
+
+  <p>You will need to include the <code>&lt;odb/sqlite/database.hxx></code>
+     header file to make this class available in your application.</p>
+
+  <p>The first constructor opens the specified SQLite database. The
+     <code>name</code> argument is the database file
+     name to open. If this argument is empty, then a temporary,
+     on-disk database is created. If this argument is the
+     <code>:memory:</code> special value, then a temporary, in-memory
+     database is created. The <code>flags</code> argument allows us to
+     specify SQLite opening flags. For more information on the possible
+     values, refer to the <code>sqlite3_open_v2</code> function description
+     in the SQLite C API documentation. The following example shows how
+     we can open the <code>test.db</code> database in the read-write
+     mode and create it if it does not exist:
+  </p>
+
+  <pre class="c++">
+auto_ptr&lt;odb::database> db (
+  new odb::sqlite::database (
+    "test.db",
+    SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE));
+  </pre>
+
+  <p>The second constructor extracts the database parameters from the
+     command line. The following options are recognized:</p>
+
+  <pre class="terminal">
+  --database &lt;name>
+  --create
+  --read-only
+  --options-file &lt;file>
+  </pre>
+
+  <p>By default, this constructor opens the database in the read-write mode
+     (<code>SQLITE_OPEN_READWRITE</code> flag). If the <code>--create</code>
+     flag is specified, then the database file is created if it does
+     not already exist (<code>SQLITE_OPEN_CREATE</code> flag). If the
+     <code>--read-only</code> flag is specified, then the database is
+     opened in the read-only mode (<code>SQLITE_OPEN_READONLY</code>
+     flag instead of <code>SQLITE_OPEN_READWRITE</code>). The
+     <code>--options-file</code> option allows us to specify some
+     or all of the database options in a file with each option appearing
+     on a separate line followed by space and an option value.</p>
+
+  <p>If the <code>erase</code> argument to this constructor is true,
+     then the above options are removed from the <code>argv</code>
+     array and the <code>argc</code> count is updated accordingly.
+     This is primarily useful if your application accepts other
+     options or arguments and you would like to get the SQLite
+     options out of the <code>argv</code> array.</p>
+
+  <p>The <code>flags</code> argument has the same semantics as in
+     the first constructor. Flags from the command line always override
+     the corresponding values specified with this argument.</p>
+
+  <p>The second constructor throws the <code>odb::sqlite::cli_exception</code>
+     exception if the SQLite option values are missing or invalid.
+     See section <a href="#11.4">Section 11.4, "SQLite Exceptions"</a>
+     for more information on this exception.</p>
+
+  <p>The static <code>print_usage()</code> function prints the list of options
+     with short descriptions that are recognized by the second constructor.</p>
+
+  <p>The last argument to both constructors is a pointer to the connection
+     factory. If we pass a non-<code>NULL</code> value, the database instance
+     assumes ownership of the factory instance. The connection factory
+     interface as well as the available implementations are described
+     in the next section.</p>
+
+  <p>The set of accessor functions following the constructors allows us
+     to query the parameters of the <code>database</code> instance.</p>
+
+  <p>The <code>begin_immediate()</code> and <code>begin_exclusive()</code>
+     functions are the SQLite-specific extensions to the standard
+     <code>odb::database::begin()</code> function (see
+     <a href="#3.4">Section 3.4, "Transactions"</a>). They allow us
+     to start an immediate (<code>BEGIN IMMEDIATE</code>) and an exclusive
+     (<code>BEGIN EXCLUSIVE</code>) SQLite transaction, respectively.
+     For more information on the semantics of the immediate and exclusive
+     transactions, refer to the <code>BEGIN</code> statement description
+     in the SQLite documentation.</p>
+
+  <p>The <code>connection()</code> function returns the SQLite database
+     connection encapsulated by the <code>odb::sqlite::connection</code>
+     class. Normally, we wouldn't call this function directly and
+     instead let the ODB runtime manage the database connections. However,
+     if for some reason you need to access the underlying SQLite connection
+     handle, refer to the SQLite ODB runtime source code for the interface
+     of the <code>connection</code> class.</p>
+
+  <h2><a name="11.3">11.3 SQLite Connection Factory</a></h2>
+
+  <p>The <code>connection_factory</code> abstract class has the
+     following interface:</p>
+
+  <pre class="c++">
+namespace odb
+{
+  namespace sqlite
+  {
+    class connection_factory
+    {
+    public:
+      virtual void
+      database (sqlite::database&amp;) = 0;
+
+      virtual details::shared_ptr&lt;sqlite::connection>
+      connect () = 0;
+    };
+  }
+}
+  </pre>
+
+  <p>The <code>database()</code> function is called when a connection
+     factory is associated with a database instance. This happens in
+     the <code>odb::sqlite::database</code> class constructors. The
+     <code>connect()</code> function is called whenever a database
+     connection is requested.</p>
+
+  <p>The three implementations of the <code>connection_factory</code>
+     interface provided by the SQLite ODB runtime library are
+     <code>single_connection_factory</code>,
+     <code>new_connection_factory</code>, and
+     <code>connection_pool_factory</code>. You will need to include
+     the <code>&lt;odb/sqlite/connection-factory.hxx></code>
+     header file to make the <code>connection_factory</code> interface
+     and these implementation classes available in your application.</p>
+
+  <p>The <code>single_connection_factory</code> class creates a
+     single connection that is shared between all the threads in
+     an application. If the connection is currently not in use,
+     then it is returned to the caller. Otherwise, the caller is
+     blocked until the connection becomes available. The
+     <code>single_connection_factory</code> class has the following
+     interface:</p>
+
+  <pre class="c++">
+namespace odb
+{
+  namespace sqlite
+  {
+    class single_connection_factory: public connection_factory
+    {
+    public:
+      single_connection_factory ();
+    };
+};
+  </pre>
+
+
+  <p>The <code>new_connection_factory</code> class creates a new
+     connection whenever one is requested. When a connection is no
+     longer needed, it is released and closed. The
+     <code>new_connection_factory</code> class has the following
+     interface:</p>
+
+  <pre class="c++">
+namespace odb
+{
+  namespace sqlite
+  {
+    class new_connection_factory: public connection_factory
+    {
+    public:
+      new_connection_factory ();
+    };
+};
+  </pre>
+
+  <p>The <code>connection_pool_factory</code> class implements a
+     connection pool. It has the following interface:</p>
+
+  <pre class="c++">
+namespace odb
+{
+  namespace sqlite
+  {
+    class connection_pool_factory: public connection_factory
+    {
+    public:
+      connection_pool_factory (std::size_t max_connections = 0,
+                               std::size_t min_connections = 0)
+    };
+};
+  </pre>
+
+  <p>The <code>max_connections</code> argument specifies the maximum
+     number of concurrent connections that this pool factory will
+     maintain. Similarly, the <code>min_connections</code> argument
+     specifies the minimum number of available connections that
+     should be kept open.</p>
+
+  <p>Whenever a connection is requested, the pool factory first
+     checks if there is an unused connection that can be returned.
+     If there is none, the pool factory checks the
+     <code>max_connections</code> value to see if a new connection
+     can be created. If the total number of connections maintained
+     by the pool is less than this value, then a new connection is
+     created and returned. Otherwise, the caller is blocked until
+     a connection becomes available.</p>
+
+  <p>When a connection is released, the pool factory first checks
+     if there are blocked callers waiting for a connection. If so, then
+     one of them is unblocked and is given the connection. Otherwise,
+     the pool factory checks whether the total number of connections
+     maintained by the pool is greater than the <code>min_connections</code>
+     value. If that's the case, the connection is closed. Otherwise, the
+     connection is added to the pool of available connections to be
+     returned on the next request. In other words, if the number of
+     connections maintained by the pool exceeds <code>min_connections</code>
+     and there are no callers waiting for a new connection,
+     then the pool will close the excess connections.</p>
+
+  <p>If the <code>max_connections</code> value is 0, then the pool will
+     create a new connection whenever all of the existing connections
+     are in use. If the <code>min_connections</code> value is 0, then
+     the pool will never close a connection and instead maintain all
+     the connections that were ever created.</p>
+
+  <p>By default, connections created by <code>new_connection_factory</code>
+     and <code>connection_pool_factory</code> enable the SQLite shared cache
+     mode and use the unlock notify functionality to aid concurrency. To
+     disable the shared cache mode you can pass the
+     <code>SQLITE_OPEN_PRIVATECACHE</code> flag when creating the database
+     instance. For more information on the shared cache mode refer to the
+     SQLite documentation.</p>
+
+  <p>If you pass <code>NULL</code> as the connection factory to one of the
+     <code>database</code> constructors, then the <code>connection_pool_factory</code>
+     instance will be created by default with the min and max connections
+     values set to <code>0</code>. The following code fragment shows how we
+     can pass our own connection factory instance:</p>
+
+  <pre class="c++">
+#include &lt;odb/database.hxx>
+
+#include &lt;odb/sqlite/database.hxx>
+#include &lt;odb/sqlite/connection-factory.hxx>
+
+int
+main (int argc, char* argv[])
+{
+  auto_ptr&lt;odb::sqlite::connection_factory> f (
+    new odb::sqlite::connection_pool_factory (20));
+
+  auto_ptr&lt;odb::database> db (
+    new sqlite::database (argc, argv, false, SQLITE_OPEN_READWRITE, f));
+}
+  </pre>
+
+  <h2><a name="11.4">11.4 SQLite Exceptions</a></h2>
+
+  <p>The SQLite ODB runtime library defines the following SQLite-specific
+     exceptions:</p>
+
+  <pre class="c++">
+namespace odb
+{
+  namespace sqlite
+  {
+    class database_exception: odb::database_exception
+    {
+    public:
+      int
+      error () const
+
+      int
+      extended_error () const;
+
+      const std::string&amp;
+      message () const;
+
+      virtual const char*
+      what () const throw ();
+    };
+
+    class cli_exception: odb::exception
+    {
+    public:
+      virtual const char*
+      what () const throw ();
+    };
+  }
+}
+  </pre>
+
+  <p>You will need to include the <code>&lt;odb/sqlite/exceptions.hxx></code>
+     header file to make these exceptions available in your application.</p>
+
+  <p>The <code>odb::sqlite::database_exception</code> is thrown if
+     an SQLite database operation fails. The SQLite-specific error
+     information is accessible via the <code>error()</code>,
+     <code>extended_error()</code>, and <code>message()</code> functions.
+     All this information is also combined and returned in a
+     human-readable form by the <code>what()</code> function.</p>
+
+  <p>The <code>odb::sqlite::cli_exception</code> is thrown by the
+     command line parsing constructor of the <code>odb::sqlite::database</code>
+     class if the SQLite option values are missing or invalid. The
+     <code>what()</code> function returns a human-readable description
+     of an error.</p>
+
+
+  <h2><a name="11.5">11.5 SQLite Limitations</a></h2>
+
+  <p>The following sections describe SQLite-specific limitations imposed by
+     the current SQLite and ODB runtime versions.</p>
+
+  <h3><a name="11.5.1">11.5.1 Query Result Caching</a></h3>
+
+  <p>SQLite ODB runtime implementation does not perform query result caching
+     (<a href="#4.4">Section 4.4, "Query Result"</a>) even when explicitly
+     requested. The SQLite API supports interleaving execution of multiple
+     prepared statements on a single connection. As a result, with SQLite, it
+     is possible to have multiple uncached results and calls to other database
+     functions do not invalidate them. The only limitation of the uncached
+     SQLite results is the unavailability of the <code>result::size()</code>
+     function. If you call this function on an SQLite query result, then
+     the <code>odb::result_not_cached</code> exception
+     (<a href="#3.11">Section 3.11, "ODB Exceptions"</a>) is always
+     thrown. Future versions of the SQLite ODB runtime library may add support
+     for result caching.</p>
+
+  <h3><a name="11.5.2">11.5.2 Automatic Assignment of Object Ids</a></h3>
+
+  <p>Due to SQLite API limitations, every automatically assigned object id
+     (<a href="#9.3.2">Section 9.3.2, "<code>auto</code>"</a>) should have
+     the <code>INTEGER</code> SQLite type. While SQLite will treat other
+     integer type names (such as <code>INT</code>, <code>BIGINT</code>, etc.)
+     as <code>INTEGER</code>, automatic id assignment will not work. By default,
+     ODB maps all C++ integral types to <code>INTEGER</code>. This means that
+     the only situation that requires consideration is the assignment of a
+     custom database type using the <code>db&nbsp;type</code> pragma
+     (<a href="#9.3.3">Section 9.3.3, "<code>type</code>"</a>). For
+     example:</p>
+
+<pre class="c++">
+#pragma db object
+class person
+{
+  ...
+
+  //#pragma db id auto type("INT")     // Will not work.
+  //#pragma db id auto type("INTEGER") // Ok.
+  #pragma db id auto                   // Ok, Mapped to INTEGER.
+  unsigned int id_;
+};
+</pre>
+
+  <h3><a name="11.5.3">11.5.3 Constraint Violations</a></h3>
+
+  <p>Due to the granularity of the SQLite error codes, it is impossible
+     to distinguish between the duplicate primary key and other constraint
+     violations. As a result, when making an object persistent, The SQLite
+     ODB runtime will translate all constraint violation errors to the
+     <code>object_not_persistent</code> exception (<a href="#3.11">Section
+     3.11, "ODB Exceptions"</a>).</p>
+
+  <h3><a name="11.5.4">11.5.4 Sharing of Queries</a></h3>
+
+  <p>As discussed in <a href="#4.3">Section 4.3, "Executing a Query"</a>, a
+     query instance that does not have any by-reference parameters is
+     immutable and can be shared between multiple threads without
+     synchronization. Currently, the SQLite ODB runtime does not support this
+     functionality. Future versions of the library will remove this
+     limitation.</p>
+
+
   <!-- PART -->
 
 
@@ -6925,7 +7489,7 @@ namespace odb
 
 
   <hr class="page-break"/>
-  <h1><a name="11">11 Profiles Introduction</a></h1>
+  <h1><a name="12">12 Profiles Introduction</a></h1>
 
   <p>ODB profiles are a generic mechanism for integrating ODB with
      widely-used C++ frameworks and libraries. A profile provides glue
@@ -6979,7 +7543,7 @@ odb --profile boost/date-time ...
 
 
   <hr class="page-break"/>
-  <h1><a name="12">12 Boost Profile</a></h1>
+  <h1><a name="13">13 Boost Profile</a></h1>
 
   <p>The ODB profile implementation for Boost is provided by the
      <code>libodb-boost</code> library and consists of multiple sub-profiles
@@ -7004,7 +7568,7 @@ odb --profile boost/date-time ...
      that can be thrown by the Boost sub-profiles are described in the
      following sections.</p>
 
-  <h2><a name="12.1">12.1 Smart Pointers Library</a></h2>
+  <h2><a name="13.1">13.1 Smart Pointers Library</a></h2>
 
   <p>The <code>smart-ptr</code> sub-profile provides persistence
      support for a subset of smart pointers from the Boost
@@ -7055,7 +7619,7 @@ class employee
      behavior, add the <code>--default-pointer</code> option specifying the
      alternative object pointer after the <code>--profile</code> option.</p>
 
-  <h2><a name="12.2">12.2 Unordered Containers Library</a></h2>
+  <h2><a name="13.2">13.2 Unordered Containers Library</a></h2>
 
   <p>The <code>unordered</code> sub-profile provides persistence support for
      the containers from the Boost <code>unordered</code> library. To enable
@@ -7081,7 +7645,7 @@ class employee
 };
 </pre>
 
-  <h2><a name="12.3">12.3 Date Time Library</a></h2>
+  <h2><a name="13.3">13.3 Date Time Library</a></h2>
 
   <p>The <code>date-time</code> sub-profile provides persistence support for a
      subset of types from the Boost <code>date_time</code> library. It is
@@ -7154,7 +7718,7 @@ namespace odb
      exceptions are thrown are database system dependent and are discussed in
      more detail in the following sub-sections.</p>
 
-  <h3><a name="12.3.1">12.3.1 MySQL Database Type Mapping</a></h3>
+  <h3><a name="13.3.1">13.3.1 MySQL Database Type Mapping</a></h3>
 
   <p>The following table summarizes the default mapping between the currently
      supported Boost <code>date_time</code> types and the MySQL database