aboutsummaryrefslogtreecommitdiff
path: root/doc/manual.xhtml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual.xhtml')
-rw-r--r--doc/manual.xhtml638
1 files changed, 535 insertions, 103 deletions
diff --git a/doc/manual.xhtml b/doc/manual.xhtml
index 88e8f07..700294c 100644
--- a/doc/manual.xhtml
+++ b/doc/manual.xhtml
@@ -513,20 +513,22 @@ for consistency.
<tr><th>12.4.11</th><td><a href="#12.4.11"><code>readonly</code></a></td></tr>
<tr><th>12.4.12</th><td><a href="#12.4.12"><code>inverse</code></a></td></tr>
<tr><th>12.4.13</th><td><a href="#12.4.13"><code>version</code></a></td></tr>
- <tr><th>12.4.14</th><td><a href="#12.4.14"><code>unordered</code></a></td></tr>
- <tr><th>12.4.15</th><td><a href="#12.4.15"><code>table</code></a></td></tr>
- <tr><th>12.4.16</th><td><a href="#12.4.16"><code>index_type</code></a></td></tr>
- <tr><th>12.4.17</th><td><a href="#12.4.17"><code>key_type</code></a></td></tr>
- <tr><th>12.4.18</th><td><a href="#12.4.18"><code>value_type</code></a></td></tr>
- <tr><th>12.4.19</th><td><a href="#12.4.19"><code>value_null</code>/<code>value_not_null</code></a></td></tr>
- <tr><th>12.4.20</th><td><a href="#12.4.20"><code>id_options</code></a></td></tr>
- <tr><th>12.4.21</th><td><a href="#12.4.21"><code>index_options</code></a></td></tr>
- <tr><th>12.4.22</th><td><a href="#12.4.22"><code>key_options</code></a></td></tr>
- <tr><th>12.4.23</th><td><a href="#12.4.23"><code>value_options</code></a></td></tr>
- <tr><th>12.4.24</th><td><a href="#12.4.24"><code>id_column</code></a></td></tr>
- <tr><th>12.4.25</th><td><a href="#12.4.25"><code>index_column</code></a></td></tr>
- <tr><th>12.4.26</th><td><a href="#12.4.26"><code>key_column</code></a></td></tr>
- <tr><th>12.4.27</th><td><a href="#12.4.27"><code>value_column</code></a></td></tr>
+ <tr><th>12.4.14</th><td><a href="#12.4.14"><code>index</code></a></td></tr>
+ <tr><th>12.4.15</th><td><a href="#12.4.15"><code>unique</code></a></td></tr>
+ <tr><th>12.4.16</th><td><a href="#12.4.16"><code>unordered</code></a></td></tr>
+ <tr><th>12.4.17</th><td><a href="#12.4.17"><code>table</code></a></td></tr>
+ <tr><th>12.4.18</th><td><a href="#12.4.18"><code>index_type</code></a></td></tr>
+ <tr><th>12.4.19</th><td><a href="#12.4.19"><code>key_type</code></a></td></tr>
+ <tr><th>12.4.20</th><td><a href="#12.4.20"><code>value_type</code></a></td></tr>
+ <tr><th>12.4.21</th><td><a href="#12.4.21"><code>value_null</code>/<code>value_not_null</code></a></td></tr>
+ <tr><th>12.4.22</th><td><a href="#12.4.22"><code>id_options</code></a></td></tr>
+ <tr><th>12.4.23</th><td><a href="#12.4.23"><code>index_options</code></a></td></tr>
+ <tr><th>12.4.24</th><td><a href="#12.4.24"><code>key_options</code></a></td></tr>
+ <tr><th>12.4.25</th><td><a href="#12.4.25"><code>value_options</code></a></td></tr>
+ <tr><th>12.4.26</th><td><a href="#12.4.26"><code>id_column</code></a></td></tr>
+ <tr><th>12.4.27</th><td><a href="#12.4.27"><code>index_column</code></a></td></tr>
+ <tr><th>12.4.28</th><td><a href="#12.4.28"><code>key_column</code></a></td></tr>
+ <tr><th>12.4.29</th><td><a href="#12.4.29"><code>value_column</code></a></td></tr>
</table>
</td>
</tr>
@@ -541,17 +543,20 @@ for consistency.
</td>
</tr>
<tr>
- <th>12.6</th><td><a href="#12.6">Database Type Mapping Pragmas</a></td>
+ <th>12.6</th><td><a href="#12.6">Index Definition Pragmas</a></td>
</tr>
<tr>
- <th>12.7</th><td><a href="#12.7">C++ Compiler Warnings</a>
+ <th>12.7</th><td><a href="#12.7">Database Type Mapping Pragmas</a></td>
+ </tr>
+ <tr>
+ <th>12.8</th><td><a href="#12.8">C++ Compiler Warnings</a>
<table class="toc">
- <tr><th>12.7.1</th><td><a href="#12.7.1">GNU C++</a></td></tr>
- <tr><th>12.7.2</th><td><a href="#12.7.2">Visual C++</a></td></tr>
- <tr><th>12.7.3</th><td><a href="#12.7.3">Sun C++</a></td></tr>
- <tr><th>12.7.4</th><td><a href="#12.7.4">IBM XL C++</a></td></tr>
- <tr><th>12.7.5</th><td><a href="#12.7.5">HP aC++</a></td></tr>
- <tr><th>12.7.6</th><td><a href="#12.7.6">Clang</a></td></tr>
+ <tr><th>12.8.1</th><td><a href="#12.8.1">GNU C++</a></td></tr>
+ <tr><th>12.8.2</th><td><a href="#12.8.2">Visual C++</a></td></tr>
+ <tr><th>12.8.3</th><td><a href="#12.8.3">Sun C++</a></td></tr>
+ <tr><th>12.8.4</th><td><a href="#12.8.4">IBM XL C++</a></td></tr>
+ <tr><th>12.8.5</th><td><a href="#12.8.5">HP aC++</a></td></tr>
+ <tr><th>12.8.6</th><td><a href="#12.8.6">Clang</a></td></tr>
</table>
</td>
</tr>
@@ -577,6 +582,7 @@ for consistency.
</table>
</td>
</tr>
+ <tr><th>13.6</th><td><a href="#13.6">MySQL Index Definition</a></td></tr>
</table>
</td>
</tr>
@@ -599,6 +605,7 @@ for consistency.
</table>
</td>
</tr>
+ <tr><th>14.6</th><td><a href="#14.6">SQLite Index Definition</a></td></tr>
</table>
</td>
</tr>
@@ -622,6 +629,7 @@ for consistency.
</table>
</td>
</tr>
+ <tr><th>15.6</th><td><a href="#15.6">PostgreSQL Index Definition</a></td></tr>
</table>
</td>
</tr>
@@ -646,6 +654,7 @@ for consistency.
</table>
</td>
</tr>
+ <tr><th>16.6</th><td><a href="#16.6">Oracle Index Definition</a></td></tr>
</table>
</td>
</tr>
@@ -669,6 +678,7 @@ for consistency.
</table>
</td>
</tr>
+ <tr><th>17.6</th><td><a href="#17.6">SQL Server Index Definition</a></td></tr>
</table>
</td>
</tr>
@@ -4575,7 +4585,12 @@ private:
The second column contains the element index within a container.
And the last column contains the element value. If the object
id or element value are composite, then, instead of a single
- column, they can occupy multiple columns.</p>
+ column, they can occupy multiple columns. For an ordered
+ container table the ODB compiler also defines two indexes:
+ one for the object id column(s) and the other for the index
+ column. Refer to <a href="#12.6">Section 12.6, "Index Definition
+ Pragmas"</a> for more information on how to customize these
+ indexes.</p>
<p>Consider the following persistent object as an example:</p>
@@ -4629,7 +4644,7 @@ private:
of person's nicknames is probably not important. To instruct the ODB
compiler to ignore the order in ordered containers we can use the
<code>db&nbsp;unordered</code> pragma (<a href="#12.3.7">Section 12.3.7,
- "<code>unordered</code>"</a>, <a href="#12.4.14">Section 12.4.14,
+ "<code>unordered</code>"</a>, <a href="#12.4.16">Section 12.4.16,
"<code>unordered</code>"</a>). For example:</p>
<pre class="cxx">
@@ -4666,7 +4681,11 @@ private:
persistent class instance of which the container is a member.
And the second column contains the element value. If the object
id or element value are composite, then, instead of a single
- column, they can occupy multiple columns.</p>
+ column, they can occupy multiple columns. ODB compiler also
+ defines an index on a set container table for the object id
+ column(s). Refer to <a href="#12.6">Section 12.6, "Index Definition
+ Pragmas"</a> for more information on how to customize this
+ index.</p>
<p>Consider the following persistent object as an example:</p>
@@ -4729,7 +4748,11 @@ private:
The second column contains the element key. And the last column
contains the element value. If the object id, element key, or
element value are composite, then instead of a single column
- they can occupy multiple columns.</p>
+ they can occupy multiple columns. ODB compiler also
+ defines an index on a map container table for the object id
+ column(s). Refer to <a href="#12.6">Section 12.6, "Index Definition
+ Pragmas"</a> for more information on how to customize this
+ index.</p>
<p>Consider the following persistent object as an example:</p>
@@ -4887,8 +4910,8 @@ class employee
use the <code>not_null</code> pragma (<a href="#12.4.5">Section
12.4.5, "<code>null</code>/<code>not_null</code>"</a>) for
single object pointers and the <code>value_not_null</code> pragma
- (<a href="#12.4.19">Section
- 12.4.19, "<code>value_null</code>/<code>value_not_null</code>"</a>)
+ (<a href="#12.4.21">Section
+ 12.4.21, "<code>value_null</code>/<code>value_not_null</code>"</a>)
for containers of object pointers. For example:</p>
<pre class="cxx">
@@ -5345,7 +5368,7 @@ CREATE TABLE employee (
pointer. Also note that an ordered container (<a href="#5.1">Section
5.1, "Ordered Containers"</a>) of pointers that is an inverse side
of a bidirectional relationship is always treated as unordered
- (<a href="#12.4.14">Section 12.4.14, "<code>unordered</code>"</a>)
+ (<a href="#12.4.16">Section 12.4.16, "<code>unordered</code>"</a>)
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).</p>
@@ -6238,9 +6261,9 @@ CREATE TABLE person (
<p>The same principle applies when a composite value type is used
as an element of a container, except that instead of
<code>db&nbsp;column</code>, either the <code>db&nbsp;value_column</code>
- (<a href="#12.4.27">Section 12.4.27, "<code>value_column</code>"</a>) or
+ (<a href="#12.4.29">Section 12.4.29, "<code>value_column</code>"</a>) or
<code>db&nbsp;key_column</code>
- (<a href="#12.4.26">Section 12.4.26, "<code>key_column</code>"</a>)
+ (<a href="#12.4.28">Section 12.4.28, "<code>key_column</code>"</a>)
pragmas are used to specify the column prefix.</p>
<p>When a composite value type contains a container, an extra table
@@ -6284,8 +6307,8 @@ CREATE TABLE person (
</pre>
<p>To customize the container table name we can use the
- <code>db&nbsp;table</code> pragma (<a href="#12.4.15">Section
- 12.4.15, "<code>table</code>"</a>), for example:</p>
+ <code>db&nbsp;table</code> pragma (<a href="#12.4.17">Section
+ 12.4.17, "<code>table</code>"</a>), for example:</p>
<pre class="cxx">
#pragma db value
@@ -8873,18 +8896,19 @@ for (bool done (false); !done; )
<p>The <em>qualifier</em> tells the ODB compiler what kind of C++ construct
this pragma describes. Valid qualifiers are <code>object</code>,
<code>view</code>, <code>value</code>, <code>member</code>,
- <code>namespace</code>, and <code>map</code>. A pragma with the
- <code>object</code> qualifier describes a persistent object type. It
- tells the ODB compiler that the C++ class it describes is a persistent
- class. Similarly, pragmas with the <code>view</code> qualifier describe
- view types, the <code>value</code> qualifier describes value types
- and the <code>member</code> qualifier is used to describe data
- members of persistent object, view, and value types. The
- <code>namespace</code> qualifier is used to describe common
+ <code>namespace</code>, <code>index</code>, and <code>map</code>.
+ A pragma with the <code>object</code> qualifier describes a persistent
+ object type. It tells the ODB compiler that the C++ class it describes
+ is a persistent class. Similarly, pragmas with the <code>view</code>
+ qualifier describe view types, the <code>value</code> qualifier
+ describes value types and the <code>member</code> qualifier is used
+ to describe data members of persistent object, view, and value types.
+ The <code>namespace</code> qualifier is used to describe common
properties of objects, views, and value types that belong to
- a C++ namespace. The <code>map</code> qualifier describes a
- mapping between additional database types and types for
- which ODB provides built-in support.</p>
+ a C++ namespace. The <code>index</code> qualifier defines a
+ database index. And, finally, the <code>map</code> qualifier
+ describes a mapping between additional database types and types
+ for which ODB provides built-in support.</p>
<p>The <em>specifier</em> informs the ODB compiler about a particular
database-related property of the C++ declaration. For example, the
@@ -9024,7 +9048,7 @@ class person
the C++ compiler to build the application. Some C++ compilers
issue warnings about pragmas that they do not recognize. There
are several ways to deal with this problem which are covered
- at the end of this chapter in <a href="#12.7">Section 12.7,
+ at the end of this chapter in <a href="#12.8">Section 12.8,
"C++ Compiler Warnings"</a>.</p>
<h2><a name="12.1">12.1 Object Type Pragmas</a></h2>
@@ -10269,7 +10293,7 @@ typedef std::vector&lt;std::string> nicknames;
<p>The semantics of the <code>id_options</code> specifier for a container
type are similar to those of the <code>id_options</code> specifier for
- a container data member (<a href="#12.4.20">Section 12.4.20,
+ a container data member (<a href="#12.4.22">Section 12.4.22,
"<code>id_options</code>"</a>).</p>
@@ -10286,7 +10310,7 @@ typedef std::vector&lt;std::string> nicknames;
<p>The semantics of the <code>index_options</code> specifier for a container
type are similar to those of the <code>index_options</code> specifier for
- a container data member (<a href="#12.4.21">Section 12.4.21,
+ a container data member (<a href="#12.4.23">Section 12.4.23,
"<code>index_options</code>"</a>).</p>
@@ -10303,7 +10327,7 @@ typedef std::map&lt;std::string, std::string> properties;
<p>The semantics of the <code>key_options</code> specifier for a container
type are similar to those of the <code>key_options</code> specifier for
- a container data member (<a href="#12.4.22">Section 12.4.22,
+ a container data member (<a href="#12.4.24">Section 12.4.24,
"<code>key_options</code>"</a>).</p>
@@ -10320,7 +10344,7 @@ typedef std::set&lt;std::string> nicknames;
<p>The semantics of the <code>value_options</code> specifier for a container
type are similar to those of the <code>value_options</code> specifier for
- a container data member (<a href="#12.4.23">Section 12.4.23,
+ a container data member (<a href="#12.4.25">Section 12.4.25,
"<code>value_options</code>"</a>).</p>
@@ -10477,87 +10501,99 @@ typedef std::map&lt;unsigned short, float> age_weight_map;
</tr>
<tr>
+ <td><code>index</code></td>
+ <td>define database index for a member</td>
+ <td><a href="#12.4.14">12.4.14</a></td>
+ </tr>
+
+ <tr>
+ <td><code>unique</code></td>
+ <td>define unique database index for a member</td>
+ <td><a href="#12.4.15">12.4.15</a></td>
+ </tr>
+
+ <tr>
<td><code>unordered</code></td>
<td>ordered container should be stored unordered</td>
- <td><a href="#12.4.14">12.4.14</a></td>
+ <td><a href="#12.4.16">12.4.16</a></td>
</tr>
<tr>
<td><code>table</code></td>
<td>table name for a container</td>
- <td><a href="#12.4.15">12.4.15</a></td>
+ <td><a href="#12.4.17">12.4.17</a></td>
</tr>
<tr>
<td><code>index_type</code></td>
<td>database type for a container's index type</td>
- <td><a href="#12.4.16">12.4.16</a></td>
+ <td><a href="#12.4.18">12.4.18</a></td>
</tr>
<tr>
<td><code>key_type</code></td>
<td>database type for a container's key type</td>
- <td><a href="#12.4.17">12.4.17</a></td>
+ <td><a href="#12.4.19">12.4.19</a></td>
</tr>
<tr>
<td><code>value_type</code></td>
<td>database type for a container's value type</td>
- <td><a href="#12.4.18">12.4.18</a></td>
+ <td><a href="#12.4.20">12.4.20</a></td>
</tr>
<tr>
<td><code>value_null</code>/<code>value_not_null</code></td>
<td>container's value can/cannot be <code>NULL</code></td>
- <td><a href="#12.4.19">12.4.19</a></td>
+ <td><a href="#12.4.21">12.4.21</a></td>
</tr>
<tr>
<td><code>id_options</code></td>
<td>database options for a container's id column</td>
- <td><a href="#12.4.20">12.4.20</a></td>
+ <td><a href="#12.4.22">12.4.22</a></td>
</tr>
<tr>
<td><code>index_options</code></td>
<td>database options for a container's index column</td>
- <td><a href="#12.4.21">12.4.21</a></td>
+ <td><a href="#12.4.23">12.4.23</a></td>
</tr>
<tr>
<td><code>key_options</code></td>
<td>database options for a container's key column</td>
- <td><a href="#12.4.22">12.4.22</a></td>
+ <td><a href="#12.4.24">12.4.24</a></td>
</tr>
<tr>
<td><code>value_options</code></td>
<td>database options for a container's value column</td>
- <td><a href="#12.4.23">12.4.23</a></td>
+ <td><a href="#12.4.25">12.4.25</a></td>
</tr>
<tr>
<td><code>id_column</code></td>
<td>column name for a container's object id</td>
- <td><a href="#12.4.24">12.4.24</a></td>
+ <td><a href="#12.4.26">12.4.26</a></td>
</tr>
<tr>
<td><code>index_column</code></td>
<td>column name for a container's index</td>
- <td><a href="#12.4.25">12.4.25</a></td>
+ <td><a href="#12.4.27">12.4.27</a></td>
</tr>
<tr>
<td><code>key_column</code></td>
<td>column name for a container's key</td>
- <td><a href="#12.4.26">12.4.26</a></td>
+ <td><a href="#12.4.28">12.4.28</a></td>
</tr>
<tr>
<td><code>value_column</code></td>
<td>column name for a container's value</td>
- <td><a href="#12.4.27">12.4.27</a></td>
+ <td><a href="#12.4.29">12.4.29</a></td>
</tr>
</table>
@@ -10856,8 +10892,8 @@ class person
{
...
- #pragma db options("UNIQUE")
- std::string email_; // Mapped to TEXT NOT NULL UNIQUE.
+ #pragma db options("CHECK(email != '')")
+ std::string email_; // Mapped to TEXT NOT NULL CHECK(email != '').
};
</pre>
@@ -10879,14 +10915,14 @@ 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("CHECK(email != '')")
+ std::string last_; // TEXT NOT NULL COLLATE binary CHECK(email != '')
#pragma db options()
std::string title_; // TEXT NOT NULL
- #pragma db options() options("UNIQUE")
- std::string email_; // TEXT NOT NULL UNIQUE
+ #pragma db options() options("CHECK(email != '')")
+ std::string email_; // TEXT NOT NULL CHECK(email != '')
};
</pre>
@@ -11089,7 +11125,7 @@ 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
- (<a href="#12.4.14">Section 12.4.14, "<code>unordered</code>"</a>).</p>
+ (<a href="#12.4.16">Section 12.4.16, "<code>unordered</code>"</a>).</p>
<p>For a more detailed discussion of inverse members, refer to
<a href="#6.2">Section 6.2, "Bidirectional Relationships"</a>.</p>
@@ -11124,7 +11160,45 @@ class person
<p>For a more detailed discussion of optimistic concurrency, refer to
<a href="#11">Chapter 11, "Optimistic Concurrency"</a>.</p>
- <h3><a name="12.4.14">12.4.14 <code>unordered</code></a></h3>
+ <h3><a name="12.4.14">12.4.14 <code>index</code></a></h3>
+
+ <p>The <code>index</code> specifier instructs the ODB compiler to define
+ a database index for the data member. For example:</p>
+
+ <pre class="cxx">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db index
+ std::string name_;
+};
+ </pre>
+
+ <p>For more information on defining database indexes, refer to
+ <a href="#12.6">Section 12.6, "Index Definition Pragmas"</a>.</p>
+
+ <h3><a name="12.4.15">12.4.15 <code>unique</code></a></h3>
+
+ <p>The <code>index</code> specifier instructs the ODB compiler to define
+ a unique database index for the data member. For example:</p>
+
+ <pre class="cxx">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db unique
+ std::string name_;
+};
+ </pre>
+
+ <p>For more information on defining database indexes, refer to
+ <a href="#12.6">Section 12.6, "Index Definition Pragmas"</a>.</p>
+
+ <h3><a name="12.4.16">12.4.16 <code>unordered</code></a></h3>
<p>The <code>unordered</code> specifier specifies that a member of
an ordered container type should be stored unordered in the database.
@@ -11147,7 +11221,7 @@ class person
storage in the database, refer to <a href="#5.1">Section 5.1,
"Ordered Containers"</a>.</p>
- <h3><a name="12.4.15">12.4.15 <code>table</code></a></h3>
+ <h3><a name="12.4.17">12.4.17 <code>table</code></a></h3>
<p>The <code>table</code> specifier specifies the table name that should
be used to store the contents of a container member. For example:</p>
@@ -11195,7 +11269,7 @@ class person
qualified names, refer to <a href="#12.1.8">Section 12.1.8,
"<code>schema</code>"</a>.</p>
- <h3><a name="12.4.16">12.4.16 <code>index_type</code></a></h3>
+ <h3><a name="12.4.18">12.4.18 <code>index_type</code></a></h3>
<p>The <code>index_type</code> specifier specifies the native
database type that should be used for an ordered container's
@@ -11215,7 +11289,7 @@ class person
};
</pre>
- <h3><a name="12.4.17">12.4.17 <code>key_type</code></a></h3>
+ <h3><a name="12.4.19">12.4.19 <code>key_type</code></a></h3>
<p>The <code>key_type</code> specifier specifies the native
database type that should be used for a map container's
@@ -11235,7 +11309,7 @@ class person
};
</pre>
- <h3><a name="12.4.18">12.4.18 <code>value_type</code></a></h3>
+ <h3><a name="12.4.20">12.4.20 <code>value_type</code></a></h3>
<p>The <code>value_type</code> specifier specifies the native
database type that should be used for a container's
@@ -11256,11 +11330,11 @@ class person
</pre>
<p>The <code>value_null</code> and <code>value_not_null</code>
- (<a href="#12.4.19">Section 12.4.19,
+ (<a href="#12.4.21">Section 12.4.21,
"<code>value_null</code>/<code>value_not_null</code>"</a>) specifiers
can be used to control the NULL semantics of a value column.</p>
- <h3><a name="12.4.19">12.4.19 <code>value_null</code>/<code>value_not_null</code></a></h3>
+ <h3><a name="12.4.21">12.4.21 <code>value_null</code>/<code>value_not_null</code></a></h3>
<p>The <code>value_null</code> and <code>value_not_null</code> specifiers
specify that a container's element value for a data member can or
@@ -11293,7 +11367,7 @@ class account
Multiset Containers"</a>) the element value is automatically treated
as not allowing a <code>NULL</code> value.</p>
- <h3><a name="12.4.20">12.4.20 <code>id_options</code></a></h3>
+ <h3><a name="12.4.22">12.4.22 <code>id_options</code></a></h3>
<p>The <code>id_options</code> specifier specifies additional
column definition options that should be used for a container's
@@ -11317,7 +11391,7 @@ class person
of the <code>options</code> specifier (<a href="#12.4.7">Section
12.4.7, "<code>options</code>"</a>).</p>
- <h3><a name="12.4.21">12.4.21 <code>index_options</code></a></h3>
+ <h3><a name="12.4.23">12.4.23 <code>index_options</code></a></h3>
<p>The <code>index_options</code> specifier specifies additional
column definition options that should be used for a container's
@@ -11338,7 +11412,7 @@ class person
of the <code>options</code> specifier (<a href="#12.4.7">Section
12.4.7, "<code>options</code>"</a>).</p>
- <h3><a name="12.4.22">12.4.22 <code>key_options</code></a></h3>
+ <h3><a name="12.4.24">12.4.24 <code>key_options</code></a></h3>
<p>The <code>key_options</code> specifier specifies additional
column definition options that should be used for a container's
@@ -11359,7 +11433,7 @@ class person
of the <code>options</code> specifier (<a href="#12.4.7">Section
12.4.7, "<code>options</code>"</a>).</p>
- <h3><a name="12.4.23">12.4.23 <code>value_options</code></a></h3>
+ <h3><a name="12.4.25">12.4.25 <code>value_options</code></a></h3>
<p>The <code>value_options</code> specifier specifies additional
column definition options that should be used for a container's
@@ -11380,7 +11454,7 @@ class person
of the <code>options</code> specifier (<a href="#12.4.7">Section
12.4.7, "<code>options</code>"</a>).</p>
- <h3><a name="12.4.24">12.4.24 <code>id_column</code></a></h3>
+ <h3><a name="12.4.26">12.4.26 <code>id_column</code></a></h3>
<p>The <code>id_column</code> specifier specifies the column
name that should be used to store the object id in a
@@ -11404,7 +11478,7 @@ class person
<p>If the column name is not specified, then <code>object_id</code>
is used by default.</p>
- <h3><a name="12.4.25">12.4.25 <code>index_column</code></a></h3>
+ <h3><a name="12.4.27">12.4.27 <code>index_column</code></a></h3>
<p>The <code>index_column</code> specifier specifies the column
name that should be used to store the element index in an
@@ -11428,7 +11502,7 @@ class person
<p>If the column name is not specified, then <code>index</code>
is used by default.</p>
- <h3><a name="12.4.26">12.4.26 <code>key_column</code></a></h3>
+ <h3><a name="12.4.28">12.4.28 <code>key_column</code></a></h3>
<p>The <code>key_column</code> specifier specifies the column
name that should be used to store the key in a map
@@ -11452,7 +11526,7 @@ class person
<p>If the column name is not specified, then <code>key</code>
is used by default.</p>
- <h3><a name="12.4.27">12.4.27 <code>value_column</code></a></h3>
+ <h3><a name="12.4.29">12.4.29 <code>value_column</code></a></h3>
<p>The <code>value_column</code> specifier specifies the column
name that should be used to store the element value in a
@@ -11692,7 +11766,207 @@ namespace hr
"<code>session</code>"</a>). For more information on sessions,
refer to <a href="#10">Chapter 10, "Session"</a>.</p>
- <h2><a name="12.6">12.6 Database Type Mapping Pragmas</a></h2>
+ <h2><a name="12.6">12.6 Index Definition Pragmas</a></h2>
+
+ <p>While it is possible to manually add indexes to the generated
+ database schema, it is more convenient to do this as part of
+ the persistent class definitions. A pragma with the <code>index</code>
+ qualifier describes a database index. It has the following
+ general format:</p>
+
+<pre class="cxx">
+#pragma db index[("&lt;name>")] \
+ [unique|type("&lt;type>")] \
+ [method("&lt;method>")] \
+ [options("&lt;index-options>")] \
+ member(&lt;name>[, "&lt;column-options>"])... \
+ members(&lt;name>[,&lt;name>...])...
+</pre>
+
+ <p>The <code>index</code> qualifier can optionally specify the
+ index name. If the index name is not specified, then one is
+ automatically derived by appending the <code>_i</code> suffix
+ to the column name of the index member. If the name is not
+ specified and the index contains multiple members, then the
+ index definition is invalid.</p>
+
+ <p>The optional <code>type</code>, <code>method</code>, and
+ <code>options</code> clauses specify the index type, for
+ example <code>UNIQUE</code>, index method, for example
+ <code>BTREE</code>, and index options, respectively. The
+ <code>unique</code> clause is a shortcut for
+ <code>type("UNIQUE")</code>. Note that not all database
+ systems support specifying an index method or options.
+ For more information on the database system-specific index
+ types, methods, and options, refer to <a href="#II">Part II,
+ "Database Systems"</a>.</p>
+
+ <p>To specify index members we can use the <code>member</code>
+ or <code>members</code> clauses, or a mix of the two. The
+ <code>member</code> clause allows us to specify a single
+ index member with optional column options, for example,
+ <code>"ASC"</code>. If we need to create a composite
+ index that contains multiple members, then we can repeat
+ the <code>member</code> clause several times or, if the
+ members don't have any column options, we can use a single
+ <code>members</code> clause instead. Similar to the index
+ type, method, and options, the format of column options is
+ database system-specific. For more details, refer to
+ <a href="#II">Part II, "Database Systems"</a>.</p>
+
+ <p>The following code fragment shows some typical examples
+ of index definitions:</p>
+
+<pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ int x;
+ int y;
+ int z1;
+ int z2;
+
+ // An index for member x with automatically-assigned name x_i.
+ //
+ #pragma db index member(x)
+
+ // A unique index named y_index for member y which is sorted in
+ // the descending order. The index is using the BTREE method.
+ //
+ #pragma db index("y_index") unique method("BTREE") member(y, "DESC")
+
+ // A composite BITMAP index named z_i for members z1 and z2.
+ //
+ #pragma db index("z_i") type("BITMAP") members(z1, z2)
+};
+</pre>
+
+ <p>ODB also offers a shortcut for defining an index with the default
+ method and options for a single data member. Such an index can
+ be defined using the <code>index</code> (<a href="#12.4.14">Section
+ 12.4.14, "<code>index</code>"</a>) or <code>unique</code>
+ (<a href="#12.4.15">Section 12.4.15, "<code>unique</code>"</a>)
+ member specifier. For example:</p>
+
+<pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ #pragma db index
+ int x;
+
+ #pragma db type("INT") unique
+ int y;
+};
+</pre>
+
+ <p>The above example is semantically equivalent to the following
+ more verbose version:</p>
+
+<pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ int x;
+
+ #pragma db type("INT")
+ int y;
+
+ #pragma db index member(x)
+ #pragma db index unique member(y)
+};
+</pre>
+
+ <p>While it is convenient to define an index inside a persistent
+ class, it is also possible to do that out of the class body. In this
+ case, the index name, if specified, must be prefixed with the
+ potentially-qualified class name. For example:</p>
+
+<pre class="cxx">
+namespace n
+{
+ #pragma db object
+ class object
+ {
+ ...
+
+ int x;
+ int y;
+ };
+
+ // An index for member x in persistent class object with automatically-
+ // assigned name x_i.
+ //
+ #pragma db index(object) member(x)
+}
+
+// An index named y_index for member y in persistent class n::object.
+//
+#pragma db index(n::object::"y_index") member(y)
+</pre>
+
+ <p>It is possible to define an index on a member that is of a
+ composite value type or on some of its nested members. For
+ example:</p>
+
+<pre class="cxx">
+#pragma db value
+struct point
+{
+ int x;
+ int y;
+ int z;
+};
+
+#pragma db object
+class object
+{
+ // An index that includes all of the p1's nested members.
+ //
+ #pragma db index
+ point p1;
+
+ point p2;
+
+ // An index that includes only p2.x and p2.y.
+ //
+ #pragma db index("p2_xy_i") members(p2.x, p2.y)
+};
+</pre>
+
+ <p>When generating a schema for a container member (<a href="#5">Chapter 5,
+ "Containers"</a>), ODB automatically defines two indexes on the container
+ table. One is for the object id that references the object table and the
+ other is for the index column in case the container is ordered
+ (<a href="#5.1">Section 5.1, "Ordered Containers"</a>). By default these
+ indexes use the default index name, type, method, and options. The
+ <code>index</code> pragma allows us to customize these two indexes by
+ recognizing the special <code>id</code> and <code>index</code> nested
+ member names when specified after a container member. For example:</p>
+
+<pre class="cxx">
+#pragma db object
+class object
+{
+ std::vector&lt;int> v;
+
+ // Change the container id index name.
+ //
+ #pragma db index("id_index") member(v.id)
+
+ // Change the container index index method.
+ //
+ #pragma db index method("BTREE") member(v.index)
+};
+</pre>
+
+ <h2><a name="12.7">12.7 Database Type Mapping Pragmas</a></h2>
<p>A pragma with the <code>map</code> qualifier describes a
mapping between two database types. For each database system
@@ -11755,6 +12029,8 @@ namespace hr
#pragma db object
class object
{
+ ...
+
#pragma db type("INTEGER[]")
std::string array_;
};
@@ -11860,6 +12136,8 @@ namespace odb
#pragma db object
class object
{
+ ...
+
#pragma db type("INTEGER[]")
std::vector&lt;int> array_;
};
@@ -11876,6 +12154,8 @@ typedef std::vector&lt;int> int_vector;
#pragma db object
class object
{
+ ...
+
std::vector&lt;int> array_; // Mapped to INTEGER[].
};
</pre>
@@ -11887,7 +12167,7 @@ class object
for each database, shows how to provide custom mapping for some of
the additional types.</p>
- <h2><a name="12.7">12.7 C++ Compiler Warnings</a></h2>
+ <h2><a name="12.8">12.8 C++ Compiler Warnings</a></h2>
<p>When a C++ header file defining persistent classes and containing
ODB pragmas is used to build the application, the C++ compiler may
@@ -11940,7 +12220,7 @@ class person
<p>The disadvantage of this approach is that it can quickly become
overly verbose when positioned pragmas are used.</p>
- <h3><a name="12.7.1">12.7.1 GNU C++</a></h3>
+ <h3><a name="12.8.1">12.8.1 GNU C++</a></h3>
<p>GNU g++ does not issue warnings about unknown pragmas
unless requested with the <code>-Wall</code> command line option.
@@ -11952,7 +12232,7 @@ class person
g++ -Wall -Wno-unknown-pragmas ...
</pre>
- <h3><a name="12.7.2">12.7.2 Visual C++</a></h3>
+ <h3><a name="12.8.2">12.8.2 Visual C++</a></h3>
<p>Microsoft Visual C++ issues an unknown pragma warning (C4068) at
warning level 1 or higher. This means that unless we have disabled
@@ -11986,7 +12266,7 @@ class person
#pragma warning (pop)
</pre>
- <h3><a name="12.7.3">12.7.3 Sun C++</a></h3>
+ <h3><a name="12.8.3">12.8.3 Sun C++</a></h3>
<p>The Sun C++ compiler does not issue warnings about unknown pragmas
unless the <code>+w</code> or <code>+w2</code> option is specified.
@@ -11998,7 +12278,7 @@ class person
CC +w -erroff=unknownpragma ...
</pre>
- <h3><a name="12.7.4">12.7.4 IBM XL C++</a></h3>
+ <h3><a name="12.8.4">12.8.4 IBM XL C++</a></h3>
<p>IBM XL C++ issues an unknown pragma warning (1540-1401) by default.
To disable this warning we can add the <code>-qsuppress=1540-1401</code>
@@ -12008,7 +12288,7 @@ CC +w -erroff=unknownpragma ...
xlC -qsuppress=1540-1401 ...
</pre>
- <h3><a name="12.7.5">12.7.5 HP aC++</a></h3>
+ <h3><a name="12.8.5">12.8.5 HP aC++</a></h3>
<p>HP aC++ (aCC) issues an unknown pragma warning (2161) by default.
To disable this warning we can add the <code>+W2161</code>
@@ -12018,7 +12298,7 @@ xlC -qsuppress=1540-1401 ...
aCC +W2161 ...
</pre>
- <h3><a name="12.7.6">12.7.6 Clang</a></h3>
+ <h3><a name="12.8.6">12.8.6 Clang</a></h3>
<p>Clang does not issue warnings about unknown pragmas
unless requested with the <code>-Wall</code> command line option.
@@ -12277,7 +12557,7 @@ class object
<p>It is also possible to add support for additional MySQL types,
such as geospatial types. For more information, refer to
- <a href="#12.6">Section 12.6, "Database Type Mapping
+ <a href="#12.7">Section 12.7, "Database Type Mapping
Pragmas"</a>.</p>
<h2><a name="13.2">13.2 MySQL Database Class</a></h2>
@@ -12723,6 +13003,31 @@ namespace odb
foreign key definitions commented out. They are retained only
for documentation.</p>
+ <h2><a name="13.6">13.6 MySQL Index Definitions</a></h2>
+
+ <p>When the <code>index</code> pragma (<a href="#12.6">Section 12.6,
+ "Index Definition Pragmas"</a>) is used to define a MySQL index,
+ the <code>type</code> clause specifies the index type (for example,
+ <code>UNIQUE</code>, <code>FULLTEXT</code>, <code>SPATIAL</code>),
+ the <code>method</code> clause specifies the index method (for
+ example, <code>BTREE</code>, <code>HASH</code>), and the
+ <code>options</code> clause is not used. The column options
+ can be used to specify column length limits and the sort order.
+ For example:</p>
+
+ <pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ std::string name_;
+
+ #pragma db index method("HASH") member(name_, "(100) DESC")
+};
+ </pre>
+
+
<!-- CHAPTER -->
@@ -12895,7 +13200,7 @@ class object
<p>It is also possible to add support for additional SQLite types,
such as <code>NUMERIC</code>. For more information, refer to
- <a href="#12.6">Section 12.6, "Database Type Mapping
+ <a href="#12.7">Section 12.7, "Database Type Mapping
Pragmas"</a>.</p>
<h2><a name="14.2">14.2 SQLite Database Class</a></h2>
@@ -13467,6 +13772,30 @@ CREATE TABLE Employee (
functionality. Future versions of the library will remove this
limitation.</p>
+ <h2><a name="14.6">14.6 SQLite Index Definitions</a></h2>
+
+ <p>When the <code>index</code> pragma (<a href="#12.6">Section 12.6,
+ "Index Definition Pragmas"</a>) is used to define an SQLite index,
+ the <code>type</code> clause specifies the index type (for example,
+ <code>UNIQUE</code>) while the <code>method</code> and
+ <code>options</code> clauses are not used. The column options
+ can be used to specify collations and the sort order. For example:</p>
+
+ <pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ std::string name_;
+
+ #pragma db index member(name_, "COLLATE binary DESC")
+};
+ </pre>
+
+ <p>Index names in SQLite are database-global. To avoid name clashes,
+ ODB automatically prefixes each index name with the table name on
+ which it is defined.</p>
<!-- CHAPTER -->
@@ -13655,7 +13984,7 @@ class object
such as <code>NUMERIC</code>, geometry types, <code>XML</code>,
<code>JSON</code>, enumeration types, composite types, arrays,
geospatial types, and the key-value store (<code>HSTORE</code>).
- For more information, refer to <a href="#12.6">Section 12.6,
+ For more information, refer to <a href="#12.7">Section 12.7,
"Database Type Mapping Pragmas"</a>.</p>
<h2><a name="15.2">15.2 PostgreSQL Database Class</a></h2>
@@ -14095,8 +14424,10 @@ SHOW integer_datetimes
<h3><a name="15.5.5">15.5.5 Timezones</a></h3>
- <p>ODB does not currently support the PostgreSQL date-time types
- with timezone information.</p>
+ <p>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 <a href="#12.7">Section 12.7, "Database Type Mapping Pragmas"</a>.</p>
<h3><a name="15.5.6">15.5.6 <code>NUMERIC</code> Type Support</a></h3>
@@ -14104,8 +14435,46 @@ SHOW integer_datetimes
to providing a binary buffer containing the binary representation
of the value. For more information on the binary format used to
store <code>NUMERIC</code> values refer to the PostgreSQL
- documentation.</p>
+ documentation. An alternative approach to accessing <code>NUMERIC</code>
+ values is to map this type to one of the natively supported
+ ones, as discussed in <a href="#12.7">Section 12.7, "Database
+ Type Mapping Pragmas"</a>.</p>
+
+
+ <h2><a name="15.6">15.6 PostgreSQL Index Definitions</a></h2>
+ <p>When the <code>index</code> pragma (<a href="#12.6">Section 12.6,
+ "Index Definition Pragmas"</a>) is used to define a PostgreSQL index,
+ the <code>type</code> clause specifies the index type (for example,
+ <code>UNIQUE</code>), the <code>method</code> clause specifies the
+ index method (for example, <code>BTREE</code>, <code>HASH</code>,
+ <code>GIN</code>, etc.), and the <code>options</code> clause
+ specifies additional index options, such as storage parameters,
+ table spaces, and the <code>WHERE</code> predicate. To support
+ the definition of concurrent indexes, the <code>type</code>
+ clause can end with the word <code>CONCURRENTLY</code> (upper and
+ lower cases are recognized). The column options can be used to
+ specify collations, operator classes, and the sort order. For example:</p>
+
+ <pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ std::string name_;
+
+ #pragma db index \
+ type("UNIQUE CONCURRENTLY") \
+ method("HASH") \
+ member(name_, "DESC") \
+ options("WITH(FILLFACTOR = 80)")
+};
+ </pre>
+
+ <p>Index names in PostgreSQL are schema-global. To avoid name clashes,
+ ODB automatically prefixes each index name with the table name on
+ which it is defined.</p>
<!-- CHAPTER -->
@@ -14291,7 +14660,7 @@ class object
<p>It is also possible to add support for additional Oracle types,
such as <code>XML</code>, geospatial types, user-defined types,
and collections (arrays, table types). For more information, refer to
- <a href="#12.6">Section 12.6, "Database Type Mapping
+ <a href="#12.7">Section 12.7, "Database Type Mapping
Pragmas"</a>.</p>
<h2><a name="16.2">16.2 Oracle Database Class</a></h2>
@@ -14864,6 +15233,11 @@ CREATE TABLE Employee (
used to store the <code>FLOAT</code> and <code>NUMBER</code> values,
refer to the Oracle Call Interface (OCI) documentation.</p>
+ <p>An alternative approach to accessing large <code>FLOAT</code> and
+ <code>NUMBER</code> values is to map these type to one of the
+ natively supported ones, as discussed in <a href="#12.7">Section
+ 12.7, "Database Type Mapping Pragmas"</a>.</p>
+
<p>Note that a <code>NUMBER</code> type that is used to represent a
floating point number (declared by specifying <code>NUMBER</code>
without any range and scale) can be extracted into the C++
@@ -14872,12 +15246,45 @@ CREATE TABLE Employee (
<h3><a name="16.5.6">16.5.6 Timezones</a></h3>
<p>ODB does not currently support the Oracle date-time types with timezone
- information.</p>
+ information. However, these types can be accessed by mapping them to
+ one of the natively supported types, as discussed in
+ <a href="#12.7">Section 12.7, "Database Type Mapping Pragmas"</a>.</p>
<h3><a name="16.5.7">16.5.7 <code>LONG</code> Types</a></h3>
<p>ODB does not support the deprecated Oracle <code>LONG</code> and
- <code>LONG RAW</code> data types.</p>
+ <code>LONG RAW</code> data types. However, these types can be accessed
+ by mapping them to one of the natively supported types, as discussed
+ in <a href="#12.7">Section 12.7, "Database Type Mapping Pragmas"</a>.</p>
+
+ <h2><a name="16.6">16.6 Oracle Index Definitions</a></h2>
+
+ <p>When the <code>index</code> pragma (<a href="#12.6">Section 12.6,
+ "Index Definition Pragmas"</a>) is used to define an Oracle index,
+ the <code>type</code> clause specifies the index type (for example,
+ <code>UNIQUE</code>, <code>BITMAP</code>), the <code>method</code>
+ clause is not used, and the <code>options</code> clause specifies
+ additional index properties, such as partitioning, table spaces, etc.
+ The column options can be used to specify the sort order. For example:</p>
+
+ <pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ std::string name_;
+
+ #pragma db index \
+ type("BITMAP") \
+ member(name_, "DESC") \
+ options("TABLESPACE TBS1")
+};
+ </pre>
+
+ <p>Index names in Oracle are schema-global. To avoid name clashes,
+ ODB automatically prefixes each index name with the table name on
+ which it is defined.</p>
<!-- CHAPTER -->
@@ -15151,7 +15558,7 @@ t.commit ();
<p>It is also possible to add support for additional SQL Server types,
such as geospatial types, <code>XML</code>, and user-defined types.
- For more information, refer to <a href="#12.6">Section 12.6, "Database
+ For more information, refer to <a href="#12.7">Section 12.7, "Database
Type Mapping Pragmas"</a>.</p>
<h2><a name="17.2">17.2 SQL Server Database Class</a></h2>
@@ -15813,6 +16220,31 @@ namespace odb
by passing the <code>--mssql-server-version&nbsp;9.0</code> ODB
compiler option.</p>
+ <h2><a name="17.6">17.6 SQL Server Index Definitions</a></h2>
+
+ <p>When the <code>index</code> pragma (<a href="#12.6">Section 12.6,
+ "Index Definition Pragmas"</a>) is used to define an SQL Server index,
+ the <code>type</code> clause specifies the index type (for example,
+ <code>UNIQUE</code>, <code>CLUSTERED</code>), the <code>method</code>
+ clause is not used, and the <code>options</code> clause specifies
+ additional index properties. The column options can be used to specify
+ the sort order. For example:</p>
+
+ <pre class="cxx">
+#pragma db object
+class object
+{
+ ...
+
+ std::string name_;
+
+ #pragma db index \
+ type("UNIQUE CLUSTERED") \
+ member(name_, "DESC") \
+ options("WITH(FILLFACTOR = 80)")
+};
+ </pre>
+
<!-- PART -->