From 440225418d94ab431dc378c8d032f0c268762c46 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 19 Jul 2011 19:57:27 +0200 Subject: Documentation fixes for PostgreSQL chapter --- doc/manual.xhtml | 310 +++++++++++++++++++++++-------------------------------- 1 file changed, 128 insertions(+), 182 deletions(-) diff --git a/doc/manual.xhtml b/doc/manual.xhtml index f7c8238..395630f 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -535,19 +535,19 @@ for consistency. - 13Profiles Introduction + 14Profiles Introduction - 14Boost Profile + 15Boost Profile - - + + - @@ -556,23 +556,23 @@ for consistency. -
14.1Smart Pointers Library
14.2Unordered Containers Library
15.1Smart Pointers Library
15.2Unordered Containers Library
14.3Date Time Library + 15.3Date Time Library - - + +
14.3.1MySQL Database Type Mapping
14.3.2SQLite Database Type Mapping
15.3.1MySQL Database Type Mapping
15.3.2SQLite Database Type Mapping
15Qt Profile + 16Qt Profile - - - + + - @@ -7015,6 +7015,7 @@ aCC +W2161 ...
15.1Basic Types Library + 16.1Basic Types Library - - + +
15.1.1MySQL Database Type Mapping
15.1.2SQLite Database Type Mapping
16.1.1MySQL Database Type Mapping
16.1.2SQLite Database Type Mapping
15.2Smart Pointers Library
15.3Containers Library
16.2Smart Pointers Library
16.3Containers Library
15.4Date Time Library + 16.4Date Time Library - - + +
15.4.1MySQL Database Type Mapping
15.4.2SQLite Database Type Mapping
16.4.1MySQL Database Type Mapping
16.4.2SQLite Database Type Mapping
+
11MySQL Database
12SQLite Database
13PostgreSQL Database
@@ -7036,7 +7037,7 @@ aCC +W2161 ...

The following table summarizes the default mapping between basic C++ value types and MySQL database types. This mapping can be customized on the per-type and per-member basis using the ODB - Pragmas Language (Chapter 10, "ODB Pragma + Pragma Language (Chapter 10, "ODB Pragma Language").

@@ -7283,7 +7284,7 @@ namespace odb

The --options-file 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.

+ on a separate line followed by a space and an option value.

If the erase argument to this constructor is true, then the above options are removed from the argv @@ -7419,7 +7420,7 @@ namespace odb 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 min_connections - and there are no caller waiting for a new connection, + and there are no callers waiting for a new connection, then the pool will close the excess connections.

If the max_connections value is 0, then the pool will @@ -7531,7 +7532,7 @@ namespace odb

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 (Chapter 10, "ODB Pragma + Pragma Language (Chapter 10, "ODB Pragma Language").

@@ -7715,7 +7716,7 @@ auto_ptr<odb::database> db ( flag instead of SQLITE_OPEN_READWRITE). The --options-file 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.

+ on a separate line followed by a space and an option value.

If the erase argument to this constructor is true, then the above options are removed from the argv @@ -8054,17 +8055,17 @@ class person library (libodb-pgsql). All PostgreSQL-specific ODB classes are defined in the odb::pgsql namespace.

-

ODB utilizes prepared statements extensively. PostgreSQL support for - prepared statements begins with version 7.4 with the introduction - of version 3.0 of the PostgreSQL messaging protocol. For this reason, - ODB supports only PostgreSQL versions 7.4 and later.

+

ODB utilizes prepared statements extensively. Support for prepared + statements was added in PostgreSQL version 7.4 with the introduction + of the messaging protocol version 3.0. For this reason, ODB supports + only PostgreSQL version 7.4 and later.

13.1 PostgreSQL Type Mapping

The following table summarizes the default mapping between basic C++ value types and PostgreSQL database types. This mapping can be customized on the per-type and per-member basis using the ODB - Pragmas Language (Chapter 10, "ODB Pragma + Pragma Language (Chapter 10, "ODB Pragma Language").

@@ -8150,14 +8151,17 @@ class person
-

Note that unsigned short, unsigned int, and - unsigned long long are mapped to SMALLINT, - INTEGER, and BIGINT respectively. The sign bit - of the value stored by the database for these types will contain the most - significant bit of the actual unsigned value being persisted.

-

Additionally, by default, C++ enumerations are automatically - mapped to INT NOT NULL.

+ mapped to INTEGER NOT NULL.

+ +

Note also that because PostgreSQL does not support unsigned integers, + the unsigned short, unsigned int, and + unsigned long long C++ types are by default mapped + to the SMALLINT, INTEGER, and + BIGINT PostgreSQL types, respectively. The sign bit + of the value stored by the database for these types will contain + the most significant bit of the actual unsigned value being + persisted.

13.2 PostgreSQL Database Class

@@ -8172,17 +8176,17 @@ namespace odb class database: public odb::database { public: - database (const std::string& db, - const std::string& user, + database (const std::string& user, const std::string& password, + const std::string& db, const std::string& host = "", unsigned int port = 0, const std::string& extra_conninfo = "", std::auto_ptr<connection_factory> = 0); - database (const std::string& db, - const std::string& user, + database (const std::string& user, const std::string& password, + const std::string& db, const std::string& host = "", const std::string& socket_ext = "", const std::string& extra_conninfo = "", @@ -8203,16 +8207,16 @@ namespace odb public: const std::string& - host () const; + user () const; const std::string& - db () const; + password () const; const std::string& - user () const; + db () const; const std::string& - password () const; + host () const; unsigned int port () const; @@ -8239,29 +8243,21 @@ namespace odb

The overloaded database constructors allow us to specify the PostgreSQL database parameters that should be used when connecting - to the database. Both the first and second constructors have explicit - arguments for db, user, password, - and host. These arguments correspond to the - dbname, user, password, and - host keywords, respectively, of the conninfo - argument of the libpq function PQconnectdb. - For more information regarding the format of the conninfo - string, refer to the description of the libpq function - PQconnectdb in the PostgreSQL documentation.

- -

The port argument of the first constructor takes an - integer value specifying the port number to connect to at the server host - when utilizing TCP/IP sockets. It corresponds to the port - keyword of the conninfo string. Zero specifies the default - port and is equivalent to omitting the port option from the - conninfo string.

- -

The socket_ext argument of the second constructor takes a - string value specifying the socket file name extension for Unix-domain - socket connections when utilizing Unix-domain connections.

+ to the database. The port argument in the first constructor + is an integer value specifying the TCP/IP port number to connect to. A + zero port number indicates that the default port should be used. + The socket_ext argument in the second constructor is a + string value specifying the UNIX-domain socket file name extension.

The third constructor allows us to specify all database parameters - via a single conninfo string.

+ as a single conninfo string. All other constructors + accept additional database connection parameters as the + extra_conninfo argument. For more information + about the format of the conninfo string, refer to + the PQconnectdb() function description in the PostgreSQL + documentation. In the case of extra_conninfo, all the + database parameters provided in this string will take precedence + over those explicitly specified with other constructor arguments.

The last constructor extracts the database parameters from the command line. The following options are recognized:

@@ -8276,8 +8272,8 @@ namespace odb

The --options-file 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.

+ or all of the database options in a file with each option appearing + on a separate line followed by a space and an option value.

If the erase argument to this constructor is true, then the above options are removed from the argv @@ -8294,13 +8290,6 @@ namespace odb

The static print_usage() function prints the list of options with short descriptions that are recognized by this constructor.

-

All the constructors accept additional database connection parameters - via the conninfo or extra_conninfo argument. - The format of this string follows that of the conninfo - argument to the libpq function PQconnectdb. - All database parameters provided via this argument will take preference - over those explicitly specified by a constructor argument.

-

The last argument to all of the constructors is a pointer to the connection factory. If we pass a non-NULL value, the database instance assumes ownership of the factory instance. The @@ -8309,14 +8298,13 @@ namespace odb

The set of accessor functions following the constructors allows us to query the parameters of the database instance. Note that - the conninfo() accessor returns a reference to a string - containing the full conninfo string passed to the database, including - explicitly specified constructor arguments, as well as extra parameters - specified by the extra_conninfo argument (if provided). The - extra_conninfo() accessor will return a reference to a copy - of the string passed as the extra_conninfo constructor - argument if it was provided. Otherwise, it will return a reference to - an empty string.

+ the conninfo() accessor returns a complete + conninfo string which includes parameters that were + explicitly specified with the various constructor arguments, as well as + the extra parameters passed in the extra_conninfo argument. + The extra_conninfo() accessor will return the + conninfo string as passed in the extra_conninfo + argument.

The connection() function returns the PostgreSQL database connection encapsulated by the odb::pgsql::connection @@ -8469,9 +8457,6 @@ namespace odb class database_exception: odb::database_exception { public: - unsigned int - error () const; - const std::string& message () const; @@ -8497,10 +8482,10 @@ namespace odb

The odb::pgsql::database_exception is thrown if a PostgreSQL database operation fails. The PostgreSQL-specific error - information is accessible via the error(), - message() and sqlstate() functions. All this - information is also combined and returned in a human-readable form by - the what() function.

+ information is accessible via the message() and + sqlstate() functions. All this information is also + combined and returned in a human-readable form by the what() + function.

The odb::pgsql::cli_exception is thrown by the command line parsing constructor of the odb::pgsql::database @@ -8515,96 +8500,57 @@ namespace odb

13.5.1 Query Result Caching

-

The PostgreSQL ODB runtime implementation will always perform query result - caching (Section 4.4, "Query Result") even when - explicitly requested not to. This is a result of libpq - behaviour, specifically that control is only returned to the client - once all the results of a query are cached.

+

The PostgreSQL ODB runtime implementation will always return a + cached query result (Section 4.4, "Query Result") + even when explicitly requested not to. This is a limitation of the + PostgreSQL client library (libpq) which does not + support uncached (streaming) query results.

13.5.2 Foreign Key Constraints

-

ODB relies on deferred checking of foreign key constraints. That is to - say, ODB requires that foreign key constraints be checked when the - containing transaction is committed. Default PostgreSQL behaviour is - to check constraints immediately. Any schema that defines a foreign - key constraint must specify the constraint as - INITIALLY DEFERRED in order for ODB to behave correctly, - as shown in the following example:

+

ODB relies on the standard SQL behavior which requires that + the foreign key constraints checking is deferred until the + transaction is committed. Default PostgreSQL behavior is + to check such constraints immediately. As a result, when + used with ODB, a custom database schema that defines foreign + key constraints must declare such constraints as + INITIALLY DEFERRED, as shown in the following example. + Schemas generated by the ODB compiler meet this requirement + automatically.

-
-CREATE TABLE employee (
-  name TEXT,
-  employer BIGINT REFERENCES employer INITIALLY DEFERRED);
-
+ 
+CREATE TABLE Employee (
+  ...
+  employer BIGINT REFERENCES Employer (name) INITIALLY DEFERRED);
+

13.5.3 Date-Time Format

-

ODB is only compatible with PostgreSQL servers that represent date-time - types using 64-bit integers. On creation of every connection, ODB - examines the server parameter integer_datetimes. If it is - not set to on, the - odb::pgsql::database_exception is thrown. You may check the - parameter value for your server by executing the SQL statement - SHOW integer_datetimes.

+

ODB expects the PostgreSQL server to use integers as a binary + format for the date-time types, which is the default for most + PostgreSQL configurations. When creating a connection, ODB + examines the integer_datetimes PostgreSQL server + parameter and if it is false, + odb::pgsql::database_exception is thrown. You may + check the value of this parameter for your server by executing + the following SQL query:

+ + 
+SHOW integer_datetimes
+

13.5.4 Timezones

-

ODB does not currently support date-time types with timezone - information.

+

ODB does not currently support the PostgreSQL date-time types + with timezone information.

13.5.5 NUMERIC Type Support

-

Support provided for the PostgreSQL NUMERIC type is limited - to provision of the raw binary data, as received from the PostgreSQL - server, to the user. The binary data may be accessed as shown in the - following example:

- - 
-#include <odb/pgsql/traits.hxx>
-
-struct numeric
-{
-  std::size_t len;
-  char* data;
-};
-
-template <>
-struct value_traits<numeric, odb::pgsql::id_numeric>
-{
-  static void
-  set_value (numeric& v,
-             const odb::details::buffer& b,
-             std::size_t n,
-             bool is_null)
-  {
-    if (!is_null)
-    {
-      v.len = n;
-      v.data = new char[n];
-      std::memcpy (v.data, b.data (), n);
-    }
-  }
-
-  static void
-  set_image (odb::details::buffer& b,
-             std::size_t& n,
-             bool& is_null
-             numeric v)
-  {
-    is_null = false;
-    n = v.len;
-
-    if (n > b.capacity ())
-      b.capacity (n);
-
-    if (n != 0)
-      std::memcpy (b.data (), v.data, n);
-  }
-};
-
- -

Refer to the PostgreSQL documentation for more information regarding - the binary format used to represent the NUMERIC type.

+

Support for the PostgreSQL NUMERIC type is limited + to providing a binary buffer containing the binary representation + of the value. For more information on the binary format used to + store NUMERIC values refer to the PostgreSQL + documentation.

@@ -8617,9 +8563,9 @@ struct value_traits<numeric, odb::pgsql::id_numeric> and libraries. It consists of the following chapters.

- - - + + +
13Profiles Introduction
14Boost Profile
15Qt Profile
14Profiles Introduction
15Boost Profile
16Qt Profile
@@ -8627,7 +8573,7 @@ struct value_traits<numeric, odb::pgsql::id_numeric>
-

13 Profiles Introduction

+

14 Profiles Introduction

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

-

14 Boost Profile

+

15 Boost Profile

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

-

14.1 Smart Pointers Library

+

15.1 Smart Pointers Library

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

-

14.2 Unordered Containers Library

+

15.2 Unordered Containers Library

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

14.3 Date Time Library

+

15.3 Date Time Library

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

-

14.3.1 MySQL Database Type Mapping

+

15.3.1 MySQL Database Type Mapping

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

-

14.3.2 SQLite Database Type Mapping

+

15.3.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the SQLite database @@ -8993,7 +8939,7 @@ class person

-

15 Qt Profile

+

16 Qt Profile

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

-

15.1 Basic Types

+

16.1 Basic Types

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

15.1.1 MySQL Database Type Mapping

+

16.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.

@@ -9076,7 +9022,7 @@ class Person it is mapped to TEXT.

-

15.1.2 SQLite Database Type Mapping

+

16.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.

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

-

15.2 Smart Pointers

+

16.2 Smart Pointers

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

-

15.3 Containers Library

+

16.3 Containers Library

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

15.4 Date Time Types

+

16.4 Date Time Types

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

-

15.4.1 MySQL Database Type Mapping

+

16.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.

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

-

15.4.2 SQLite Database Type Mapping

+

16.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.

-- cgit v1.1