From 8a288c54e5d1a5aacc115515f335ed6224e34459 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov 10.2.1 type
10.2.2 id_type
- 10.2.3 null
/not_null
- 10.2.4 unordered
- 10.2.5 index_type
- 10.2.6 key_type
- 10.2.7 value_type
- 10.2.8 value_null
/value_not_null
- 10.2.9 id_column
- 10.2.10 index_column
- 10.2.11 key_column
+ 10.2.12 value_column
+ 10.2.4 default
+ 10.2.5 options
+ 10.2.6 unordered
+ 10.2.7 index_type
+ 10.2.8 key_type
+ 10.2.9 value_type
+ 10.2.10 value_null
/value_not_null
+ 10.2.11 id_options
+ 10.2.12 index_options
+ 10.2.13 key_options
+ 10.2.14 value_options
+ 10.2.15 id_column
+ 10.2.16 index_column
+ 10.2.17 key_column
@@ -443,19 +449,25 @@ for consistency.
10.2.18 value_column
10.3.2 auto
10.3.3 type
- 10.3.4 null
/not_null
- 10.3.5 column
- 10.3.6 transient
- 10.3.7 inverse
- 10.3.8 unordered
- 10.3.9 table
- 10.3.10 index_type
- 10.3.11 key_type
- 10.3.12 value_type
- 10.3.13 value_null
/value_not_null
- 10.3.14 id_column
- 10.3.15 index_column
- 10.3.16 key_column
+ 10.3.17 value_column
+ 10.3.5 default
+ 10.3.6 options
+ 10.3.7 column
+ 10.3.8 transient
+ 10.3.9 inverse
+ 10.3.10 unordered
+ 10.3.11 table
+ 10.3.12 index_type
+ 10.3.13 key_type
+ 10.3.14 value_type
+ 10.3.15 value_null
/value_not_null
+ 10.3.16 id_options
+ 10.3.17 index_options
+ 10.3.18 key_options
+ 10.3.19 value_options
+ 10.3.20 id_column
+ 10.3.21 index_column
+ 10.3.22 key_column
@@ -3634,8 +3646,8 @@ private:
the order information. In the example above, for instance, the order
of person's nicknames is probably not important. To instruct the ODB
compiler to ignore the order in ordered containers we can use the
- 10.3.23 value_column
db unordered
pragma (Section 10.2.4,
- "unordered
", Section 10.3.8,
+ db unordered
pragma (Section 10.2.6,
+ "unordered
", Section 10.3.10,
"unordered
"). For example:
@@ -3888,8 +3900,8 @@ class employee use the-not_null
pragma (Section 10.3.4, "null
/not_null
") for single object pointers and thevalue_not_null
pragma - (Section - 10.3.13, "value_null
/value_not_null
") + (Section + 10.3.15, "value_null
/value_not_null
") for containers of object pointers. For example:@@ -4246,7 +4258,7 @@ CREATE TABLE employee ( of these references.To eliminate redundant database schema references we can use the -
@@ -4290,7 +4302,7 @@ CREATE TABLE employee ( pointer. Also note that an ordered container (Section 5.1, "Ordered Containers") of pointers that is an inverse side of a bidirectional relationship is always treated as unordered - (Section 10.3.8, "inverse
pragma (Section 10.3.7, +inverse
pragma (Section 10.3.9, "inverse
") which tells the ODB compiler that a pointer is the inverse side of a bidirectional relationship. Either side of a relationship can be made inverse. For example:unordered
") + (Section 10.3.10, "unordered
") because the contents of such a container are implicitly built from the direct side of the relationship which does not contain the element order (index). @@ -4972,8 +4984,8 @@ t.commit ();Customizing a column name for a data member of a simple value type is straightforward: we simply specify the desired name with - the
@@ -5074,9 +5086,9 @@ CREATE TABLE person (db column
pragma (Section - 10.3.5, "column
"). For composite value + thedb column
pragma (Section + 10.3.7, "column
"). For composite value types things are slightly more complex since they are mapped to multiple columns. Consider the following example:The same principle applies when a composite value type is used as an element of a container, except that instead of
db column
, either thedb value_column
- (Section 10.3.17, "value_column
") or + (Section 10.3.23, "value_column
") ordb key_column
- (Section 10.3.16, "key_column
") + (Section 10.3.22, "key_column
") pragmas are used to specify the column prefix.When a composite value type contains a container, an extra table @@ -5120,8 +5132,8 @@ CREATE TABLE person (
To customize the container table name we can use the -
+db table
pragma (Section - 10.3.9, "table
"), for example:db table
pragma (Section + 10.3.11, "table
"), for example:#pragma db value @@ -6044,57 +6056,93 @@ private:-+ + ++ default
default value for a value type +10.2.4 ++ + ++ options
database options for a value type +10.2.5 +unordered
ordered container should be stored unordered -10.2.4 +10.2.6 index_type
database type for a container's index type -10.2.5 +10.2.7 key_type
database type for a container's key type -10.2.6 +10.2.8 value_type
database type for a container's value type -10.2.7 +10.2.9 + + value_null
/value_not_null
container's value can/cannot be -NULL
10.2.8 +10.2.10 ++ + ++ id_options
database options for a container's id column +10.2.11 ++ + ++ index_options
database options for a container's index column +10.2.12 ++ + ++ key_options
database options for a container's key column +10.2.13 ++ + value_options
database options for a container's value column +10.2.14 - id_column
column name for a container's table object id -10.2.9 +column name for a container's object id +10.2.15 - index_column
column name for a container's table index -10.2.10 +column name for a container's index +10.2.16 - key_column
column name for a container's table key -10.2.11 +column name for a container's key +10.2.17 @@ -6106,8 +6154,9 @@ private: is the scope. A particular value type specifier applies to all the members of this value type that don't have a pre-member version of the specifier, while the member specifier always applies only - to a single member. In other words, member specifiers take precedence - over parameters specified with value specifiers. + to a single member. Also, with a few exceptions, member specifiers + take precedence over and override parameters specified with value + specifiers. - value_column
column name for a container's table value -10.2.12 +column name for a container's value +10.2.18 10.2.1
@@ -6261,7 +6310,52 @@ typedef shared_ptr<person> person_ptr; for the object pointers, refer to Chapter 6, "Relationships". -type
10.2.4
+unordered
10.2.4
+ +default
The
+ +default
specifier specifies the database default value + that should be used for data members of this type. For example:+#pragma db value(std::string) default("") + +#pragma db object +class person +{ + ... + + std::string name_; // Mapped to TEXT NOT NULL DEFAULT ''. +}; ++ +The semantics of the
+ +default
specifier for a value type + are similar to those of thedefault
specifier for a + data member (Section 10.3.5, + "default
").10.2.5
+ +options
The
+ +options
specifier specifies additional column + definition options that should be used for data members of this + type. For example:+#pragma db value(std::string) options("COLLATE binary") + +#pragma db object +class person +{ + ... + + std::string name_; // Mapped to TEXT NOT NULL COLLATE binary. +}; ++ +The semantics of the
+ +options
specifier for a value type + are similar to those of theoptions
specifier for a + data member (Section 10.3.6, + "options
").10.2.6
unordered
The
-unordered
specifier specifies that the ordered container should be stored unordered in the database. The database @@ -6278,12 +6372,12 @@ typedef std::vector<std::string> names; storage in the database, refer to Section 5.1, "Ordered Containers".10.2.5
+index_type
10.2.7
index_type
The
@@ -6292,12 +6386,12 @@ typedef std::vector<std::string> names; #pragma db value(names) index_type("SMALLINT UNSIGNED")index_type
specifier specifies the native database type that should be used for an ordered container's index column. The semantics ofindex_type
- are similar to that of thetype
specifier + are similar to those of thetype
specifier (Section 10.2.1, "type
"). The native database type is expected to be an integer type. For example:10.2.6
+key_type
10.2.8
key_type
The
@@ -6306,12 +6400,12 @@ typedef std::map<unsigned short, float> age_weight_map; #pragma db value(age_weight_map) key_type("INT UNSIGNED")key_type
specifier specifies the native database type that should be used for a map container's key column. The semantics ofkey_type
- are similar to that of thetype
specifier + are similar to those of thetype
specifier (Section 10.2.1, "type
"). For example:
value_type
value_type
The value_type
specifier specifies the native
database type that should be used for a container's
value column. The semantics of value_type
- are similar to that of the type
specifier
+ are similar to those of the type
specifier
(Section 10.2.1, "type
"). For
example:
The value_null
and value_not_null
- (Section 10.2.8,
+ (Section 10.2.10,
"value_null
/value_not_null
") specifiers
can be used to control the NULL semantics of a value column.
value_null
/value_not_null
value_null
/value_not_null
The value_null
and value_not_null
specifiers
specify that a container type's element value can or cannot be
NULL
, respectively. The semantics of value_null
- and value_not_null
are similar to that of the
+ and value_not_null
are similar to those of the
null
and not_null
specifiers
(Section 10.2.3, "null
/not_null
").
For example:
For set and multiset containers (Section 5.2, "Set and
Multiset Containers") the element value is automatically treated
- as not alowing a NULL
value.
NULL
value.
+
- id_column
id_options
The id_options
specifier specifies additional
+ column definition options that should be used for a container's
+ id column. For example:
+typedef std::vector<std::string> nicknames; +#pragma db value(nicknames) id_options("COLLATE binary") ++ +
The semantics of the id_options
specifier for a container
+ type are similar to those of the id_options
specifier for
+ a container data member (Section 10.3.16,
+ "id_options
").
index_options
The index_options
specifier specifies additional
+ column definition options that should be used for a container's
+ index column. For example:
+typedef std::vector<std::string> nicknames; +#pragma db value(nicknames) index_options("ZEROFILL") ++ +
The semantics of the index_options
specifier for a container
+ type are similar to those of the index_options
specifier for
+ a container data member (Section 10.3.17,
+ "index_options
").
key_options
The key_options
specifier specifies additional
+ column definition options that should be used for a container's
+ key column. For example:
+typedef std::map<std::string, std::string> properties; +#pragma db value(properties) key_options("COLLATE binary") ++ +
The semantics of the key_options
specifier for a container
+ type are similar to those of the key_options
specifier for
+ a container data member (Section 10.3.18,
+ "key_options
").
value_options
The value_options
specifier specifies additional
+ column definition options that should be used for a container's
+ value column. For example:
+typedef std::set<std::string> nicknames; +#pragma db value(nicknames) value_options("COLLATE binary") ++ +
The semantics of the value_options
specifier for a container
+ type are similar to those of the value_options
specifier for
+ a container data member (Section 10.3.19,
+ "value_options
").
id_column
The id_column
specifier specifies the column
name that should be used to store the object id in a
@@ -6366,7 +6529,7 @@ typedef std::vector<std::string> names;
If the column name is not specified, then object_id
is used by default.
index_column
index_column
The index_column
specifier specifies the column
name that should be used to store the element index in an
@@ -6380,7 +6543,7 @@ typedef std::vector<std::string> names;
If the column name is not specified, then index
is used by default.
key_column
key_column
The key_column
specifier specifies the column
name that should be used to store the key in a map
@@ -6394,7 +6557,7 @@ typedef std::map<unsigned short, float> age_weight_map;
If the column name is not specified, then key
is used by default.
value_column
value_column
The value_column
specifier specifies the column
name that should be used to store the element value in a
@@ -6440,93 +6603,128 @@ typedef std::map<unsigned short, float> age_weight_map;
type
null
/not_null
NULL
column
default
options
column
transient
inverse
unordered
table
index_type
key_type
value_type
value_null
/value_not_null
NULL
id_options
index_options
key_options
value_options
id_column
index_column
key_column
value_column
id
null
/not_null
") specifiers
can be used to control the NULL semantics of a data member.
- column
The column
specifier specifies the column name
- that should be used to store a data member in a relational database.
- For example:
-#pragma db object -class person -{ - ... - - #pragma db id column("person_id") - unsigned long id_; -}; -- -
For a member of a composite value type, the column
specifier
- specifies the column name prefix. Refer to Section 7.1,
- "Composite Value Column and Table Names" for details.
If the column name is not specified, it is derived from the member
- name by removing the common data member name decorations, such as leading
- and trailing underscores, the m_
prefix, etc.
transient
The transient
specifier instructs the ODB compiler
- not to store a data member in the database. For example:
-#pragma db object -class person -{ - ... - - date born_; - - #pragma db transient - unsigned short age_; // Computed from born_. -}; -- -
This pragma is usually used on computed members, pointers and - references that are only meaningful in the application's - memory, as well as utility members such as mutexes, etc.
-null
/not_null
The null
and not_null
specifiers specify that
@@ -6708,7 +6860,215 @@ class account
for the object pointers, refer to Chapter 6,
"Relationships".
inverse
default
The default
specifier specifies the database default value
+ that should be used for a data member. For example:
+#pragma db object +class person +{ + ... + + #pragma db default(-1) + int age_; // Mapped to INT NOT NULL DEFAULT -1. +}; ++ +
A default value can be the special null
keyword,
+ a bool
literal (true
or false
),
+ an integer literal, a floating point literal, a string literal, or
+ an enumerator name. If you need to specify a default value that is
+ an expression, for example an SQL function call, then you can use
+ the options
specifier (Section
+ 10.3.6, "options
") instead. For example:
+enum gender {male, female, undisclosed}; + +#pragma db object +class person +{ + ... + + #pragma db default(null) + nullable<std::string> middle_; // DEFAULT NULL + + #pragma db default(false) + bool married_; // DEFAULT 0/FALSE + + #pragma db default(0.0) + float weight_; // DEFAULT 0.0 + + #pragma db default("Mr") + string title_; // DEFAULT 'Mr' + + #pragma db default(undisclosed) + gender gender_; // DEFAULT 2/'undisclosed' + + #pragma db options("DEFAULT CURRENT_TIMESTAMP()") + date timestamp_; // DEFAULT CURRENT_TIMESTAMP() +}; ++ +
Default values specified as enumerators are only supported for
+ members that are mapped to an ENUM
or an integer
+ type in the database, which is the case for the automatic
+ mapping of C++ enums to suitable database types as performed
+ by the ODB compiler. If you have mapped a C++ enum to another
+ database type, then you should use a literal corresponding
+ to that type to specify the default value. For example:
+enum gender {male, female, undisclosed}; +#pragma db value(gender) type("VARCHAR(11)") + +#pragma db object +class person +{ + ... + + #pragma db default("undisclosed") + gender gender_; // DEFAULT 'undisclosed' +}; ++ +
A default value can also be specified on the per-type basis
+ (Section 10.2.4, "default
").
+ An empty default
specifier can be used to reset
+ a default value that was previously specified on the per-type
+ basis. For example:
+#pragma db value(std::string) default("") + +#pragma db object +class person +{ + ... + + #pragma db default() + std::string name_; // No default value. +}; ++ +
A data member containing the object id (Section
+ 10.3.1, "id
" ) is automatically treated as not
+ having a default value even if its type specifies a default value.
Note also that default values do not affect the generated C++ code + in any way. In particular, no automatic initialization of data members + with their default values is performed at any point. If you need such + an initialization, you will need to implement it yourself, for example, + in your persistent class constructors. The default values only + affect the generated database schemas and, in the context of ODB, + are primarily useful for schema evolution.
+ + +options
The options
specifier specifies additional column
+ definition options that should be used for a data member. For
+ example:
+#pragma db object +class person +{ + ... + + #pragma db options("UNIQUE") + std::string email_; // Mapped to TEXT NOT NULL UNIQUE. +}; ++ +
Options can also be specified on the per-type basis
+ (Section 10.2.5, "options
").
+ By default, options are accumulating. That is, the ODB compiler
+ first adds all the options specified for a value type followed
+ by all the options specified for a data member. To clear the
+ accumulated options at any point in this sequence you can use
+ an empty options
specifier. For example:
+#pragma db value(std::string) options("COLLATE binary") + +#pragma db object +class person +{ + ... + + std::string first_; // TEXT NOT NULL COLLATE binary + + #pragma db options("UNIQUE") + std::string last_; // TEXT NOT NULL COLLATE binary UNIQUE + + #pragma db options() + std::string title_; // TEXT NOT NULL + + #pragma db options() options("UNIQUE") + std::string email_; // TEXT NOT NULL UNIQUE +}; ++ +
ODB provides dedicated specifiers for specifying column types
+ (Section 10.3.3, "type
"),
+ NULL
constraints (Section 10.3.4,
+ "null
/not_null
"), and default
+ values (Section 10.3.5, "default
").
+ For ODB to function correctly these specifiers should always be
+ used instead of the opaque options
specifier for
+ these components of a column definition.
column
The column
specifier specifies the column name
+ that should be used to store a data member in a relational database.
+ For example:
+#pragma db object +class person +{ + ... + + #pragma db id column("person_id") + unsigned long id_; +}; ++ +
For a member of a composite value type, the column
specifier
+ specifies the column name prefix. Refer to Section 7.1,
+ "Composite Value Column and Table Names" for details.
If the column name is not specified, it is derived from the member
+ name by removing the common data member name decorations, such as leading
+ and trailing underscores, the m_
prefix, etc.
transient
The transient
specifier instructs the ODB compiler
+ not to store a data member in the database. For example:
+#pragma db object +class person +{ + ... + + date born_; + + #pragma db transient + unsigned short age_; // Computed from born_. +}; ++ +
This pragma is usually used on computed members, pointers and + references that are only meaningful in the application's + memory, as well as utility members such as mutexes, etc.
+ +inverse
The inverse
specifier specifies that a data member of
an object pointer or a container of object pointers type is an
@@ -6746,12 +7106,12 @@ class person
relationship information. Only ordered and set containers can be used
for inverse members. If an inverse member is of an ordered container
type, it is automatically marked as unordered
- (Section 10.3.8, "unordered
").
unordered
").
For a more detailed discussion of inverse members, refer to Section 6.2, "Bidirectional Relationships".
-unordered
unordered
The unordered
specifier specifies that a member of
an ordered container type should be stored unordered in the database.
@@ -6774,7 +7134,7 @@ class person
storage in the database, refer to Section 5.1,
"Ordered Containers".
table
table
The table
specifier specifies the table name that should
be used to store the contents of a container member. For example:
index_type
index_type
The index_type
specifier specifies the native
database type that should be used for an ordered container's
index column of a data member. The semantics of index_type
- are similar to that of the type
specifier
+ are similar to those of the type
specifier
(Section 10.3.3, "type
"). The native
database type is expected to be an integer type. For example:
key_type
key_type
The key_type
specifier specifies the native
database type that should be used for a map container's
key column of a data member. The semantics of key_type
- are similar to that of the type
specifier
+ are similar to those of the type
specifier
(Section 10.3.3, "type
"). For
example:
value_type
value_type
The value_type
specifier specifies the native
database type that should be used for a container's
value column of a data member. The semantics of value_type
- are similar to that of the type
specifier
+ are similar to those of the type
specifier
(Section 10.3.3, "type
"). For
example:
The value_null
and value_not_null
- (Section 10.3.13,
+ (Section 10.3.15,
"value_null
/value_not_null
") specifiers
can be used to control the NULL semantics of a value column.
value_null
/value_not_null
value_null
/value_not_null
The value_null
and value_not_null
specifiers
specify that a container's element value for a data member can or
cannot be NULL
, respectively. The semantics of
value_null
and value_not_null
are similar
- to that of the null
and not_null
specifiers
+ to those of the null
and not_null
specifiers
(Section 10.3.4, "null
/not_null
").
For example:
NULL
value.
- id_column
id_options
The id_options
specifier specifies additional
+ column definition options that should be used for a container's
+ id column of a data member. For example:
+#pragma db object +class person +{ + ... + + #pragma db id options("COLLATE binary") + std::string name_; + + #pragma db id_options("COLLATE binary") + std::vector<std::string> nicknames_; +}; ++ +
The semantics of id_options
are similar to those
+ of the options
specifier (Section
+ 10.3.6, "options
").
index_options
The index_options
specifier specifies additional
+ column definition options that should be used for a container's
+ index column of a data member. For example:
+#pragma db object +class person +{ + ... + + #pragma db index_options("ZEROFILL") + std::vector<std::string> nicknames_; +}; ++ +
The semantics of index_options
are similar to those
+ of the options
specifier (Section
+ 10.3.6, "options
").
key_options
The key_options
specifier specifies additional
+ column definition options that should be used for a container's
+ key column of a data member. For example:
+#pragma db object +class person +{ + ... + + #pragma db key_options("COLLATE binary") + std::map<std::string, std::string> properties_; +}; ++ +
The semantics of key_options
are similar to those
+ of the options
specifier (Section
+ 10.3.6, "options
").
value_options
The value_options
specifier specifies additional
+ column definition options that should be used for a container's
+ value column of a data member. For example:
+#pragma db object +class person +{ + ... + + #pragma db value_options("COLLATE binary") + std::set<std::string> nicknames_; +}; ++ +
The semantics of value_options
are similar to those
+ of the options
specifier (Section
+ 10.3.6, "options
").
id_column
The id_column
specifier specifies the column
name that should be used to store the object id in a
container's table for a data member. The semantics of
- id_column
are similar to that of the
+ id_column
are similar to those of the
column
specifier
- (Section 10.3.5, "column
").
+ (Section 10.3.7, "column
").
For example:
@@ -6926,14 +7373,14 @@ class personIf the column name is not specified, then
-object_id
is used by default.10.3.15
+index_column
10.3.21
index_column
The
index_column
specifier specifies the column name that should be used to store the element index in an ordered container's table for a data member. The semantics of -index_column
are similar to that of the +index_column
are similar to those of thecolumn
specifier - (Section 10.3.5, "column
"). + (Section 10.3.7, "column
"). For example:@@ -6950,14 +7397,14 @@ class personIf the column name is not specified, then
-index
is used by default.10.3.16
+key_column
10.3.22
key_column
The
key_column
specifier specifies the column name that should be used to store the key in a map container's table for a data member. The semantics of -key_column
are similar to that of the +key_column
are similar to those of thecolumn
specifier - (Section 10.3.5, "column
"). + (Section 10.3.7, "column
"). For example:@@ -6974,14 +7421,14 @@ class personIf the column name is not specified, then
-key
is used by default.10.3.17
+value_column
10.3.23
value_column
The
value_column
specifier specifies the column name that should be used to store the element value in a container's table for a data member. The semantics of -value_column
are similar to that of the +value_column
are similar to those of thecolumn
specifier - (Section 10.3.5, "column
"). + (Section 10.3.7, "column
"). For example:-- cgit v1.1