From 4ac9fb445ba8203f3690dec6199ae5153bad0e14 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 18 Jan 2013 15:56:37 +0200 Subject: Document transaction callbacks --- doc/manual.xhtml | 646 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 411 insertions(+), 235 deletions(-) (limited to 'doc') diff --git a/doc/manual.xhtml b/doc/manual.xhtml index f36ad9b..22b68bf 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -577,17 +577,25 @@ for consistency. + 13Advanced Techniques and Mechanisms + + +
13.1Transaction Callbacks
+ + + + PART II DATABASE SYSTEMS - 13Multi-Database Support + 14Multi-Database Support - + - @@ -596,124 +604,124 @@ for consistency. - - - - - @@ -723,35 +731,35 @@ for consistency. - + -
13.1Static Multi-Database Support
14.1Static Multi-Database Support
13.2Dynamic Multi-Database Support + 14.2Dynamic Multi-Database Support - +
13.2.213.2.2 Dynamic Loading of Database Support Code
14.2.214.2.2 Dynamic Loading of Database Support Code
14MySQL Database + 15MySQL Database - - - - + + + + - - +
14.1MySQL Type Mapping
14.2MySQL Database Class
14.3MySQL Connection and Connection Factory
14.4MySQL Exceptions
15.1MySQL Type Mapping
15.2MySQL Database Class
15.3MySQL Connection and Connection Factory
15.4MySQL Exceptions
14.5MySQL Limitations + 15.5MySQL Limitations - +
14.5.1Foreign Key Constraints
15.5.1Foreign Key Constraints
14.6MySQL Index Definition
15.6MySQL Index Definition
15SQLite Database + 16SQLite Database - - - - + + + + - - +
15.1SQLite Type Mapping
15.2SQLite Database Class
15.3SQLite Connection and Connection Factory
15.4SQLite Exceptions
16.1SQLite Type Mapping
16.2SQLite Database Class
16.3SQLite Connection and Connection Factory
16.4SQLite Exceptions
15.5SQLite Limitations + 16.5SQLite Limitations - - - - - + + + + +
15.5.1Query Result Caching
15.5.2Automatic Assignment of Object Ids
15.5.3Foreign Key Constraints
15.5.4Constraint Violations
15.5.5Sharing of Queries
16.5.1Query Result Caching
16.5.2Automatic Assignment of Object Ids
16.5.3Foreign Key Constraints
16.5.4Constraint Violations
16.5.5Sharing of Queries
15.6SQLite Index Definition
16.6SQLite Index Definition
16PostgreSQL Database + 17PostgreSQL Database - - - - + + + + - - +
16.1PostgreSQL Type Mapping
16.2PostgreSQL Database Class
16.3PostgreSQL Connection and Connection Factory
16.4PostgreSQL Exceptions
17.1PostgreSQL Type Mapping
17.2PostgreSQL Database Class
17.3PostgreSQL Connection and Connection Factory
17.4PostgreSQL Exceptions
16.5PostgreSQL Limitations + 17.5PostgreSQL Limitations - - - - - - + + + + + +
16.5.1Query Result Caching
16.5.2Foreign Key Constraints
16.5.3Unique Constraint Violations
16.5.4Date-Time Format
16.5.5Timezones
16.5.6NUMERIC Type Support
17.5.1Query Result Caching
17.5.2Foreign Key Constraints
17.5.3Unique Constraint Violations
17.5.4Date-Time Format
17.5.5Timezones
17.5.6NUMERIC Type Support
16.6PostgreSQL Index Definition
17.6PostgreSQL Index Definition
17Oracle Database + 18Oracle Database - - - - + + + + - - +
17.1Oracle Type Mapping
17.2Oracle Database Class
17.3Oracle Connection and Connection Factory
17.4Oracle Exceptions
18.1Oracle Type Mapping
18.2Oracle Database Class
18.3Oracle Connection and Connection Factory
18.4Oracle Exceptions
17.5Oracle Limitations + 18.5Oracle Limitations - - - - - - - - + + + + + + + +
17.5.1Identifier Truncation
17.5.2Query Result Caching
17.5.3Foreign Key Constraints
17.5.4Unique Constraint Violations
17.5.5Large FLOAT and NUMBER Types
17.5.6Timezones
17.5.7LONG Types
17.5.8LOB Types and By-Value Accessors/Modifiers
18.5.1Identifier Truncation
18.5.2Query Result Caching
18.5.3Foreign Key Constraints
18.5.4Unique Constraint Violations
18.5.5Large FLOAT and NUMBER Types
18.5.6Timezones
18.5.7LONG Types
18.5.8LOB Types and By-Value Accessors/Modifiers
17.6Oracle Index Definition
18.6Oracle Index Definition
18Microsoft SQL Server Database + 19Microsoft SQL Server Database - - - - + + + - - +
18.1SQL Server Type Mapping + 19.1SQL Server Type Mapping - +
18.1.1ROWVERSION Support
19.1.1ROWVERSION Support
18.2SQL Server Database Class
18.3SQL Server Connection and Connection Factory
18.4SQL Server Exceptions
19.2SQL Server Database Class
19.3SQL Server Connection and Connection Factory
19.4SQL Server Exceptions
18.5SQL Server Limitations + 19.5SQL Server Limitations - - - - - - - + + + + + + +
18.5.1Query Result Caching
18.5.2Foreign Key Constraints
18.5.3Unique Constraint Violations
18.5.4Multi-threaded Windows Applications
18.5.5Affected Row Count and DDL Statements
18.5.6Long Data and Auto Object Ids, ROWVERSION
18.5.7Long Data and By-Value Accessors/Modifiers
19.5.1Query Result Caching
19.5.2Foreign Key Constraints
19.5.3Unique Constraint Violations
19.5.4Multi-threaded Windows Applications
19.5.5Affected Row Count and DDL Statements
19.5.6Long Data and Auto Object Ids, ROWVERSION
19.5.7Long Data and By-Value Accessors/Modifiers
18.6SQL Server Index Definition
19.6SQL Server Index Definition
19Profiles Introduction20Profiles Introduction
20Boost Profile + 21Boost Profile - - - - + + + + - - @@ -760,29 +768,29 @@ for consistency. -
20.1Smart Pointers Library
20.2Unordered Containers Library
20.3Multi-Index Container Library
20.4Optional Library
21.1Smart Pointers Library
21.2Unordered Containers Library
21.3Multi-Index Container Library
21.4Optional Library
20.5Date Time Library + 21.5Date Time Library - - - - - + + + + +
20.5.1MySQL Database Type Mapping
20.5.2SQLite Database Type Mapping
20.5.3PostgreSQL Database Type Mapping
20.5.4Oracle Database Type Mapping
20.5.5SQL Server Database Type Mapping
21.5.1MySQL Database Type Mapping
21.5.2SQLite Database Type Mapping
21.5.3PostgreSQL Database Type Mapping
21.5.4Oracle Database Type Mapping
21.5.5SQL Server Database Type Mapping
20.6Uuid Library + 21.6Uuid Library - - - - - + + + + +
20.6.1MySQL Database Type Mapping
20.6.2SQLite Database Type Mapping
20.6.3PostgreSQL Database Type Mapping
20.6.4Oracle Database Type Mapping
20.6.5SQL Server Database Type Mapping
21.6.1MySQL Database Type Mapping
21.6.2SQLite Database Type Mapping
21.6.3PostgreSQL Database Type Mapping
21.6.4Oracle Database Type Mapping
21.6.5SQL Server Database Type Mapping
21Qt Profile + 22Qt Profile - - - + + - @@ -1551,7 +1559,7 @@ main (int argc, char* argv[]) database name, etc., from the command line. In your own applications you may prefer to use other mysql::database constructors which allow you to pass this information directly - (Section 14.2, "MySQL Database Class").

+ (Section 15.2, "MySQL Database Class").

Next, we create three person objects. Right now they are transient objects, which means that if we terminate the application @@ -2083,7 +2091,7 @@ odb::mysql::database db2 ("john", "secret", "test_db2"); tight integration with specific database systems to being able to write database-agnostic code and loading individual database systems support dynamically. While all these aspects are covered in detail - in Chapter 13, "Multi-Database Support", in this + in Chapter 14, "Multi-Database Support", in this section we will get a taste of this functionality by extending our "Hello World" example to be able to store its data either in MySQL or PostgreSQL (other database systems supported by ODB can be added @@ -2100,8 +2108,8 @@ odb --multi-database dynamic -d common -d mysql -d pgsql \

The --multi-database ODB compiler option turns on multi-database support. For now it is not important what the - dynamic value that we passed to this option means, - but if you are curious, see Chapter 13. The result of this + dynamic value that we passed to this option means, but + if you are curious, see Chapter 14. The result of this command are three sets of generated files: person-odb.?xx (common interface; corresponds to the common database), person-odb-mysql.?xx (MySQL support code), and @@ -2925,6 +2933,10 @@ namespace odb static bool reset_current (); + + // Callback API. + // + ... }; } @@ -3014,6 +3026,9 @@ for (size_t i (0); i < n; ++i) t.commit (); +

For more information on the transaction callback support, refer + to Section 13.1, "Transaction Callbacks".

+

Note that in the above discussion of atomicity, consistency, isolation, and durability, all of those guarantees only apply to the object's state in the database as opposed to the object's @@ -3091,6 +3106,9 @@ update_age (database& db, person& p) } +

See also Section 13.1, "Transaction Callbacks" + for an alternative approach.

+

3.6 Connections

The odb::connection class represents a connection @@ -7393,7 +7411,7 @@ namespace odb consider using a more efficient implementation of the optional value concept such as the optional class template from Boost - (Section 20.4, "Optional Library").

+ (Section 21.4, "Optional Library").

Another common C++ representation of a value that can be NULL is a pointer. ODB will automatically @@ -13880,6 +13898,164 @@ class person + + + +

+

13 Advanced Techniques and Mechanisms

+ +

This chapter covers more advanced techniques and mechanisms + provided by ODB that may be useful in certain situations.

+ +

13.1 Transaction Callbacks

+ +

The ODB transaction class (odb::transaction) allows + an application to register a callback that will be called after + the transaction is finalized, that is, committed or rolled back. + This mechanism can be used, for example, to restore values that + were updated during the transaction execution to their original + states if the transaction is rolled back.

+ +

The callback management interface of the transaction + class is shown below.

+ + 
+namespace odb
+{
+  class transaction
+  {
+    ...
+
+  public:
+    static const unsigned short event_commit = 0x01;
+    static const unsigned short event_rollback = 0x02;
+    static const unsigned short event_all = event_commit | event_rollback;
+
+    typedef void (*callback_type) (
+      unsigned short event, void* key, unsigned long long data);
+
+    void
+    register_ (callback_type callback,
+               void* key,
+               unsigned short event = event_all,
+               unsigned long long data = 0,
+               transaction** state = 0);
+
+
+    void
+    unregister (void* key);
+  }
+}
+
+ +

The register_() function registers a + post-commit/rollback callback. The callback + argument is the function that should be called. The + key argument is used by the transaction + to identify this callback. It is also normally used + to pass an address of the data object on which the + callback function will work. The event + argument is the bitwise-or of the events that should + trigger the callback.

+ +

The optional data argument can be used to store any POD + user data that doesn't exceed 8 bytes in size and doesn't require + alignment greater than unsigned long long. For + example, we could store an old value of a flag or a counter + that needs to be restored in case of a roll back.

+ +

The optional state argument can be used to + indicate that the callback has been unregistered because + the transaction was finalized. In this case the transaction + automatically resets the passed pointer to 0. This is + primarily useful if we are interested in only one of + the events (commit or rollback).

+ +

The unregister() function unregisters a previously + registered callback. If the number of registered callbacks is + large, then this can be a slow operation. Generally, the callback + mechanism is optimized for cases where the callbacks stay + registered until the transaction is finalized.

+ +

Note also that you don't need to unregister a callback that has + been called or auto-reset using the state argument + passed to register_(). This function does nothing + if the key is not found.

+ +

When the callback is called, it is passed the event that + triggered it, as well as the key and + data values that were passed to the + register_() function. Note also that the order + in which the callbacks are called is unspecified. The rollback + event can be triggered by an exception. In this case, if the + callback throws, the program will be terminated.

+ +

The following example shows how we can use transaction + callbacks together with database operation callbacks + (Section 12.1.7, "callback") + to manage the object's "dirty" flag.

+ + 
+#include <odb/callback.hxx>
+#include <odb/transaction.hxx>
+
+#pragma db object callback(update)
+class object
+{
+  ...
+
+  #pragma db transient
+  mutable bool dirty_;
+
+  // Non-NULL value indicates that we are registered
+  // with this transaction.
+  //
+  #pragma db transient
+  mutable odb::transaction* tran_;
+
+  void
+  update (odb::callback_event e, odb::database&) const
+  {
+    using namespace odb::core;
+
+    if (e == callback_event::post_update)
+      return;
+
+    // Mark the object as clean again but register a
+    // transaction callback in case the update is rolled
+    // back.
+    //
+    tran_ = &transaction::current ();
+    tran_->register_ (&rollback,
+                      const_cast<object*> (this),
+                      transaction::event_rollback,
+                      0,
+                      &tran_);
+    dirty_ = false;
+  }
+
+  static void
+  rollback (unsigned short, void* key, unsigned long long)
+  {
+    // Restore the dirty flag since the changes have been
+    // rolled back.
+    //
+    object& o (*static_cast<object*> (key));
+    o.dirty_ = true;
+  }
+
+  ~object ()
+  {
+    // Unregister the callback if we are going away before
+    // the transaction.
+    //
+    if (tran_ != 0)
+      tran_->unregister (this);
+  }
+};
+
+ + @@ -13896,12 +14072,12 @@ class person II consists of the following chapters.

21.1Basic Types Library + 22.1Basic Types Library - - - - - + + + + +
21.1.1MySQL Database Type Mapping
21.1.2SQLite Database Type Mapping
21.1.3PostgreSQL Database Type Mapping
21.1.4Oracle Database Type Mapping
21.1.5SQL Server Database Type Mapping
22.1.1MySQL Database Type Mapping
22.1.2SQLite Database Type Mapping
22.1.3PostgreSQL Database Type Mapping
22.1.4Oracle Database Type Mapping
22.1.5SQL Server Database Type Mapping
21.2Smart Pointers Library
21.3Containers Library
22.2Smart Pointers Library
22.3Containers Library
21.4Date Time Library + 22.4Date Time Library - - - - - + + + + +
21.4.1MySQL Database Type Mapping
21.4.2SQLite Database Type Mapping
21.4.3PostgreSQL Database Type Mapping
21.4.4Oracle Database Type Mapping
21.4.5SQL Server Database Type Mapping
22.4.1MySQL Database Type Mapping
22.4.2SQLite Database Type Mapping
22.4.3PostgreSQL Database Type Mapping
22.4.4Oracle Database Type Mapping
22.4.5SQL Server Database Type Mapping
- - - - - - + + + + + +
13Multi-Database Support
14MySQL Database
15SQLite Database
16PostgreSQL Database
17Oracle Database
18Microsoft SQL Server Database
14Multi-Database Support
15MySQL Database
16SQLite Database
17PostgreSQL Database
18Oracle Database
19Microsoft SQL Server Database
@@ -13909,7 +14085,7 @@ class person
-

13 Multi-Database Support

+

14 Multi-Database Support

Some applications may need to access multiple database systems, either simultaneously or one at a time. For example, an application may @@ -13970,7 +14146,7 @@ class person separate libraries and loaded dynamically by the application. The disadvantages of dynamic support are slight overhead and certain limitations in functionality compared to static support (see - Section 13.2, "Dynamic Multi-Database Support" + Section 14.2, "Dynamic Multi-Database Support" for details). As a result, dynamic multi-database support is most suitable to situations where we need the same code to work with a range of database systems. For example, if your @@ -14100,7 +14276,7 @@ odb --odb-file-suffix common:-odb-common ... support in more detail.

-

13.1 Static Multi-Database Support

+

14.1 Static Multi-Database Support

With static multi-database support, instead of including person-odb.hxx, application source code has @@ -14272,7 +14448,7 @@ odb -m static -d common -d pgsql -d sqlite --default-database pgsql ... support is enabled, then the common (dynamic) interface is always made the default database.

-

13.2 Dynamic Multi-Database Support

+

14.2 Dynamic Multi-Database Support

With dynamic multi-database support, application source code only needs to include the person-odb.hxx header file, just @@ -14443,7 +14619,7 @@ namespace odb expression). Every odb::<db>::query class provides such a translation constructor.

-

13.2.2 Dynamic Loading of Database Support Code

+

14.2.2 Dynamic Loading of Database Support Code

With dynamic multi-database support, the generated database support code automatically registers itself with the function tables that @@ -14621,7 +14797,7 @@ person.hxx

-

14 MySQL Database

+

15 MySQL Database

To generate support code for the MySQL database you will need to pass the "--database mysql" @@ -14630,7 +14806,7 @@ person.hxx library (libodb-mysql). All MySQL-specific ODB classes are defined in the odb::mysql namespace.

-

14.1 MySQL Type Mapping

+

15.1 MySQL Type Mapping

The following table summarizes the default mapping between basic C++ value types and MySQL database types. This mapping can be @@ -14823,7 +14999,7 @@ class object Section 12.7, "Database Type Mapping Pragmas".

-

14.2 MySQL Database Class

+

15.2 MySQL Database Class

The MySQL database class has the following interface:

@@ -14983,7 +15159,7 @@ namespace odb

This constructor throws the odb::mysql::cli_exception exception if the MySQL option values are missing or invalid. - See section Section 14.4, "MySQL Exceptions" + See section Section 15.4, "MySQL Exceptions" for more information on this exception.

The static print_usage() function prints the list of options @@ -15002,10 +15178,10 @@ namespace odb

The connection() function returns a pointer to the MySQL database connection encapsulated by the odb::mysql::connection class. For more information - on mysql::connection, refer to Section - 14.3, "MySQL Connection and Connection Factory".

+ on mysql::connection, refer to Section + 15.3, "MySQL Connection and Connection Factory".

-

14.3 MySQL Connection and Connection Factory

+

15.3 MySQL Connection and Connection Factory

The mysql::connection class has the following interface:

@@ -15197,7 +15373,7 @@ main (int argc, char* argv[]) } -

14.4 MySQL Exceptions

+

15.4 MySQL Exceptions

The MySQL ODB runtime library defines the following MySQL-specific exceptions:

@@ -15249,12 +15425,12 @@ namespace odb what() function returns a human-readable description of an error.

-

14.5 MySQL Limitations

+

15.5 MySQL Limitations

The following sections describe MySQL-specific limitations imposed by the current MySQL and ODB runtime versions.

-

14.5.1 Foreign Key Constraints

+

15.5.1 Foreign Key Constraints

ODB relies on standard SQL behavior which requires that foreign key constraints checking is deferred until the transaction is @@ -15265,7 +15441,7 @@ namespace odb foreign key definitions commented out. They are retained only for documentation.

-

14.6 MySQL Index Definitions

+

15.6 MySQL Index Definitions

When the index pragma (Section 12.6, "Index Definition Pragmas") is used to define a MySQL index, @@ -15294,7 +15470,7 @@ class object

-

15 SQLite Database

+

16 SQLite Database

To generate support code for the SQLite database you will need to pass the "--database sqlite" @@ -15303,7 +15479,7 @@ class object library (libodb-sqlite). All SQLite-specific ODB classes are defined in the odb::sqlite namespace.

-

15.1 SQLite Type Mapping

+

16.1 SQLite Type Mapping

The following table summarizes the default mapping between basic C++ value types and SQLite database types. This mapping can be @@ -15481,7 +15657,7 @@ class object Section 12.7, "Database Type Mapping Pragmas".

-

15.2 SQLite Database Class

+

16.2 SQLite Database Class

The SQLite database class has the following interface:

@@ -15554,7 +15730,7 @@ namespace odb values, refer to the sqlite3_open_v2() function description in the SQLite C API documentation. The foreign_keys argument specifies whether foreign key constraints checking - should be enabled. See Section 15.5.3, + should be enabled. See Section 16.5.3, "Foreign Key Constraints" for more information on foreign keys. The vfs argument specifies the SQLite virtual file system module that should be used to access the @@ -15610,7 +15786,7 @@ auto_ptr<odb::database> db (

The third constructor throws the odb::sqlite::cli_exception exception if the SQLite option values are missing or invalid. - See Section 15.4, "SQLite Exceptions" + See Section 16.4, "SQLite Exceptions" for more information on this exception.

The static print_usage() function prints the list of options @@ -15639,10 +15815,10 @@ auto_ptr<odb::database> db (

The connection() function returns a pointer to the SQLite database connection encapsulated by the odb::sqlite::connection class. For more information - on sqlite::connection, refer to Section - 15.3, "SQLite Connection and Connection Factory".

+ on sqlite::connection, refer to Section + 16.3, "SQLite Connection and Connection Factory".

-

15.3 SQLite Connection and Connection Factory

+

16.3 SQLite Connection and Connection Factory

The sqlite::connection class has the following interface:

@@ -15687,7 +15863,7 @@ namespace odb functions allow us to start an immediate and an exclusive SQLite transaction on the connection, respectively. Their semantics are equivalent to the corresponding functions defined in the - sqlite::database class (Section 15.2, + sqlite::database class (Section 16.2, "SQLite Database Class"). The handle() accessor returns the SQLite handle corresponding to the connection.

@@ -15887,7 +16063,7 @@ main (int argc, char* argv[]) } -

15.4 SQLite Exceptions

+

16.4 SQLite Exceptions

The SQLite ODB runtime library defines the following SQLite-specific exceptions:

@@ -15940,12 +16116,12 @@ namespace odb of an error.

-

15.5 SQLite Limitations

+

16.5 SQLite Limitations

The following sections describe SQLite-specific limitations imposed by the current SQLite and ODB runtime versions.

-

15.5.1 Query Result Caching

+

16.5.1 Query Result Caching

SQLite ODB runtime implementation does not perform query result caching (Section 4.4, "Query Result") even when explicitly @@ -15960,7 +16136,7 @@ namespace odb thrown. Future versions of the SQLite ODB runtime library may add support for result caching.

-

15.5.2 Automatic Assignment of Object Ids

+

16.5.2 Automatic Assignment of Object Ids

Due to SQLite API limitations, every automatically assigned object id (Section 12.4.2, "auto") should have @@ -15986,7 +16162,7 @@ class person }; -

15.5.3 Foreign Key Constraints

+

16.5.3 Foreign Key Constraints

By default the SQLite ODB runtime enables foreign key constraints checking (PRAGMA foreign_keys=ON). You can disable foreign @@ -16050,7 +16226,7 @@ CREATE TABLE Employee ( -

15.5.4 Constraint Violations

+

16.5.4 Constraint Violations

Due to the granularity of the SQLite error codes, it is impossible to distinguish between the duplicate primary key and other constraint @@ -16059,7 +16235,7 @@ CREATE TABLE Employee ( object_already_persistent exception (Section 3.14, "ODB Exceptions").

-

15.5.5 Sharing of Queries

+

16.5.5 Sharing of Queries

As discussed in Section 4.3, "Executing a Query", a query instance that does not have any by-reference parameters is @@ -16068,7 +16244,7 @@ CREATE TABLE Employee ( functionality. Future versions of the library will remove this limitation.

-

15.6 SQLite Index Definitions

+

16.6 SQLite Index Definitions

When the index pragma (Section 12.6, "Index Definition Pragmas") is used to define an SQLite index, @@ -16097,7 +16273,7 @@ class object

-

16 PostgreSQL Database

+

17 PostgreSQL Database

To generate support code for the PostgreSQL database you will need to pass the "--database pgsql" @@ -16111,7 +16287,7 @@ class object of the messaging protocol version 3.0. For this reason, ODB supports only PostgreSQL version 7.4 and later.

-

16.1 PostgreSQL Type Mapping

+

17.1 PostgreSQL Type Mapping

The following table summarizes the default mapping between basic C++ value types and PostgreSQL database types. This mapping can be @@ -16289,7 +16465,7 @@ class object For more information, refer to Section 12.7, "Database Type Mapping Pragmas".

-

16.2 PostgreSQL Database Class

+

17.2 PostgreSQL Database Class

The PostgreSQL database class has the following interface:

@@ -16409,7 +16585,7 @@ namespace odb

This constructor throws the odb::pgsql::cli_exception exception if the PostgreSQL option values are missing or invalid. - See section Section 16.4, "PostgreSQL Exceptions" + See section Section 17.4, "PostgreSQL Exceptions" for more information on this exception.

The static print_usage() function prints the list of options @@ -16435,10 +16611,10 @@ namespace odb

The connection() function returns a pointer to the PostgreSQL database connection encapsulated by the odb::pgsql::connection class. For more information - on pgsql::connection, refer to Section - 16.3, "PostgreSQL Connection and Connection Factory".

+ on pgsql::connection, refer to Section + 17.3, "PostgreSQL Connection and Connection Factory".

-

16.3 PostgreSQL Connection and Connection Factory

+

17.3 PostgreSQL Connection and Connection Factory

The pgsql::connection class has the following interface:

@@ -16619,7 +16795,7 @@ main (int argc, char* argv[]) } -

16.4 PostgreSQL Exceptions

+

17.4 PostgreSQL Exceptions

The PostgreSQL ODB runtime library defines the following PostgreSQL-specific exceptions:

@@ -16668,12 +16844,12 @@ namespace odb what() function returns a human-readable description of an error.

-

16.5 PostgreSQL Limitations

+

17.5 PostgreSQL Limitations

The following sections describe PostgreSQL-specific limitations imposed by the current PostgreSQL and ODB runtime versions.

-

16.5.1 Query Result Caching

+

17.5.1 Query Result Caching

The PostgreSQL ODB runtime implementation will always return a cached query result (Section 4.4, "Query Result") @@ -16681,7 +16857,7 @@ namespace odb PostgreSQL client library (libpq) which does not support uncached (streaming) query results.

-

16.5.2 Foreign Key Constraints

+

17.5.2 Foreign Key Constraints

ODB relies on standard SQL behavior which requires that foreign key constraints checking is deferred until the @@ -16699,7 +16875,7 @@ CREATE TABLE Employee ( employer BIGINT REFERENCES Employer(id) INITIALLY DEFERRED); -

16.5.3 Unique Constraint Violations

+

17.5.3 Unique Constraint Violations

Due to the granularity of the PostgreSQL error codes, it is impossible to distinguish between the duplicate primary key and other unique @@ -16708,7 +16884,7 @@ CREATE TABLE Employee ( errors to the object_already_persistent exception (Section 3.14, "ODB Exceptions").

-

16.5.4 Date-Time Format

+

17.5.4 Date-Time Format

ODB expects the PostgreSQL server to use integers as a binary format for the date-time types, which is the default for most @@ -16723,14 +16899,14 @@ CREATE TABLE Employee ( SHOW integer_datetimes -

16.5.5 Timezones

+

17.5.5 Timezones

ODB does not currently natively support the PostgreSQL date-time types with timezone information. However, these types can be accessed by mapping them to one of the natively supported types, as discussed in Section 12.7, "Database Type Mapping Pragmas".

-

16.5.6 NUMERIC Type Support

+

17.5.6 NUMERIC Type Support

Support for the PostgreSQL NUMERIC type is limited to providing a binary buffer containing the binary representation @@ -16742,7 +16918,7 @@ SHOW integer_datetimes Type Mapping Pragmas".

-

16.6 PostgreSQL Index Definitions

+

17.6 PostgreSQL Index Definitions

When the index pragma (Section 12.6, "Index Definition Pragmas") is used to define a PostgreSQL index, @@ -16781,7 +16957,7 @@ class object

-

17 Oracle Database

+

18 Oracle Database

To generate support code for the Oracle database you will need to pass the "--database oracle" @@ -16790,7 +16966,7 @@ class object library (libodb-oracle). All Oracle-specific ODB classes are defined in the odb::oracle namespace.

-

17.1 Oracle Type Mapping

+

18.1 Oracle Type Mapping

The following table summarizes the default mapping between basic C++ value types and Oracle database types. This mapping can be @@ -16965,7 +17141,7 @@ class object Section 12.7, "Database Type Mapping Pragmas".

-

17.2 Oracle Database Class

+

18.2 Oracle Database Class

The Oracle database class encapsulates the OCI environment handle as well as the database connection string and user credentials @@ -17090,7 +17266,7 @@ namespace odb

This constructor throws the odb::oracle::cli_exception exception if the Oracle option values are missing or invalid. See section - Section 17.4, "Oracle Exceptions" for more + Section 18.4, "Oracle Exceptions" for more information on this exception.

The static print_usage() function prints the list of options @@ -17140,10 +17316,10 @@ namespace odb

The connection() function returns a pointer to the Oracle database connection encapsulated by the odb::oracle::connection class. For more information - on oracle::connection, refer to Section - 17.3, "Oracle Connection and Connection Factory".

+ on oracle::connection, refer to Section + 18.3, "Oracle Connection and Connection Factory".

-

17.3 Oracle Connection and Connection Factory

+

18.3 Oracle Connection and Connection Factory

The oracle::connection class has the following interface:

@@ -17345,7 +17521,7 @@ main (int argc, char* argv[]) } -

17.4 Oracle Exceptions

+

18.4 Oracle Exceptions

The Oracle ODB runtime library defines the following Oracle-specific exceptions:

@@ -17426,12 +17602,12 @@ namespace odb condition. The what() function returns a human-readable description of an error.

-

17.5 Oracle Limitations

+

18.5 Oracle Limitations

The following sections describe Oracle-specific limitations imposed by the current Oracle and ODB runtime versions.

-

17.5.1 Identifier Truncation

+

18.5.1 Identifier Truncation

Oracle limits the length of database identifiers (table, column, etc., names) to 30 characters. The ODB compiler automatically truncates @@ -17476,7 +17652,7 @@ class long_class_name }; -

17.5.2 Query Result Caching

+

18.5.2 Query Result Caching

Oracle ODB runtime implementation does not perform query result caching (Section 4.4, "Query Result") even when explicitly @@ -17491,7 +17667,7 @@ class long_class_name always thrown. Future versions of the Oracle ODB runtime library may add support for result caching.

-

17.5.3 Foreign Key Constraints

+

18.5.3 Foreign Key Constraints

ODB relies on standard SQL behavior which requires that foreign key constraints checking is deferred until the @@ -17510,7 +17686,7 @@ CREATE TABLE Employee ( DEFERRABLE INITIALLY DEFERRED); -

17.5.4 Unique Constraint Violations

+

18.5.4 Unique Constraint Violations

Due to the granularity of the Oracle error codes, it is impossible to distinguish between the duplicate primary key and other unique @@ -17519,7 +17695,7 @@ CREATE TABLE Employee ( errors to the object_already_persistent exception (Section 3.14, "ODB Exceptions").

-

17.5.5 Large FLOAT and +

18.5.5 Large FLOAT and NUMBER Types

The Oracle FLOAT type with a binary precision greater @@ -17545,21 +17721,21 @@ CREATE TABLE Employee ( without any range and scale) can be extracted into the C++ float and double types.

-

17.5.6 Timezones

+

18.5.6 Timezones

ODB does not currently support the Oracle date-time types with timezone information. However, these types can be accessed by mapping them to one of the natively supported types, as discussed in Section 12.7, "Database Type Mapping Pragmas".

-

17.5.7 LONG Types

+

18.5.7 LONG Types

ODB does not support the deprecated Oracle LONG and LONG RAW data types. However, these types can be accessed by mapping them to one of the natively supported types, as discussed in Section 12.7, "Database Type Mapping Pragmas".

-

17.5.8 LOB Types and By-Value Accessors/Modifiers

+

18.5.8 LOB Types and By-Value Accessors/Modifiers

As discussed in Section 12.4.5, "get/set/access", by-value @@ -17570,7 +17746,7 @@ CREATE TABLE Employee ( data members. As a result, by-reference accessors and modifiers should be used for these data types.

-

17.6 Oracle Index Definitions

+

18.6 Oracle Index Definitions

When the index pragma (Section 12.6, "Index Definition Pragmas") is used to define an Oracle index, @@ -17604,7 +17780,7 @@ class object

-

18 Microsoft SQL Server Database

+

19 Microsoft SQL Server Database

To generate support code for the SQL Server database you will need to pass the "--database mssql" @@ -17613,7 +17789,7 @@ class object library (libodb-mssql). All SQL Server-specific ODB classes are defined in the odb::mssql namespace.

-

18.1 SQL Server Type Mapping

+

19.1 SQL Server Type Mapping

The following table summarizes the default mapping between basic C++ value types and SQL Server database types. This mapping can be @@ -17822,7 +17998,7 @@ class object than once as part of a query result iteration (Section 4.4, "Query Result"). Any such attempt will result in the odb::mssql::long_data_reload exception - (Section 18.4, "SQL Server Exceptions"). For + (Section 19.4, "SQL Server Exceptions"). For example:

@@ -17880,7 +18056,7 @@ t.commit ();
      For more information, refer to Section 12.7, "Database
      Type Mapping Pragmas".

 
-  
18.1.1 ROWVERSION Support

+  
19.1.1 ROWVERSION Support

 
   
ROWVERSION is a special SQL Server data type that is
      automatically incremented by the database server whenever a row
@@ -17909,7 +18085,7 @@ class person
 };
-

18.2 SQL Server Database Class

+

19.2 SQL Server Database Class

The SQL Server database class encapsulates the ODBC environment handle as well as the server instance address and @@ -18206,7 +18382,7 @@ odb::mssql::database dbA ("test",

This constructor throws the odb::mssql::cli_exception exception if the SQL Server option values are missing or invalid. See - section Section 18.4, "SQL Server Exceptions" for + section Section 19.4, "SQL Server Exceptions" for more information on this exception.

The static print_usage() function prints the list of options @@ -18237,10 +18413,10 @@ odb::mssql::database dbA ("test",

The connection() function returns a pointer to the SQL Server database connection encapsulated by the odb::mssql::connection class. For more information - on mssql::connection, refer to Section - 18.3, "SQL Server Connection and Connection Factory".

+ on mssql::connection, refer to Section + 19.3, "SQL Server Connection and Connection Factory".

-

18.3 SQL Server Connection and Connection Factory

+

19.3 SQL Server Connection and Connection Factory

The mssql::connection class has the following interface:

@@ -18435,7 +18611,7 @@ main (int argc, char* argv[]) } -

18.4 SQL Server Exceptions

+

19.4 SQL Server Exceptions

The SQL Server ODB runtime library defines the following SQL Server-specific exceptions:

@@ -18516,14 +18692,14 @@ namespace odb

The odb::mssql::long_data_reload is thrown if an attempt is made to re-load an object or view with long data as part of a query result iteration. For more information, refer - to Section 18.1, "SQL Server Type Mapping".

+ to Section 19.1, "SQL Server Type Mapping".

-

18.5 SQL Server Limitations

+

19.5 SQL Server Limitations

The following sections describe SQL Server-specific limitations imposed by the current SQL Server and ODB runtime versions.

-

18.5.1 Query Result Caching

+

19.5.1 Query Result Caching

SQL Server ODB runtime implementation does not perform query result caching (Section 4.4, "Query Result") even when @@ -18538,7 +18714,7 @@ namespace odb 3.14, "ODB Exceptions") is always thrown. Future versions of the SQL Server ODB runtime library may add support for result caching.

-

18.5.2 Foreign Key Constraints

+

19.5.2 Foreign Key Constraints

ODB relies on standard SQL behavior which requires that foreign key constraints checking is deferred until the transaction is @@ -18547,7 +18723,7 @@ namespace odb the ODB compiler for SQL Server have foreign key definitions commented out. They are retained only for documentation.

-

18.5.3 Unique Constraint Violations

+

19.5.3 Unique Constraint Violations

Due to the granularity of the ODBC error codes, it is impossible to distinguish between the duplicate primary key and other unique @@ -18556,7 +18732,7 @@ namespace odb errors to the object_already_persistent exception (Section 3.14, "ODB Exceptions").

-

18.5.4 Multi-threaded Windows Applications

+

19.5.4 Multi-threaded Windows Applications

Multi-threaded Windows applications must use the _beginthread()/_beginthreadex() and @@ -18565,7 +18741,7 @@ namespace odb Win32 functions to start and terminate threads. This is a limitation of the ODBC implementation on Windows.

-

18.5.5 Affected Row Count and DDL Statements

+

19.5.5 Affected Row Count and DDL Statements

SQL Server always returns zero as the number of affected rows for DDL statements. In particular, this means that the @@ -18573,7 +18749,7 @@ namespace odb "Executing Native SQL Statements") function will always return zero for such statements.

-

18.5.6 Long Data and Auto Object Ids, ROWVERSION

+

19.5.6 Long Data and Auto Object Ids, ROWVERSION

SQL Server 2005 has a bug that causes it to fail on an INSERT or UPDATE statement with the OUTPUT clause @@ -18583,7 +18759,7 @@ namespace odb by the database::persist() or database::update() function when used on an object that contains long data and has an automatically assigned object id or uses ROWVERSION-based - optimistic concurrency (Section 18.1.1, + optimistic concurrency (Section 19.1.1, "ROWVERSION Support"). The error message reads "This operation conflicts with another pending operation on this transaction. The operation failed."

@@ -18600,7 +18776,7 @@ namespace odb objects that use ROWVERSION for optimistic concurrency and containing long data.

-

18.5.7 Long Data and By-Value Accessors/Modifiers

+

19.5.7 Long Data and By-Value Accessors/Modifiers

As discussed in Section 12.4.5, "get/set/access", by-value @@ -18610,7 +18786,7 @@ namespace odb by-reference accessors and modifiers should be used for these data types.

-

18.6 SQL Server Index Definitions

+

19.6 SQL Server Index Definitions

When the index pragma (Section 12.6, "Index Definition Pragmas") is used to define an SQL Server index, @@ -18647,9 +18823,9 @@ class object and libraries. It consists of the following chapters.

- - - + + +
19Profiles Introduction
20Boost Profile
21Qt Profile
20Profiles Introduction
21Boost Profile
22Qt Profile
@@ -18657,7 +18833,7 @@ class object
-

19 Profiles Introduction

+

20 Profiles Introduction

ODB profiles are a generic mechanism for integrating ODB with widely-used C++ frameworks and libraries. A profile provides glue @@ -18711,7 +18887,7 @@ odb --profile boost/date-time ...

-

20 Boost Profile

+

21 Boost Profile

The ODB profile implementation for Boost is provided by the libodb-boost library and consists of multiple sub-profiles @@ -18736,7 +18912,7 @@ odb --profile boost/date-time ... that can be thrown by the Boost sub-profiles are described in the following sections.

-

20.1 Smart Pointers Library

+

21.1 Smart Pointers Library

The smart-ptr sub-profile provides persistence support for a subset of smart pointers from the Boost @@ -18806,7 +18982,7 @@ class employee this behavior, add the --default-pointer option specifying the alternative pointer type after the --profile option.

-

20.2 Unordered Containers Library

+

21.2 Unordered Containers Library

The unordered sub-profile provides persistence support for the containers from the Boost unordered library. To enable @@ -18832,7 +19008,7 @@ class person }; -

20.3 Multi-Index Container Library

+

21.3 Multi-Index Container Library

The multi-index sub-profile provides persistence support for boost::multi_index_container from the Boost Multi-Index @@ -18917,7 +19093,7 @@ class person }; -

20.4 Optional Library

+

21.4 Optional Library

The optional sub-profile provides persistence support for the boost::optional container from the Boost @@ -18949,7 +19125,7 @@ class person this profile is used, the NULL values are automatically enabled for data members of the boost::optional type.

-

20.5 Date Time Library

+

21.5 Date Time Library

The date-time sub-profile provides persistence support for a subset of types from the Boost date_time library. It is @@ -19022,7 +19198,7 @@ namespace odb exceptions are thrown are database system dependent and are discussed in more detail in the following sub-sections.

-

20.5.1 MySQL Database Type Mapping

+

21.5.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the MySQL database @@ -19083,7 +19259,7 @@ class person the out_of_range exception. Refer to the MySQL documentation for more information on the MySQL data type ranges.

-

20.5.2 SQLite Database Type Mapping

+

21.5.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the SQLite database @@ -19161,7 +19337,7 @@ class person will result in the out_of_range exception.

-

20.5.3 PostgreSQL Database Type Mapping

+

21.5.3 PostgreSQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the PostgreSQL database @@ -19212,7 +19388,7 @@ class person result in the special_value exception.

-

20.5.4 Oracle Database Type Mapping

+

21.5.4 Oracle Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the Oracle database @@ -19274,7 +19450,7 @@ class person the special_value exception.

-

20.5.5 SQL Server Database Type Mapping

+

21.5.5 SQL Server Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the SQL Server database @@ -19345,7 +19521,7 @@ class person posix_time::time_duration value out of this range will result in the value_out_of_range exception.

-

20.6 Uuid Library

+

21.6 Uuid Library

The uuid sub-profile provides persistence support for the uuid type from the Boost uuid library. To @@ -19377,7 +19553,7 @@ class object }; -

20.6.1 MySQL Database Type Mapping

+

21.6.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the Boost uuid type and the MySQL database type.

@@ -19397,7 +19573,7 @@ class object
-

20.6.2 SQLite Database Type Mapping

+

21.6.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the Boost uuid type and the SQLite database type.

@@ -19417,7 +19593,7 @@ class object
-

20.6.3 PostgreSQL Database Type Mapping

+

21.6.3 PostgreSQL Database Type Mapping

The following table summarizes the default mapping between the Boost uuid type and the PostgreSQL database type.

@@ -19437,7 +19613,7 @@ class object -

20.6.4 Oracle Database Type Mapping

+

21.6.4 Oracle Database Type Mapping

The following table summarizes the default mapping between the Boost uuid type and the Oracle database type.

@@ -19457,7 +19633,7 @@ class object -

20.6.5 SQL Server Database Type Mapping

+

21.6.5 SQL Server Database Type Mapping

The following table summarizes the default mapping between the Boost uuid type and the SQL Server database type.

@@ -19482,7 +19658,7 @@ class object
-

21 Qt Profile

+

22 Qt Profile

The ODB profile implementation for Qt is provided by the libodb-qt library and consists of multiple sub-profiles @@ -19508,7 +19684,7 @@ class object that can be thrown by the Qt sub-profiles are described in the following sections.

-

21.1 Basic Types

+

22.1 Basic Types

The basic sub-profile provides persistence support for basic types defined by Qt. To enable only this profile, pass @@ -19554,7 +19730,7 @@ class object }; -

21.1.1 MySQL Database Type Mapping

+

22.1.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the MySQL database types.

@@ -19617,7 +19793,7 @@ class Person -

21.1.2 SQLite Database Type Mapping

+

22.1.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the SQLite database types.

@@ -19653,7 +19829,7 @@ class Person are stored as a NULL value if their isNull() member function returns true.

-

21.1.3 PostgreSQL Database Type Mapping

+

22.1.3 PostgreSQL Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the PostgreSQL database types.

@@ -19708,7 +19884,7 @@ class Person }; -

21.1.4 Oracle Database Type Mapping

+

22.1.4 Oracle Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the Oracle database types.

@@ -19767,7 +19943,7 @@ class Person }; -

21.1.5 SQL Server Database Type Mapping

+

22.1.5 SQL Server Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the SQL Server database types.

@@ -19834,7 +20010,7 @@ class Person }; -

21.2 Smart Pointers

+

22.2 Smart Pointers

The smart-ptr sub-profile provides persistence support the Qt smart pointers. To enable only this profile, pass @@ -19903,7 +20079,7 @@ class Employee this behavior, add the --default-pointer option specifying the alternative pointer type after the --profile option.

-

21.3 Containers Library

+

22.3 Containers Library

The container sub-profile provides persistence support for Qt containers. To enable only this profile, pass @@ -19928,7 +20104,7 @@ class Person }; -

21.4 Date Time Types

+

22.4 Date Time Types

The date-time sub-profile provides persistence support for the Qt date-time types. To enable only this profile, pass @@ -19981,7 +20157,7 @@ namespace odb system dependent and is discussed in more detail in the following sub-sections.

-

21.4.1 MySQL Database Type Mapping

+

22.4.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the MySQL database types.

@@ -20040,7 +20216,7 @@ class Person the MySQL documentation for more information on the MySQL data type ranges.

-

21.4.2 SQLite Database Type Mapping

+

22.4.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the SQLite database types.

@@ -20102,7 +20278,7 @@ class Person epoch) as an SQLite INTEGER will result in the out_of_range exception.

-

21.4.3 PostgreSQL Database Type Mapping

+

22.4.3 PostgreSQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the PostgreSQL database types.

@@ -20138,7 +20314,7 @@ class Person QDateTime types are stored as a NULL value if their isNull() member function returns true.

-

21.4.4 Oracle Database Type Mapping

+

22.4.4 Oracle Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the Oracle database types.

@@ -20192,7 +20368,7 @@ class person }; -

21.4.5 SQL Server Database Type Mapping

+

22.4.5 SQL Server Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the SQL Server database types.

-- cgit v1.1