ODB 2.1.0 released
ODB 2.1.0 was released today.
In case you are not familiar with ODB, it is an object-relational mapping (ORM) system for C++. It allows you to persist C++ objects to a relational database without having to deal with tables, columns, or SQL, and manually writing any of the mapping code. ODB natively supports SQLite, PostgreSQL, MySQL, Oracle, and Microsoft SQL Server. Pre-built packages are available for GNU/Linux, Windows, Mac OS X, and Solaris. Supported C++ compilers include GCC, MS Visual C++, Sun CC, and Clang.
This release packs a long list of new features (note to ourselves: if the NEWS entries are over a page long — time to release). The major ones include the ability to use accessor and modifier functions/expressions to access data members, the ability to declare virtual data members, the ability to define database indexes, as well as support for mapping extended database types, such as geospatial types, user-defined types, and collections. There are also notable additions to the profile libraries. The Boost profile now includes support for the Multi-Index and Uuid libraries while the Qt profile now supports the QUuid type. Furthermore, there is a number of improvements in individual database support, especially for SQLite (see below).
We have also added Visual Studio 2012 and Clang 3.1 to the list of compilers that we use for testing. Specifically, all the runtime libraries, examples, and tests now come with project/solution files for Visual Studio 2012 in addition to 2010 and 2008. As always, below I am going to examine these and other notable new features in more detail. For the complete list of changes, see the official ODB 2.1.0 announcement.
Accessors and Modifiers
ODB now supports multiple ways to access data members in persistent objects, views, and value types. Now, if the data member is not accessible directly, the ODB compiler will try to automatically discover suitable accessor and modifier functions. By default the ODB compiler will look for names in the form: get/set_foo(), get/setFoo(), get/setfoo(), as well as just foo(). You can also add custom name derivations with the --accessor-regex and --modifier-regex options. Here is an example:
#pragma db object
class person
{
public:
const std::string& name () const;
void setName (const std::string&);
private:
std::string name_; // Using name() and setName().
...
};
If the ODB compiler was unable to find a suitable accessor or modifier function, then we can specify one explicitly with the new get and set pragmas. For example:
#pragma db object
class person
{
public:
const std::string& get_full_name () const;
std::string& set_full_name ();
private:
#pragma db get(get_full_name) set(set_full_name)
std::string name_;
...
};
In fact, it doesn’t have to be just a function. Rather, it can be an accessor or modifier expression. Here is a more interesting example:
#pragma db object
class person
{
public:
const char* name () const;
void name (const char*);
private:
#pragma db get(std::string (this.name ())) \
set(this.name ((?).c_str ()))
std::string name_;
...
};
For more information on automatic discovery of accessors and modifiers, refer to Section 3.2, “Declaring Persistent Objects and Values” in the ODB manual. For details on how to specify custom accessor/modifier expressions, see Section 12.4.5, “get/set/access” as well as the access example in the odb-examples package.
Virtual Data Members
A virtual data member is an imaginary data member that is only used for the purpose of database persistence. A virtual data member does not actually exist (that is, occupy space) in the C++ class.
At first, the idea of a virtual data member may seem odd but if you think about it, it’s a natural extension of the accessor/modifier support discussed above. After all, if we have an accessor/modifier pair, why do we have to have a physical data member to tie it to? Probably the best way to illustrate this idea is to show how we can use virtual data members to handle the C++ pimpl idiom:
#pragma db object
class person
{
public:
const std::string& name () const;
void name (const std::string&);
unsigned short age () const;
void age (unsigned short) const;
private:
struct impl;
#pragma db transient
impl* pimpl_;
#pragma db member(name) virtual(std::string)
#pragma db member(age) virtual(unsigned short)
...
};
Besides the pimpl idiom, virtual data members can also be useful to aggregate or dis-aggregate real data members and to handle third-party types for which names of real data members may not be known.
Note also that virtual data members have nothing to do with C++ virtual functions or virtual inheritance. Specifically, no virtual function call overhead is incurred when using virtual data members.
For more information on virtual data members, refer to Section 12.4.13, “virtual” in the ODB manual as well as the access and pimpl examples in the odb-examples package.
Database Indexes
ODB now supports defining database indexes within the pragma language. If all you need is a simple index on a particular data member (simple or composite), then all you have to do is specify either the index (for non-unique index) or unique (for unique index) pragma. For example:
#pragma db object
class person
{
...
#pragma db unique
std::string name_;
#pragma db index
unsigned short age_;
};
It is also possible to define an index on more than one member as well as to give it a custom name:
#pragma db object
class person
{
...
std::string first_;
std::string last_;
#pragma db index("name_i") unique members(first_, last_)
};
ODB also supports database-specific index types, methods, and options. Here is an example of a more involved PostgreSQL-specific index definition:
#pragma db object
class person
{
...
std::string name_;
#pragma db index \
type("UNIQUE CONCURRENTLY") \
method("HASH") \
member(name_, "DESC") \
options("WITH(FILLFACTOR = 80)")
};
For more information on defining database indexes, refer to Section 12.6, “Index Definition Pragmas” in the ODB manual.
Mapping Extended Database Types
Besides the standard integers, strings, and BLOBs, most modern database implementations also provide a slew of extended SQL types. Things like geospatial types, user-defined types, collections (arrays, table types, etc), key-value stores, XML, JSON, etc. While ODB does not support such extended types directly (it would take years to cover all the types in all the databases), it now includes a mechanism which, with a bit of effort, allows you to map pretty much any extended SQL type to any C++ type.
This is a really big and powerful feature. As a result, I wrote a separate post that is dedicated just to Extended Database to C++ Type Mapping. It provides much more detail and some cool examples. There is also Section 12.7, “Database Type Mapping Pragmas” in the ODB manual.
Profile Library Improvements
Both Boost and Qt profile libraries now include persistence support for their respective UUID types. By default, these types are mapped to a UUID SQL type if the database provides such a type (e.g., UUID in PostgreSQL and UNIQUEIDENTIFER in SQL Server) or to a suitable 16-byte binary type otherwise. As a result, you can now use boost::uuids::uuid and QUuid in your persistent classes without any extra effort:
// Boost version.
//
#pragma db object
class person
{
...
boost::uuids::uuid id_;
};
// Qt version.
//
#pragma db object
class Person
{
...
QUuid id_;
};
For more information on UUID support in Boost, refer to Section 19.6, “Uuid Library” in the ODB manual. For Qt, see Section 20.1, “Basic Types”.
In addition, the Boost profile now includes support for the Multi-Index container library. While there are some interesting implementation details about which I am planning to write in a separate post, from the user perspective, multi_index_container can now be used in persistent classes just as any standard container. For example:
namespace mi = boost::multi_index;
#pragma db object
class person
{
...
typedef
mi::multi_index_container<
std::string,
mi::indexed_by<
mi::sequenced<>,
mi::ordered_unique<mi::identity<std::string> >
>
> emails;
emails emails_;
};
For more information on Multi-Index container support, refer to Section 19.3, “Multi-Index Container Library” in the ODB manual.
Combined Database Schema
The ODB compiler now supports the generation of the combined SQL file from multiple header files. For example:
odb ... --generate-schema-only --at-once --output-name schema \ employee.hxx employer.hxx
The result of the above command will be the schema.sql file that contains database creation code (DLL statements) for persistent classes defined in both employee.hxx and employer.hxx headers.
A combined SQL file can be easier to work with, for example, send to a DBA for review. It can also be useful when dealing with circular dependencies, as discussed in Section 6.3 “Circular Relationships” in the ODB manual.
C++11 std::array to BLOB Mapping
ODB now includes built-in support for mapping C++11 std::array<char, N> and std::array<unsigned char, N> types to BLOB/BINARY database types. For example:
#pragma db object
class person
{
...
#pragma db type("BINARY(1024)")
std::array<char, 1024> pub_key_;
};
SQLite Support Improvements
On Windows, SQLite ODB runtime now supports persistence of std::wstring. You can also pass the database name as std::wstring in addition to std::string. The odb::sqlite::database class constructors have also been extended to accept the virtual filesystem (vfs) module name. Finally, the default SQLite mapping for float and double now allows the NULL value since SQLite treats NaN values as NULL.