QtOrm is an unofficial object-relational mapping module for the Qt Framework (http://qt.io).
The current version is a prototype and a proof-of-concept.
Refer to qws19.pdf for more examples.
Copyright (C) 2019 Dmitriy Purgin dmitriy.purgin@sequality.at
Copyright (C) 2019 sequality software engineering e.U. office@sequality.at
QtOrm is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
QtOrm is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with QtOrm. If not, see https://www.gnu.org/licenses/.
The QtOrm library is being built on top of Qt 5.12 LTS and requires a C++17-compliant compiler with C++ standard library support. QtOrm depends on Qt Core and Qt SQL.
The library is currently being developed and tested with MinGW 7 on Windows 10, other compilers and platforms might be supported but not guaranteed.
- Open qtorm.pro with Qt Creator
- Configure with the required Qt kit (Qt 5.12 at least, C++17-compliant compiler)
- Build
- Deploy with
make install
QtOrm currently supports SQLite backend with the following operations:
- Creating database schema according to the registered entities in the OR-mapper
- Reading data from a table, optionally filtered and ordered
- Inserting and/or updating rows
- Removing single rows
- Transaction support
- 1:n, n:1 relations support
Domain classes representing table entities must be derived from QObject. Class names will be mapped
to database tables with the same name. All properties declared with Q_PROPERTY() will be mapped
to database columns with the same names.
All mappable properties must be readable, writable, and notifyable.
Every entity must have proprety int id. This property will be set to autogenerated by the
SQLite backend.
Every entity must have a default constructor declared with Q_INVOKABLE, otherwise the OR mapper will not be able to instantiate it when fetching data.
All entities must be registered at most once before the first QOrmSession instantiation:
qRegisterOrmEntity<Entity1, Entity2, Entity3, ...>();
A 1:n relation can be created by declaring a QVector of related entities as follows:
class Town;
class Province : public QObject
{
Q_OBJECT
Q_PROPERTY(int id READ id WRITE setId NOTIFY idChanged)
Q_PROPERTY(QVector<Town*> towns READ towns WRITE setTowns NOTIFY townsChanged)
// the rest of the class skipped
};
In this case the property towns will be transient and will not be mapped to a database column.
This requires that there is an n:1 back-reference to Province in the Town entity. When updating
the reference, keep in mind that change is required on both sides. For example, when adding a Town
to a Province, add this object to the vector towns and set the back-reference of Town to the
corresponding Province.
An n:1 relation can be created by declaring a pointer to the referenced entity as follows:
class Province;
class Town : public QObject
{
Q_OBJECT
Q_PROPERTY(int id READ id WRITE setId NOTIFY idChanged)
Q_PROPERTY(Province* province READ province WRITE setProvince NOTIFY provinceChanged)
// the rest of the class skipped
};
The SQLite provider maps the property province to a database column province_id with the column
type set to the mapped type of Province::id. Back-reference in Province is optional.
An instance of QOrmSession is the entry point to the OR mapper. All database operations should be
performed using a single instance of a QOrmSession.
An instance of QOrmSession can be configured either by using an instance of QOrmSessionConfiguration
or automatically from qtorm.json file located either in resources root, worki
61EC
ng directory, or
the application executable directory.
{
"provider": "sqlite",
"verbose": true,
"sqlite": {
"databaseName": "database.sqlite",
"schemaMode": "recreate",
"verbose": true
}
}
Possible values for schemaMode: recreate, bypass.
Any other JSON keys are silently ignored.