C++ ORM for SQLite.zip

# Hiberlite ORM [](https://travis-ci.org/paulftw/hiberlite) [](https://ci.appveyor.com/project/d-led/hiberlite/branch/master) C++ object-relational mapping with API inspired by the awesome Boost.Serialization - that means _almost no API to learn_. ## Usage Just compile and link all files under src/ to your project. Include the main header: ```cpp #include "hiberlite.h" ``` ## Features Key features of Hiberlite are: - Boost.Serialization like API - no code generators / preprocessors - support for one-to-many and many-to-many relations - automatic code generation - lazy loading - smart pointers - no need to inherit from a single base class In contrast to most serialization libraries with SQL serializers, C++ objects mapped with hiberlite behave similar to active record pattern - you are not forced to follow the "read all your data/modify some small part/write everything back" path. For people who need reliable data storage, ACID transactions, simple random-access to their data files, and don't like coding in SQL. ----------------------- # Tutorial While building a typical RDBMS application developer has to deal with the following tasks: 1. Open a database 2. Create database schema 3. Populate the tables with data 4. Read and/or modify that data Hiberlite greatly reduces the implementation of each of these tasks. ## Creating a database Opening a database is as simple as ```cpp hiberlite::Database db; db.open("sample.db"); ``` Where ```cpp Database::open(std::string filename) ``` opens a sqlite3 file. If it doesn't exist it will be created. Another option is to have constructor automatically open/create the DB file: ```cpp hiberlite::Database db("sample.db"); ``` ## Creating database schema In C++ You deal with classes and objects. You know what objects You want to store in the database. And hiberlite will figure out how to store that data. ### Defining data model First You must prepare the data classes for use with hiberlite. Suppose we develop a social-network application. We define a person class as: ```cpp class Person{ public: string name; int age; vector<string> bio; }; ``` Now, to let hiberlite know about the internal structure of this class, we add an access method and an export declaration: ```cpp class Person{ friend class hiberlite::access; template<class Archive> void hibernate(Archive & ar) { ar & HIBERLITE_NVP(name); ar & HIBERLITE_NVP(age); ar & HIBERLITE_NVP(bio); } public: string name; double age; vector<string> bio; }; HIBERLITE_EXPORT_CLASS(Person) ``` Inside the **hibernate(Archive & ar)** method we list all the data fields we want to persist in the database. Macro **HIBERLITE_EXPORT_CLASS(Person)** is invoked to register the class name with Hiberlite. For now just remember to invoke it once per class in your project. (Placing it in the Person.cpp is a good idea) At this point hiberlite is able to map the Person to a database. ### Creating tables Database schema in hiberlite is simply a set of classes, that are stored in the database. A programmer defines that set of classes, and hiberlite determines the needed tables and their columns. Each instance of Database maintains its own copy of the database schema (set of data classes). To insert a new class to that set, use registerBeanClass template method: ```cpp db.registerBeanClass<Person>(); ``` In most applications several classes are stored in one database - so usually You will call **registerBeanClass** several times: ```cpp Database db("gmail2.0.db"); db.registerBeanClass<UserAccount>(); db.registerBeanClass<Letter>(); db.registerBeanClass<Attachment>(); ``` When the classes are registered, Database can create tables to map them: ```cpp db.dropModel(); db.createModel(); ``` **createModel()** executes several **CREATE TABLE** queries. **dropModel()** cleans the database - executes **DROP TABLE IF EXISTS** query for each table in the schema. Besides uninstallers, this method may be used to destroy the old tables (from a probably obsolete scheme) before calling createModel(). ## Saving data When the database with proper schema is opened, we can put some Person objects in it: ```cpp Person x; x.name="Amanda"; x.age=21; x.bio.push_back("born 1987"); hiberlite::bean_ptr<Person> p=db.copyBean(x); x.age=-1; //does NOT change any database record p->age=22; //does change the database ``` **copyBean(x)** template method creates a copy of its argument and saves it to the database. It returns a smart pointer - **bean_ptr**. **bean_ptr** is inspired by the **boost::shared_ptr**. The main difference is that in addition to deletion, **bean_ptr** guarantees that the referenced object will be also saved to the database, when no longer needed. An internal primary key is autogenerated for each object in the database. It can be read with **sqlid_t bean_ptr::get_id()**. Another way to create a bean is to use **createBean()** template method: ```cpp hiberlite::bean_ptr<Person> p=db.createBean<Person>(); p->name="Amanda"; p->age=21; p->bio.push_back("born 1987"); ``` ## Loading data There are several methods to query the database: **bean_ptr<C> Database::loadBean(sqlid_t id)** loads the bean with the given id. ```cpp bean_ptr<Person> p=db.loadBean<Person>(1); cout << "first person is " << p->name << endl; ``` In this case object itself is not loaded, when bean_ptr is returned. bean_ptr is a lazy pointer, so the wrapped object will be loaded when first needed. In this example Person will be loaded later, when we try to access the name field. **std::vector< bean_ptr<C> > Database::getAllBeans()** returns a vector with all the beans of a given class C. ```cpp vector< bean_ptr<Person> > v=db.getAllBeans<Person>(); cout << "found " << v.size() << " persons in the database\n"; ``` In this example objects are not loaded at all. You can load the same object more than once - all the returned bean_ptr's will point the same bean. ## Deleting beans To remove an object from the database, call bean_ptr::destroy(): ```cpp bean_ptr<Person> p==db.loadBean<Person>(1); p.destroy(); ``` ## Examples All the above code is put together in sample.cpp. For more demonstration see the poor-mans unit tests : tests.cpp. User-defined class First we define the class we plan to store in the database: ```cpp class MyClass{ friend class hiberlite::access; template<class Archive> void hibernate(Archive & ar) { ar & HIBERLITE_NVP(a); ar & HIBERLITE_NVP(b); ar & HIBERLITE_NVP(vs); } public: int a; double b; vector<string> vs; }; HIBERLITE_EXPORT_CLASS(MyClass) ``` Note the friend declaration and the hibernate(...) template method - these two pieces of code are necessary for hiberlite to access the internal structure of the user-defined class. **HIBERLITE_NVP** is a macro that creates a name-value pair with reference to its argument. **HIBERLITE_EXPORT_CLASS()** defines the root table name for the class. More on this later. ## How it is stored hiberlite will use 2 tables to represent MyClass instances in the database: ```cpp CREATE TABLE MyClass ( a INTEGER, b REAL, hiberlite_id INTEGER PRIMARY KEY AUTOINCREMENT ) CREATE TABLE MyClass_vs_items ( hiberlite_entry_indx INTEGER, hiberlite_id INTEGER PRIMARY KEY AUTOINCREMENT, hiberlite_parent_id INTEGER, item TEXT ) ``` Table MyClass is the root table for MyClass. It will contain one row per object. Columns a and b store values of the corresponding int and double fields. HIBERLITE_EXPORT_CLASS(MyClass) macro simply declares that instances of MyClass must be stored int the MyClass root table and its subtables. MyClass_vs_items table is the "subtable" of MyClass. It is used to store elements