Add support for embedded database schemas

New options: --schema-format, --default-schema. New example: schema/embedded.

3 files changed, 103 insertions, 5 deletions

diff --git a/doc/manual.xhtml b/doc/manual.xhtml
index fd14163..f244dc5 100644
--- a/doc/manual.xhtml
+++ b/doc/manual.xhtml
@@ -1046,10 +1046,16 @@ mysql --user=odb_test --database=odb_test < person.sql
 
   <p>The above command will log in to a local MySQL server as user
     <code>odb_test</code> without a password and use the database
-    named <code>odb_test</code>. Note that after executing this
+    named <code>odb_test</code>. Beware that after executing this
     command, all the data stored in the <code>odb_test</code> database
     will be deleted.</p>
 
+  <p>Note also that using a standalone generated SQL file is not the
+     only way to create a database schema in ODB. We can also embed
+     the schema directly into our application or use custom schemas
+     that were not generated by the ODB compiler. Refer to
+     <a href="#3.3">Section 3.3, "Database"</a> for details.</p>
+
   <p>Once the database schema is ready, we run our application
   using the same login and database name:</p>
 
@@ -1916,6 +1922,80 @@ auto_ptr&lt;odb::database> db (
      system-specific <code>database</code> classes, refer to
      <a href="#10">Chapter 10, "Database Systems"</a>.</p>
 
+  <p>Before we can persist our objects, the corresponding database schema has
+     to be created in the database. The schema contains table definitions and
+     other relational database artifacts that are used to store the state of
+     persistent objects in the database.</p>
+
+  <p>There are several ways to create the database schema. The easiest is to
+     instruct the ODB compiler to generate the corresponding schema from the
+     persistent classes (<code>--generate-schema</code> option). The ODB
+     compiler can generate the schema either as a standalone SQL file or
+     embedded into the generated C++ code (<code>--schema-format</code>
+     option).  If we are using the SQL file to create the database schema, then
+     this file should be executed, normally only once, before the application
+     is started.</p>
+
+  <p>Alternatively, the schema can be embedded directly into the generated
+     code and we can use the <code>odb::schema_catalog</code> class to
+     create it in the database from within our application,
+     for example:</p>
+
+  <pre class="c++">
+#include &lt;odb/schema-catalog.hxx>
+
+odb::transaction t (db->begin ());
+odb::schema_catalog::create_schema (*db);
+t.commit ();
+  </pre>
+
+  <p>Refer to the next section for information on the
+     <code>odb::transaction</code> class.  The complete version of the above
+     code fragment is available in the <code>schema/embedded</code> example in
+     the <code>odb-examples</code> package.</p>
+
+  <p>The <code>odb::schema_catalog</code> class has the following interface.
+     You will need to include the <code>&lt;odb/schema-catalog.hxx></code>
+     header file to make this class available in your application.</p>
+
+  <pre class="c++">
+namespace odb
+{
+  class schema_catalog
+  {
+  public:
+    static void
+    create_schema (database&amp;, const std::string&amp; name = "");
+  };
+}
+  </pre>
+
+  <p>The first argument to the <code>create_schema()</code> function
+     is the database instance that we would like to create the schema in.
+     The second argument is the schema name. By default, the ODB
+     compiler generates all embedded schemas with the default schema
+     name (empty string). However, if your application needs to
+     have several separate schemas, you can use the
+     <code>--default-schema</code> ODB compiler option to assign
+     custom schema names and then use these names as a second argument
+     to <code>create_schema()</code>. If the schema is not found,
+     <code>create_schema()</code> throws the
+     <code>odb::unknown_schema</code> exception. The
+     <code>create_schema()</code> function should be called within
+     a transaction.</p>
+
+  <p>Finally, we can also use a custom database schema with ODB. This approach
+     can work similarly to the standalone SQL file described above except that
+     the database schema is hand-written or produced by another program. Or we
+     could execute custom SQL statements that create the schema directly from
+     our application. To map persistent classes to custom database schemas, ODB
+     provides a wide range of mapping customization pragmas, such
+     as <code>db&nbsp;table</code>, <code>db&nbsp;column</code>,
+     and <code>db&nbsp;type</code> (<a href="#9">Chapter 9, "ODB Pragma
+     Language"</a>). For sample code that shows how to perform such mapping
+     for various C++ constructs, refer to the <code>schema/custom</code>
+     example in the <code>odb-examples</code> package.</p>
+
   <h2><a name="3.4">3.4 Transactions</a></h2>
 
   <p>A transaction is an atomic, consistent, isolated and durable
@@ -2615,6 +2695,17 @@ namespace odb
   struct database_exception: exception
   {
   };
+
+  // Schema catalog exceptions.
+  //
+  struct unknown_schema: exception
+  {
+    const std::string&amp;
+    name () const;
+
+    virtual const char*
+    what () const throw ();
+  };
 }
   </pre>
 
@@ -2663,11 +2754,16 @@ namespace odb
      the query result class. Refer to <a href="#4.4">Section 4.4,
      "Query Result"</a> for details.</p>
 
-  <p>The <code>database_exception</code> is a base class for all
+  <p>The <code>database_exception</code> exception is a base class for all
      database system-specific exceptions that are thrown by the
      database system-specific runtime library. See <a href="#10">Chapter
      10, "Database Systems"</a> for more information.</p>
 
+  <p>The <code>unknown_schema</code> exception is thrown by the
+     <code>odb::schema_catalog</code> class if a schema with the specified
+     name is not found. Refer to <a href="#3.3">Section 3.3, "Database"</a>
+     for details.</p>
+
   <p>The <code>odb::exception</code> class is defined in the
      <code>&lt;odb/exception.hxx></code> header file. All the
      concrete ODB exceptions are defined in
diff --git a/doc/odb-prologue.1 b/doc/odb-prologue.1
index 0eb3fb4..7610917 100644
--- a/doc/odb-prologue.1
+++ b/doc/odb-prologue.1
@@ -49,7 +49,9 @@ option is specified), and
 .B name-odb.cxx
 (source file). Additionally, if the
 .B --generate-schema
-option is specified and the target database supports it, the
+option is specified and the
+.B sql
+schema format is requested, the
 .B name.sql
 database schema file is generated.
 .\"
diff --git a/doc/odb-prologue.xhtml b/doc/odb-prologue.xhtml
index d3edc41..61826e2 100644
--- a/doc/odb-prologue.xhtml
+++ b/doc/odb-prologue.xhtml
@@ -74,7 +74,7 @@
   <code><b>name-odb.cxx</b></code> (source file).
 
   Additionally, if the <code><b>--generate-schema</b></code> option is
-  specified and the target database supports it, the <code><b>name.sql</b></code> database
-  schema file is generated.</p>
+  specified and the <code><b>sql</b></code> schema format is requested,
+  the <code><b>name.sql</b></code> database schema file is generated.</p>
 
   <h1>OPTIONS</h1>