Wraps sqlite3_session when SQLite is compiled with
SQLITE_ENABLE_SESSION. Sessions record row-level changes so they can be
applied elsewhere via changesets or patchsets.
Use cases
- Perfect for synchronization pipelines—capture edits locally, ship the blob, and replay it on a remote connection.
- Patchsets are smaller but lossy (no “prior values”). Changesets keep enough context to resolve conflicts; pick the format that matches your workflow.
- Use
set_indirect(true)when re-applying incoming changes so they do not loop back into the session you are recording for outbound sync.
session_options
| Member | Description |
|---|---|
bool indirect = false | Marks tracked changes as indirect so filters can ignore them. |
Example usage
if (!sqlite::sessions_supported()) {
return;
}
sqlite::session sess{db};
sess.attach_all();
sqlite::transaction tx{db};
apply_business_updates();
tx.commit();
auto payload = sess.changeset();
sqlite::apply_changeset(replica, payload);
When you replay incoming blobs, tap sqlite3changeset_start_v2 via
native_handle() if you need to plug in custom conflict resolution.
session
| Member | Description |
|---|---|
session(connection&, std::string_view schema = "main", session_options opts = {}) | Constructs a session associated with schema. |
~session() | Closes the underlying sqlite3_session*. |
session(session&&) noexcept, session& operator=(session&&) noexcept | Transfer ownership. |
session(session const&)=delete, session& operator=(session const&)=delete | Non-copyable. |
void attach(std::string_view table) | Track changes for a specific table. |
void attach_all() | Track changes for every table in the schema. |
void enable(bool value) | Enable or disable capturing. |
void set_indirect(bool value) | Marks subsequent changes as indirect. |
std::vector<unsigned char> changeset() | Serializes accumulated changes in the standard changeset format. |
std::vector<unsigned char> patchset() | Serializes in the smaller patchset format. |
void* native_handle() const noexcept | Returns the raw sqlite3_session*. |
Free helpers
| Function | Description |
|---|---|
constexpr bool sessions_supported() noexcept | Indicates whether session APIs are enabled. |
void apply_changeset(connection&, std::span<const unsigned char> data) | Applies a captured changeset to a connection. |
void apply_patchset(connection&, std::span<const unsigned char> data) | Applies a patchset. |