diff options
Diffstat (limited to 'doc/manual.xhtml')
| -rw-r--r-- | doc/manual.xhtml | 100 |
1 files changed, 98 insertions, 2 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<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 <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><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&, const std::string& 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 table</code>, <code>db column</code>, + and <code>db 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& + 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><odb/exception.hxx></code> header file. All the concrete ODB exceptions are defined in |