Skip to content

Commit a8ee24b

Browse files
jkaliasjkalias
committed
2 parents 1a80d20 + 040070d commit a8ee24b

File tree

1 file changed

+247
-1
lines changed

1 file changed

+247
-1
lines changed

‎README.md‎

Lines changed: 247 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,249 @@
11
[![CMake Build Matrix](https://github.com/jkalias/sqlite-reflection/actions/workflows/cmake.yml/badge.svg)](https://github.com/jkalias/sqlite-reflection/actions/workflows/cmake.yml)
22
[![GitHub license](https://img.shields.io/github/license/jkalias/functional_cpp)](https://github.com/jkalias/sqlite-reflection/blob/main/LICENSE)
3-
# C++ SQLite with reflection
3+
# C++ API for SQLite with compile time reflection
4+
5+
## Introduction
6+
A core feature of any application is persistence of user data, usually in a database. When there is no need for server storage, or even for fallback and/or backup reasons, SQLite offers a battle-tested and cross-platform solution for local database management.
7+
8+
However, SQLite is written in C, and even though it exposes a [C++ API](https://www.sqlite.org/cintro.html), this tends to be rather verbose and full of details. In addition, the domain expert/programmer should always do manual bookeeping and cleanup of the relevant SQLite objects, so that no memory leaks occur. Finally, all operations are eventually expressed through raw SQL queries, which at the end is rather tedious and repetitive work.
9+
10+
This library is inspired by the approach other languages and frameworks take against the problem of data persistence. Specifically, in C# the [Entity Framework](https://en.wikipedia.org/wiki/Entity_Framework) allows the programmer to focus on modelling the domain, while delegating the responsibility of database management, table allocation and naming, member type annotation and naming and so on, to EF. In Swift the feature of [keypaths](https://developer.apple.com/documentation/swift/keypath) allows the programmer to write safe code, which is checked at compile time. Its predecessor Objective-C has used keypaths extensively in the [Core Data](https://developer.apple.com/documentation/coredata) Framework, which is Apple's database management software stack, using primarily SQLite in the background.
11+
12+
The primary goals of this library are
13+
* a native C++ API for object persistence, which feels "at home" for C++ programmers
14+
* safe code, checked at compile time, without the need to write raw SQL queries
15+
* automatic record registration for all types used in the program, without any additional setup
16+
* a safe and easy API for all CRUD (Create, Read, Update, Delete) operations
17+
18+
## Detailed design
19+
### Model domain record types and their members
20+
In order to define a domain object for persistence, just define its name and its members. For example, the following snippet declares a struct called `Person` and another struct called `Pet`, which will both be saved in the database. This is using the technique of [X Macro](https://en.wikipedia.org/wiki/X_Macro), which will prove out to be indispensable for automation of database operations, and it's the main facilitator of reflection in this library.
21+
```c++
22+
// in Person.h
23+
#include <string>
24+
25+
#define REFLECTABLE Person
26+
#define FIELDS \
27+
MEMBER_TEXT(first_name) \
28+
MEMBER_TEXT(last_name) \
29+
MEMBER_INT(age) \
30+
MEMBER_BOOL(is_vaccinated) \
31+
FUNC(std::wstring GetFullName() const)
32+
#include "reflection.h"
33+
34+
// either inline in the header or in a separate Person.cc file
35+
std::wstring Person::GetFullName() const {
36+
return first_name + L" " + last_name;
37+
}
38+
39+
// equivalent to
40+
//struct Person {
41+
// std::wstring first_name;
42+
// std::wstring last_name;
43+
// int64_t age;
44+
// bool is_vaccinated;
45+
// int64_t id; <--- all records gain an id for unique identification in the database
46+
//
47+
// std::wstring GetFullName() const;
48+
//}
49+
50+
// in Pet.h
51+
#include <string>
52+
53+
#define REFLECTABLE Pet
54+
#define FIELDS \
55+
MEMBER_TEXT(name) \
56+
MEMBER_REAL(weight)
57+
#include "reflection.h"
58+
59+
// equivalent to
60+
// struct Pet {
61+
// std::wstring name;
62+
// double weight;
63+
// int64_t id; <--- id for database
64+
//}
65+
```
66+
67+
During the database initialization phase, all record types (in the example `Person` and `Pet`) will be register in the database and the corresponding tables will be created if needed. No need for manual registration, no runtime errors due to forgotten records.
68+
69+
The following member attributes are allowed, based on the most commonly used SQLite column types:
70+
* int64_t -> `MEMBER_INT`
71+
* double -> `MEMBER_REAL`
72+
* std::wstring -> `MEMBER_TEXT`. Wide strings are used in order to allow unicode text to be saved in the database.
73+
* int64_t -> `MEMBER_INT`
74+
* bool -> `MEMBER_BOOL`
75+
* timestamp -> `MEMBER_DATETIME` (read note below)
76+
* custom functions -> `FUNC`. The corresponding function must be provided by the programmer.
77+
78+
Special note for timestamps. Very often one needs to save a datetime (date with time) in the database for a given record type. C++ has an excellent `std::chrono` library to deal with time and duration, however the most useful features are available only in C++20 (and not guaranteed for all compiler vendors at the time of writing...) In order to facilitate a cross-platform solution which works all the way down to C++11, all datetimes are stored in their UTC [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) representation, by leveraging the (awesome) [date](https://github.com/HowardHinnant/date) library of Howard Hinnant, one of the main actors behind `std::chrono`.
79+
80+
### Creating a database object
81+
All database interactions are funneled through the database object. Before the database is accessed, it needs to know what record types it will operate on (as defined above), so it needs to be initialized. If you pass an empty string, an in-memory database will be created (useful for unit-testing).
82+
```c++
83+
// initialization needs to happen at program startup
84+
#include "database.h"
85+
86+
void MySetupCode(const std::string& db_path) {
87+
...
88+
Database::Initialize(db_path);
89+
...
90+
}
91+
```
92+
93+
Even though it's not strictly necessary, you are encouraged to finalize the database at program shutdown
94+
```c++
95+
// good practice during program shutdown
96+
#include "database.h"
97+
98+
void MyTearDownCode() {
99+
...
100+
Database::Finalize();
101+
...
102+
}
103+
```
104+
### Persist records (Save)
105+
In order to save objects in the database, you first need to get a hold of the database object and then pass it the records for persistence. You don't _have_ to pass multiple records, you can only use one if you need to.
106+
```c++
107+
const auto& db = Database::Instance();
108+
std::vector<Person> persons;
109+
110+
// id is here given - 5
111+
persons.push_back({L"peter", L"meier", 32, true, 5});
112+
... // add more records for persistence
113+
114+
db.Save(persons);
115+
116+
// if you don't want to manage the id yourself, just let the database manage it
117+
// leave the last argument empty (it's always the id)
118+
// persons.push_back({L"peter", L"meier", 32, true});
119+
120+
// this will set the record id to the next available value
121+
// db.SaveAutoIncrement(persons);
122+
```
123+
### Retrieve records (Read)
124+
In order to fetch records of a given type from the database, you first need to get a hold of the database object and then call a variant of the `Fetch` operation.
125+
```c++
126+
// assume that these persons have been previously saved in the database
127+
// {L"name1", L"surname1", 13, false, 1}
128+
// {L"john", L"surname2", 25, false, 2}
129+
// {L"john", L"surname3", 37, false, 3}
130+
// {L"jame", L"surname4", 45, false, 4}
131+
// {L"name5", L"surname5", 56, false, 5}
132+
133+
const auto& db = Database::Instance();
134+
135+
// retrieve all persons stored
136+
const auto all_persons = db.FetchAll<Person>();
137+
138+
// retrieve a person from a given id
139+
const auto specific_person = db.Fetch<Person>(5);
140+
141+
// create a custom predicate
142+
const auto fetch_condition = GreaterThanOrEqual(&Person::id, 2)
143+
.And(SmallerThan(&Person::id, 5))
144+
.And(Equal(&Person::first_name, L"john"));
145+
146+
// retrieve persons with custom predicate
147+
// this will fetch only
148+
// Person{L"john", L"surname2", 25, false, 2}
149+
// and
150+
// Person{L"john", L"surname3", 37, false, 3}
151+
const auto fetched_persons_with_predicate = db.Fetch<Person>(&fetch_condition);
152+
```
153+
154+
### Update records
155+
Updating records couldn't be simpler: just manipulate the needed members of the given records, and ship them back to the database for update.
156+
```c++
157+
// assume that these persons have been previously saved in the database
158+
// {L"john", L"doe", 28, false, 3}
159+
// {L"mary", L"poppins", 29, false, 5}
160+
161+
const auto& db = Database::Instance();
162+
163+
// retrieve all records
164+
std::vector<Person> persons = db.FetchAll<Person>();
165+
166+
// update the records as needed
167+
persons[0].last_name = L"rambo";
168+
persons[1].age = 20;
169+
170+
// update the records in the database
171+
db.Update(persons);
172+
```
173+
174+
### Delete records
175+
Deleting records can be done in three variants: with a given id, by passing the whole record, or by a custom predicate.
176+
```c++
177+
// assume that these persons have been previously saved in the database
178+
// {L"παναγιώτης", L"ανδριανόπουλος", 28, true, 3}
179+
// {L"peter", L"meier", 32, false, 5}
180+
// {L"mary", L"poppins", 20, true, 13}
181+
182+
const auto& db = Database::Instance();
183+
184+
const auto age_match_predicate = SmallerThan(&Person::age, 30)
185+
.And(Equal(&Person::is_vaccinated, true));
186+
187+
// this will leave only {L"peter", L"meier", 32, false, 5} in the database
188+
db.Delete<Person>(&age_match_predicate);
189+
190+
// this would delete the 3rd record entry of the vector
191+
// std::vector<Person> persons = db.FetchAll<Person>();
192+
// db.Delete(persons[2]);
193+
194+
// this would delete the record entry from its id
195+
// db.Delete<Person>(persons[1].id);
196+
// or
197+
// db.Delete<Person>(5);
198+
```
199+
200+
## Compilation (Cmake)
201+
### Dependencies
202+
* CMake >= 3.14
203+
204+
### Minimum C++ version
205+
* C++11
206+
207+
An out-of-source build strategy is used. All following examples assume an output build folder named ```build```. If no additional argument is passed to CMake, C++11 is used. Otherwise, you can pass ```-DCMAKE_CXX_STANDARD=20``` and it will use C++20 for example.
208+
### macOS (Xcode)
209+
```console
210+
cd sqlite-reflection
211+
cmake -S . -B build -G Xcode
212+
```
213+
Then open the generated ```sqlite-reflection.xcodeproj``` in the ```build``` folder.
214+
215+
### macOS (Makefiles/clang)
216+
```console
217+
cd sqlite-reflection
218+
cmake -S . -B build
219+
cmake --build build
220+
build/tests/unit_tests
221+
```
222+
223+
### macOS (Makefiles/g++)
224+
Assuming you have installed Homebrew, you can then use the gcc and g++ compilers by doing the following (this example uses version gcc 11)
225+
```console
226+
cd sqlite-reflection
227+
cmake \
228+
-S . \
229+
-B build \
230+
-DCMAKE_C_COMPILER=/opt/homebrew/Cellar/gcc/11.2.0/bin/gcc-11 \
231+
-DCMAKE_CXX_COMPILER=/opt/homebrew/Cellar/gcc/11.2.0/bin/g++-11
232+
cmake --build build
233+
build/tests/unit_tests
234+
```
235+
236+
### Linux (Makefiles)
237+
```console
238+
cd sqlite-reflection
239+
cmake -S . -B build
240+
cmake --build build
241+
build/tests/unit_tests
242+
```
243+
244+
### Windows (Visual Studio)
245+
```console
246+
cd sqlite-reflection
247+
cmake -S . -B build
248+
```
249+
Then open the generated ```sqlite-reflection.sln``` in the ```build``` folder.

0 commit comments

Comments
 (0)