You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
@@ -13,36 +13,11 @@ The primary goals of this library are
13
13
* a native C++ API for object persistence, which feels "at home" for C++ programmers
14
14
* safe code, checked at compile time, without the need to write raw SQL queries
15
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
16
17
17
18
## Detailed design
18
-
### Creating a database object
19
-
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 (more on that later), so it needs to be initialized. If you pass an empty string, an in-memory database will be created (useful for unit-testing).
20
-
```c++
21
-
// initialization needs to happen at program startup
Even though it's not strictly necessary, you are encouraged to finalize the database at program shutdown
33
-
```c++
34
-
// good practice during program shutdown
35
-
#include"database.h"
36
-
37
-
voidMyTearDownCode() {
38
-
...
39
-
Database::Finalize();
40
-
...
41
-
}
42
-
```
43
-
44
-
### Defining the record types and their members
45
-
In order to define a type for persistence, just define its name and its members. For example, the following snippet declares a struct called `Person` and another struct called `Pet`. 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.
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.
46
21
```c++
47
22
// in Person.h
48
23
#include<string>
@@ -89,16 +64,139 @@ MEMBER_REAL(weight)
89
64
//}
90
65
```
91
66
92
-
During the database initialization phase, all record types (here `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, which did not get registered.
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.
93
68
94
-
The following member attributes are allowed:
69
+
The following member attributes are allowed, based on the most commonly used SQLite column types:
95
70
* int64_t -> `MEMBER_INT`
96
71
* double -> `MEMBER_REAL`
97
-
* std::wstring -> `MEMBER_TEXT`. Wide strings are used in order to allow unicode strings to be saved in the database
72
+
* std::wstring -> `MEMBER_TEXT`. Wide strings are used in order to allow unicode text to be saved in the database.
* custom functions -> `FUNC`. The corresponding function must be provided by the programmer.
101
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
+
voidMySetupCode(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.
// 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
0 commit comments