From fe69d94f3d2dcb37d69ac2d7a0f88ad5fce2ad5c Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 1 Mar 2011 11:56:33 +0200 Subject: Add support for embedded database schemas New options: --schema-format, --default-schema. New example: schema/embedded. --- doc/manual.xhtml | 100 ++++++++++++++++++++++++++++++++++++++++++++++++- doc/odb-prologue.1 | 4 +- doc/odb-prologue.xhtml | 4 +- 3 files changed, 103 insertions(+), 5 deletions(-) (limited to 'doc') 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

The above command will log in to a local MySQL server as user odb_test without a password and use the database - named odb_test. Note that after executing this + named odb_test. Beware that after executing this command, all the data stored in the odb_test database will be deleted.

+

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 + Section 3.3, "Database" for details.

+

Once the database schema is ready, we run our application using the same login and database name:

@@ -1916,6 +1922,80 @@ auto_ptr<odb::database> db ( system-specific database classes, refer to Chapter 10, "Database Systems".

+

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.

+ +

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 (--generate-schema option). The ODB + compiler can generate the schema either as a standalone SQL file or + embedded into the generated C++ code (--schema-format + 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.

+ +

Alternatively, the schema can be embedded directly into the generated + code and we can use the odb::schema_catalog class to + create it in the database from within our application, + for example:

+ + 
+#include <odb/schema-catalog.hxx>
+
+odb::transaction t (db->begin ());
+odb::schema_catalog::create_schema (*db);
+t.commit ();
+
+ +

Refer to the next section for information on the + odb::transaction class. The complete version of the above + code fragment is available in the schema/embedded example in + the odb-examples package.

+ +

The odb::schema_catalog class has the following interface. + You will need to include the <odb/schema-catalog.hxx> + header file to make this class available in your application.

+ + 
+namespace odb
+{
+  class schema_catalog
+  {
+  public:
+    static void
+    create_schema (database&, const std::string& name = "");
+  };
+}
+
+ +

The first argument to the create_schema() 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 + --default-schema ODB compiler option to assign + custom schema names and then use these names as a second argument + to create_schema(). If the schema is not found, + create_schema() throws the + odb::unknown_schema exception. The + create_schema() function should be called within + a transaction.

+ +

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 db table, db column, + and db type (Chapter 9, "ODB Pragma + Language"). For sample code that shows how to perform such mapping + for various C++ constructs, refer to the schema/custom + example in the odb-examples package.

+

3.4 Transactions

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 (); + }; } @@ -2663,11 +2754,16 @@ namespace odb the query result class. Refer to Section 4.4, "Query Result" for details.

-

The database_exception is a base class for all +

The database_exception exception is a base class for all database system-specific exceptions that are thrown by the database system-specific runtime library. See Chapter 10, "Database Systems" for more information.

+

The unknown_schema exception is thrown by the + odb::schema_catalog class if a schema with the specified + name is not found. Refer to Section 3.3, "Database" + for details.

+

The odb::exception class is defined in the <odb/exception.hxx> 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 @@ name-odb.cxx (source file). Additionally, if the --generate-schema option is - specified and the target database supports it, the name.sql database - schema file is generated.

+ specified and the sql schema format is requested, + the name.sql database schema file is generated.

OPTIONS

-- cgit v1.1