Database Connection. More...

Inheritance diagram for database:

Classes
struct	column_metadata
	Return type for table_column_metadata() More...

struct	status
	Return type for status() More...

Public Member Functions
	~database () noexcept
	Equivalent to sqlite3_close_v2.

void	busy_timeout (int ms)
	Set a busy timeout.

int64_t	changes () const noexcept
	Count of the number of rows modified.

void	cacheflush ()
	Flush caches to disk mid-transaction.

template<int Code, class ... Args>
auto	config (Args &&...args) -> void
	Configure database connection.

void	extended_result_codes (bool onoff)
	Enable or disable extended result codes.

void	file_control (const string_param &db_name, int op, void *data)
	Low-level control of database file.

const char *	filename (const string_param &db_name) const noexcept
	Return the filename for the database connection.

bool	get_autocommit () const noexcept
	Return the auto-commit mode.

void	interrupt () noexcept
	Interrupt a long-running query.

bool	is_interrupted () noexcept
	Returns whether or not an interrupt is currently in effect.

int64_t	last_insert_rowid () const noexcept
	Returns last insert rowid.

void	set_last_insert_rowid (int64_t value) noexcept
	Set the last insert rowid value.

int	limit (int id, int new_val) noexcept
	Set or retrieve run-time limits.

class mutex *	mutex () const noexcept
	Retrieve the mutex for the database connection.

const class statement *	next_statement (const class statement *prev) const noexcept
	Find the next prepared statement.

class statement *	next_statement (const class statement *prev) noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	overload_function (const string_param &name, int arg_count) noexcept
	Overload a function for a virtual table.

template<class T >
void	progress_handler (int step_count, int(*handler)(type_identity_t< T > data_ptr) noexcept, T data_ptr) const noexcept
	Register a callback to be called on query progress.

template<class T >
void	progress_handler (int step_count, T handler_ptr) const noexcept
	Register a callback to be called on query progress.

std::optional< bool >	readonly (const string_param &db_name) const noexcept
	Determine if a database is read-only.

void	release_memory () const
	Free memory used by the database connection.

struct status	status (int op, bool reset=false) const
	Retrieve database connection status.

column_metadata	table_column_metadata (const string_param &db_name, const string_param &table_name, const string_param &column_name) const
	Extract metadata about a column of a table.

int64_t	total_changes () const noexcept
	Returns total number of rows modified.

int	txn_state (const string_param &schema) const noexcept
	Returns the transaction state of a database.

std::unique_ptr< blob >	open_blob (const string_param &dbname, const string_param &table, const string_param &column, int64_t rowid, bool writable)
	Open a blob.

const char *	db_name (int idx) noexcept
	Return schema names.

void	operator delete (void *) noexcept
	Operator delete for a fake pointer is no-op.

sqlite3 *	c_ptr () const noexcept
	Access the real underlying SQLite type.

Executing queries

void	exec (std::string_view sql)
	Run multiple statements of SQL.

template<class T >
T	exec (std::u8string_view sql)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T >
T	exec (std::string_view sql, T callback)
	Run multiple statements of SQL with a callback.

template<class T >
T	exec (std::u8string_view sql, T callback)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Callbacks and notifications

template<class T >
void	busy_handler (int(*handler)(type_identity_t< T > data_ptr, int count_invoked) noexcept, T data_ptr)
	Register a callback to handle SQLITE_BUSY errors.

template<class T >
void	busy_handler (T handler_ptr)
	Register a callback to handle SQLITE_BUSY errors.

template<class T >
void	collation_needed (T data_ptr, void(handler)(type_identity_t< T > data_ptr, database , int encoding, const char *name) noexcept)
	Register a callback to be called when undefined collation sequence is required.

template<class T >
void	collation_needed (T handler_ptr)
	Register a callback to be called when undefined collation sequence is required.

template<class T >
void	commit_hook (int(*handler)(type_identity_t< T > data_ptr) noexcept, T data_ptr) noexcept
	Register a callback to be called on commit.

template<class T >
void	commit_hook (T handler_ptr) noexcept
	Register a callback to be called on commit.

template<class T >
void	rollback_hook (void(*handler)(type_identity_t< T > data_ptr) noexcept, T data_ptr) noexcept
	Register a callback to be called on rollback.

template<class T >
void	rollback_hook (T handler_ptr) noexcept
	Register a callback to be called on rollback.

template<class T >
void	update_hook (void(handler)(type_identity_t< T > data_ptr, int op, const char db_name, const char *table, sqlite3_int64 rowid) noexcept, T data_ptr) noexcept
	Register a callback to be called whenever a row is updated, inserted or deleted in a rowid table.

template<class T >
void	update_hook (T handler_ptr) noexcept
	Register a callback to be called whenever a row is updated, inserted or deleted in a rowid table.

template<class T >
void	preupdate_hook (void(handler)(type_identity_t< T > data_ptr, database db, int op, const char db_name, const char table, sqlite3_int64 rowid_old, sqlite3_int64 rowid_new) noexcept, T data_ptr) noexcept
	Register a callback to be called prior to each INSERT, UPDATE, and DELETE operation on a database table.

template<class T >
void	preupdate_hook (T handler_ptr) noexcept
	Register a callback to be called prior to each INSERT, UPDATE, and DELETE operation on a database table.

template<class T >
void	wal_hook (int(handler)(type_identity_t< T > data_ptr, database db, const char *db_name, int num_pages) noexcept, T data_ptr) noexcept
	Register a callback to be called each time data is committed to a database in wal mode.

template<class T >
void	wal_hook (T handler_ptr) noexcept
	Register a callback to be called each time data is committed to a database in wal mode.

Preupdate hook helpers
value *	preupdate_old (int column_idx)
	Returns value of a column of the table row before it is updated.

value *	preupdate_new (int column_idx)
	Returns value of a column of the table row after it is updated.

int	preupdate_count () const noexcept
	Returns the number of columns in the row that is being inserted, updated, or deleted.

int	preupdate_depth () const noexcept
	Returns the "depth" of an update from the top level SQL.

int	preupdate_blobwrite () const noexcept
	Returns the index of the column being written via sqlite3_blob_write.

WAL checkpoint control
std::pair< int, int >	checkpoint (const string_param &db_name, int mode=SQLITE_CHECKPOINT_PASSIVE)
	Checkpoint a database.

void	autocheckpoint (int num_frames)
	Configure an auto-checkpoint.

Defining collating sequences

template<class T >
void	create_collation (const string_param &name, int encoding, T collator_ptr, int(compare)(type_identity_t< T > collator, int lhs_len, const void lhs_bytes, int rhs_len, const void rhs_bytes) noexcept, void(destructor)(type_identity_t< T > collator) noexcept)
	Define a new collating sequence.

template<class T >
void	create_collation (const string_param &name, int encoding, T collator_ptr, void(*destructor)(type_identity_t< T > obj) noexcept=nullptr)
	Define a new collating sequence.

Creating or redefining SQL functions

template<class T >
void	create_function (const char name, int arg_count, int flags, T data_ptr, void(func)(context , int, value ) noexcept, void(step)(context , int, value ) noexcept, void(last)(context ) noexcept, void(destructor)(type_identity_t< T > data_ptr) noexcept)
	Create or redefine SQL function.

template<class T >
void	create_function (const char name, int arg_count, int flags, T impl_ptr, void(destructor)(type_identity_t< T > obj) noexcept=nullptr)
	Create or redefine SQL function.

template<class T >
void	create_window_function (const char name, int arg_count, int flags, T data_ptr, void(step)(context , int, value ) noexcept, void(last)(context ) noexcept, void(current)(context ) noexcept, void(inverse)(context , int, value ) noexcept, void(destructor)(type_identity_t< T > data_ptr) noexcept)
	Create or redefine SQL aggregate window function

template<class T >
void	create_window_function (const char name, int arg_count, int flags, T impl_ptr, void(destructor)(type_identity_t< T > obj) noexcept=nullptr)
	Create or redefine SQL aggregate window function

Virtual Table Modules

void	create_module (const string_param &name, const sqlite3_module *mod)
	Register a virtual table implementation.

template<typename T >
void	create_module (const string_param &name, const sqlite3_module mod, T data, void(destructor)(T )=nullptr)
	Register a virtual table implementation.

void	declare_vtab (const string_param &sdl)
	Declare the schema of a virtual table.

template<int Code, class ... Args>
auto	vtab_config (Args &&...args) -> void
	Configure virtual table.

int	vtab_on_conflict () const noexcept
	Determine the virtual table conflict policy.

void	drop_modules ()
	Remove all virtual table modules from database connection.

void	drop_modules_except (const char const keep)
	Remove virtual table modules from database connection.

template<size_t N>
void	drop_modules_except (const char *const (&keep)[N])
	Remove virtual table modules from database connection.

template<class ... Args>
void	drop_modules_except (Args &&...args)
	Remove virtual table modules from database connection.

Extension management
void	enable_load_extension (bool val)
	Enable or disable extension loading.

void	load_extension (const string_param &file, const string_param &proc=nullptr)
	Load an extension.

void	auto_extension (void(entry_point)(database , const char *, const struct sqlite3_api_routines ))
	Automatically load statically linked extension.

void	cancel_auto_extension (void(entry_point)(database , const char *, const struct sqlite3_api_routines ))
	Cancel automatic extension Loading.

void	reset_auto_extension () noexcept
	Reset automatic extension loading.

Serialization
std::pair< allocated_bytes, size_t >	serialize (const string_param &schema_name)
	Serialize a database.

span< std::byte >	serialize_reference (const string_param &schema_name) noexcept
	Serialize a database.

void	deserialize (const string_param &schema_name, std::byte *buf, size_t size, size_t buf_size, unsigned flags=0)
	Deserialize a database.

void	deserialize (const string_param &schema_name, const std::byte *buf, size_t size, size_t buf_size, unsigned flags=0)
	Deserialize a database.

void	deserialize (const string_param &schema_name, allocated_bytes buf, size_t size, size_t buf_size, unsigned flags=0)
	Deserialize a database.

Snapshots
std::unique_ptr< snapshot >	get_snapshot (const string_param &schema)
	Record a database snapshot.

void	open_snapshot (const string_param &schema, const snapshot &snap)
	Start a read transaction on an historical snapshot.

void	recover_snapshot (const string_param &db)
	Recover snapshots from a wal file.

Static Public Member Functions
static std::unique_ptr< database >	open (const string_param &db_filename, int flags, const char *vfs=nullptr)
	Open a new database connection.

static database *	from (sqlite3 *obj) noexcept
	Create fake pointer from the underlying SQLite one.

Detailed Description

Database Connection.

This is a fake wrapper class for sqlite3.

#include <thinsqlitepp/database.hpp>

Class Documentation

◆ thinsqlitepp::database::column_metadata

struct thinsqlitepp::database::column_metadata

Return type for table_column_metadata()

Class Members
const char *	data_type	Declared data type.
const char *	collation_sequence	Collation sequence name.
bool	not_null	Whether NOT NULL constraint exists.
bool	primary_key	Whether column part of PK.
bool	auto_increment	Whether column is auto-increment.

◆ thinsqlitepp::database::status

struct thinsqlitepp::database::status

Return type for status()

Class Members
int	current
int	high

Member Function Documentation

◆ open()

static std::unique_ptr< database > open	(	const string_param &	db_filename,
		int	flags,
		const char *	vfs = nullptr )

static

Open a new database connection.

Equivalent to sqlite3_open_v2

◆ busy_timeout()

void busy_timeout ( int ms )

inline

Set a busy timeout.

Equivalent to sqlite3_busy_timeout

◆ changes()

int64_t changes ( ) const

inlinenoexcept

Count of the number of rows modified.

Equivalent to sqlite3_changes

◆ exec() [1/2]

void exec ( std::string_view sql )

Run multiple statements of SQL.

Unlike other functions in this library this one DOES NOT delegate to sqlite3_exec but instead implements equivalent functionality directly.

It runs zero or more UTF-8 encoded, semicolon-separate SQL statements passed as the sql argument. If an error occurs while evaluating the SQL statements then execution of the current statement stops and subsequent statements are skipped.

As usual the error will be reported via an exception

Parameters

sql	Statements to execute

◆ exec() [2/2]

template<class T >

T exec	(	std::string_view	sql,
		T	callback )

Run multiple statements of SQL with a callback.

Unlike other functions in this library this one DOES NOT delegate to sqlite3_exec but instead implements equivalent functionality directly.

It runs zero or more UTF-8 encoded, semicolon-separate SQL statements passed as the sql argument. The callback callable is passed by value and is invoked for each result row coming out of the evaluated SQL statements. The callable can have one of the 4 possible variants:

bool callback(int statement_idx, row current_row)
void callback(int statement_idx, row current_row)
bool callback(row current_row)
void callback(row current_row)

If more than one way of calling the callback is possible the way it will be invoked is chosen in the order given above.

For variants 1 and 3 if an invocation of callback returns false then the execution of the current statement stops and subsequent statements are skipped.

For variants 1 and 2 the statement_idx is the index of the SQL statement being executed. If you only pass a single statement to exec() you generally don't need these variants.

The callback argument is returned back from the function which allows it to accumulate state.

If an error occurs while evaluating the SQL statements then execution of the current statement stops and subsequent statements are skipped.

As usual the error will be reported via an exception

Parameters

sql	Statements to execute
callback	Callback to execute for each row of the results

Returns: the callback argument

◆ busy_handler() [1/2]

template<class T >

void busy_handler	(	int(*	handler )(type_identity_t< T > data_ptr, int count_invoked) noexcept,
		T	data_ptr )

inline

Register a callback to handle SQLITE_BUSY errors.

Equivalent to sqlite3_busy_handler

Parameters

handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.
data_ptr	A pointer to callback data or nullptr.

◆ busy_handler() [2/2]

template<class T >

void busy_handler ( T handler_ptr )

Register a callback to handle SQLITE_BUSY errors.

Equivalent to sqlite3_busy_handler

Parameters

handler_ptr

A pointer to any C++ callable that can be invoked as

int count_invoked = ...;

bool result = (*handler_ptr)(count_invoked);

This invocation must be noexcept. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

◆ collation_needed() [1/2]

template<class T >

void collation_needed	(	T	data_ptr,
		void(*	handler )(type_identity_t< T > data_ptr, database , int encoding, const char name) noexcept )

inline

Register a callback to be called when undefined collation sequence is required.

Equivalent to sqlite3_collation_needed

Parameters

data_ptr	A pointer to callback data or nullptr.
handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.

◆ collation_needed() [2/2]

template<class T >

void collation_needed ( T handler_ptr )

Register a callback to be called when undefined collation sequence is required.

Equivalent to sqlite3_collation_needed

Parameters

handler_ptr

A pointer to any C++ callable that can be invoked as

database * db = ...;
int encoding = <one of SQLITE_UTF8, SQLITE_UTF16BE, or SQLITE_UTF16LE>
const char * name = ...;
(*handler_ptr)(db, encoding, name);

This invocation must be noexcept. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

◆ commit_hook() [1/2]

template<class T >

void commit_hook	(	int(*	handler )(type_identity_t< T > data_ptr) noexcept,
		T	data_ptr )

inlinenoexcept

Register a callback to be called on commit.

Equivalent to sqlite3_commit_hook

Parameters

handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.
data_ptr	A pointer to callback data or nullptr.

◆ commit_hook() [2/2]

template<class T >

void commit_hook ( T handler_ptr )

noexcept

Register a callback to be called on commit.

Equivalent to sqlite3_commit_hook

Parameters

handler_ptr

A pointer to any C++ callable that can be invoked as

bool result = (*handler_ptr)();

This invocation must be noexcept. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

◆ rollback_hook() [1/2]

template<class T >

void rollback_hook	(	void(*	handler )(type_identity_t< T > data_ptr) noexcept,
		T	data_ptr )

inlinenoexcept

Register a callback to be called on rollback.

Equivalent to sqlite3_rollback_hook

Parameters

handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.
data_ptr	A pointer to callback data or nullptr.

◆ rollback_hook() [2/2]

template<class T >

void rollback_hook ( T handler_ptr )

noexcept

Register a callback to be called on rollback.

Equivalent to sqlite3_rollback_hook

Parameters

handler_ptr

A pointer to any C++ callable that can be invoked as

(*handler_ptr)();

This invocation must be noexcept. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

◆ update_hook() [1/2]

template<class T >

void update_hook	(	void(*	handler )(type_identity_t< T > data_ptr, int op, const char db_name, const char table, sqlite3_int64 rowid) noexcept,
		T	data_ptr )

inlinenoexcept

Register a callback to be called whenever a row is updated, inserted or deleted in a rowid table.

Equivalent to sqlite3_update_hook

Parameters

handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.
data_ptr	A pointer to callback data or nullptr.

◆ update_hook() [2/2]

template<class T >

void update_hook ( T handler_ptr )

noexcept

Register a callback to be called whenever a row is updated, inserted or deleted in a rowid table.

Equivalent to sqlite3_update_hook

Parameters

handler_ptr

A pointer to any C++ callable that can be invoked as

(*handler_ptr)(int op, const char * db_name, const char * table, int64_t rowid);

thinsqlitepp::database::db_name

const char * db_name(int idx) noexcept

Return schema names.

Definition database_iface.hpp:1478

This invocation must be noexcept. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

◆ preupdate_hook() [1/2]

template<class T >

void preupdate_hook	(	void(*	handler )(type_identity_t< T > data_ptr, database db, int op, const char db_name, const char *table, sqlite3_int64 rowid_old, sqlite3_int64 rowid_new) noexcept,
		T	data_ptr )

inlinenoexcept

Register a callback to be called prior to each INSERT, UPDATE, and DELETE operation on a database table.

Equivalent to sqlite3_preupdate_hook

Available only if SQLITE_ENABLE_PREUPDATE_HOOK is defined during compilation

Parameters

handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.
data_ptr	A pointer to callback data or nullptr.

Since: SQLite 3.16

◆ preupdate_hook() [2/2]

template<class T >

void preupdate_hook ( T handler_ptr )

noexcept

Register a callback to be called prior to each INSERT, UPDATE, and DELETE operation on a database table.

Equivalent to sqlite3_preupdate_hook

Available only if SQLITE_ENABLE_PREUPDATE_HOOK is defined during compilation

Parameters

handler_ptr

A pointer to any C++ callable that can be invoked as

(*handler_ptr)(database * db, int op, const char * db_name, const char * table, int64_t rowid_old, int64_t rowid_new);

This invocation must be noexcept. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

Since: SQLite 3.16

◆ wal_hook() [1/2]

template<class T >

void wal_hook	(	int(*	handler )(type_identity_t< T > data_ptr, database db, const char db_name, int num_pages) noexcept,
		T	data_ptr )

inlinenoexcept

Register a callback to be called each time data is committed to a database in wal mode.

Equivalent to sqlite3_wal_hook

Parameters

handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.
data_ptr	A pointer to callback data or nullptr.

◆ wal_hook() [2/2]

template<class T >

void wal_hook ( T handler_ptr )

noexcept

Register a callback to be called each time data is committed to a database in wal mode.

Equivalent to sqlite3_wal_hook

Parameters

handler_ptr

A pointer to any C++ callable that can be invoked as

(*handler_ptr)(const char * db_name, int num_pages);

This invocation can throw exceptions. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

◆ preupdate_old()

value * preupdate_old ( int column_idx )

Returns value of a column of the table row before it is updated.

Equivalent to sqlite3_preupdate_old

This can only be called from a pre-update hook. Available only if SQLITE_ENABLE_PREUPDATE_HOOK is defined during compilation

Since: SQLite 3.16

◆ preupdate_new()

value * preupdate_new ( int column_idx )

Returns value of a column of the table row after it is updated.

Equivalent to sqlite3_preupdate_new

This can only be called from a pre-update hook. Available only if SQLITE_ENABLE_PREUPDATE_HOOK is defined during compilation

Since: SQLite 3.16

◆ preupdate_count()

int preupdate_count ( ) const

inlinenoexcept

Returns the number of columns in the row that is being inserted, updated, or deleted.

Equivalent to sqlite3_preupdate_count

This can only be called from a pre-update hook. Available only if SQLITE_ENABLE_PREUPDATE_HOOK is defined during compilation

Since: SQLite 3.16

◆ preupdate_depth()

int preupdate_depth ( ) const

inlinenoexcept

Returns the "depth" of an update from the top level SQL.

Equivalent to sqlite3_preupdate_depth

This can only be called from a pre-update hook. Available only if SQLITE_ENABLE_PREUPDATE_HOOK is defined during compilation

Returns: 0 if the preupdate callback was invoked as a result of a direct insert, update, or delete operation; or 1 for inserts, updates, or deletes invoked by top-level triggers; or 2 for changes resulting from triggers called by top-level triggers; and so forth.

Since: SQLite 3.16

◆ preupdate_blobwrite()

int preupdate_blobwrite ( ) const

inlinenoexcept

Returns the index of the column being written via sqlite3_blob_write.

Equivalent to sqlite3_preupdate_blobwrite

This can only be called from a pre-update hook. Available only if SQLITE_ENABLE_PREUPDATE_HOOK is defined during compilation

Since: SQLite 3.36

◆ checkpoint()

std::pair< int, int > checkpoint	(	const string_param &	db_name,
		int	mode = SQLITE_CHECKPOINT_PASSIVE )

Checkpoint a database.

Equivalent to sqlite3_wal_checkpoint_v2

Parameters

db_name	Name of attached database (or nullptr)
mode	One of SQLITE_CHECKPOINT_ values

Returns: A pair of {Size of WAL log in frames, Total number of frames checkpointed} or {-1, -1} if the database is not in WAL mode

◆ autocheckpoint()

void autocheckpoint ( int num_frames )

inline

Configure an auto-checkpoint.

Equivalent to sqlite3_wal_autocheckpoint

◆ create_collation() [1/2]

template<class T >

void create_collation	(	const string_param &	name,
		int	encoding,
		T	collator_ptr,
		int(*	compare )(type_identity_t< T > collator, int lhs_len, const void lhs_bytes, int rhs_len, const void rhs_bytes) noexcept,
		void(*	destructor )(type_identity_t< T > collator) noexcept )

Define a new collating sequence.

Equivalent to sqlite3_create_collation_v2

Parameters

name	Collation name
encoding	One of SQLite text encodings
collator_ptr	A pointer to a collator or nullptr.
compare	A collating function that matches the type of `collator_ptr` argument. Can be nullptr.
destructor	A "destructor" function for the `collator_ptr` argument. Can be nullptr.

◆ create_collation() [2/2]

template<class T >

void create_collation	(	const string_param &	name,
		int	encoding,
		T	collator_ptr,
		void(*	destructor )(type_identity_t< T > obj) noexcept = nullptr )

Define a new collating sequence.

Equivalent to sqlite3_create_collation_v2

Parameters

name	Collation name
encoding	One of SQLite text encodings
collator_ptr	A pointer to any C++ callable that can be invoked as span<const std::byte> lhs = ...; span<const std::byte> rhs = ...; int res = (*collator_ptr)(lhs, rhs); std::span This invocation must be `noexcept`. This parameter can also be nullptr to reset the collator.
destructor	A "destructor" function for the `collator_ptr` argument. Can be nullptr. Unlike the sqlite3_create_collation_v2 the `destructor` is always called even if this function throws an exception.

◆ create_function() [1/2]

template<class T >

void create_function	(	const char *	name,
		int	arg_count,
		int	flags,
		T	data_ptr,
		void(*	func )(context , int, value *) noexcept,
		void(*	step )(context , int, value *) noexcept,
		void(*	last )(context *) noexcept,
		void(*	destructor )(type_identity_t< T > data_ptr) noexcept )

Create or redefine SQL function.

Equivalent to sqlite3_create_function_v2

Parameters

name	Name of the SQL function to be created or redefined
arg_count	The number of arguments that the SQL function takes. If this parameter is -1, then the SQL function may take any number of arguments.
flags	Combination of Text encoding flags that specify what encoding this SQL function prefers for its parameters Function flags
data_ptr	A pointer to callback data or nullptr. The implementation of the function can gain access to this pointer using context::user_data().
func	Function callback. See sqlite3_create_function_v2
step	Step callback. See sqlite3_create_function_v2
last	Last callback. See sqlite3_create_function_v2
destructor	A "destructor" function for `data_ptr`. Can be nullptr.

◆ create_function() [2/2]

template<class T >

void create_function	(	const char *	name,
		int	arg_count,
		int	flags,
		T	impl_ptr,
		void(*	destructor )(type_identity_t< T > obj) noexcept = nullptr )

Create or redefine SQL function.

Equivalent to sqlite3_create_function_v2

Parameters

name	Name of the SQL function to be created or redefined
arg_count	The number of arguments that the SQL function takes. If this parameter is -1, then the SQL function may take any number of arguments.
flags	Combination of Text encoding flags that specify what encoding this SQL function prefers for its parameters Function flags
impl_ptr	A pointer to C++ object that implements the function or nullptr. The C++ object pointed to it needs to: For scalar SQL function only be callable as: (impl_ptr)(context , int, value ); thinsqlitepp::context SQL Function Context Object. Definition context_iface.hpp:37 thinsqlitepp::value Dynamically Typed Value Object. Definition value_iface.hpp:35 For aggregate SQL function only** be callable as: impl_ptr->step(context , int, value ); impl_ptr->last(context ); If impl_ptr is nullptr the function is removed.
destructor	A "destructor" function for `impl_ptr`. Can be nullptr.

◆ create_window_function() [1/2]

template<class T >

void create_window_function	(	const char *	name,
		int	arg_count,
		int	flags,
		T	data_ptr,
		void(*	step )(context , int, value *) noexcept,
		void(*	last )(context *) noexcept,
		void(*	current )(context *) noexcept,
		void(*	inverse )(context , int, value *) noexcept,
		void(*	destructor )(type_identity_t< T > data_ptr) noexcept )

Create or redefine SQL aggregate window function

Equivalent to sqlite3_create_window_function

Parameters

name	Name of the SQL function to be created or redefined
arg_count	The number of arguments that the SQL aggregate takes. If this parameter is -1, then the SQL aggregate may take any number of arguments.
flags	Combination of Text encoding flags that specify what encoding this SQL function prefers for its parameters Function flags
data_ptr	A pointer to callback data or nullptr. The implementation of the function can gain access to this pointer using context::user_data().
step	Step callback. See sqlite3_create_window_function
last	Last callback. See sqlite3_create_window_function
current	Current callback. See sqlite3_create_window_function
inverse	Inverse callback. See sqlite3_create_window_function
destructor	A "destructor" function for `data_ptr`. Can be nullptr.

Since: SQLite 3.25

◆ create_window_function() [2/2]

template<class T >

void create_window_function	(	const char *	name,
		int	arg_count,
		int	flags,
		T	impl_ptr,
		void(*	destructor )(type_identity_t< T > obj) noexcept = nullptr )

Create or redefine SQL aggregate window function

Equivalent to sqlite3_create_window_function

Parameters

name	Name of the SQL function to be created or redefined
arg_count	The number of arguments that the SQL function takes. If this parameter is -1, then the SQL function may take any number of arguments.
flags	Combination of Text encoding flags that specify what encoding this SQL function prefers for its parameters Function flags
impl_ptr	A pointer to C++ object that implements the function or nullptr. The C++ object pointed to it needs to be callable as: impl_ptr->step(context , int, value ); impl_ptr->last(context ); impl_ptr->current(context ); impl_ptr->inverse(context , int, value **); If impl_ptr is nullptr the function is removed.
destructor	A "destructor" function for `impl_ptr`. Can be nullptr.

Since: SQLite 3.25

◆ cacheflush()

void cacheflush ( )

inline

Flush caches to disk mid-transaction.

Equivalent to sqlite3_db_cacheflush

Since: SQLite 3.1

◆ config()

template<int Code, class ... Args>

auto config ( Args &&... args ) -> void

inline

Configure database connection.

Wraps sqlite3_db_config

Template Parameters

Code	One of the SQLITE_DBCONFIG_ options. Needs to be explicitly specified
Args	depend on the `Code` template parameter

The following table lists required argument types for each option. Supplying wrong argument types will result in compile-time error.

Code	Arguments
SQLITE_DBCONFIG_MAINDBNAME	const char *
SQLITE_DBCONFIG_LOOKASIDE	void *, int, int
SQLITE_DBCONFIG_ENABLE_FKEY	int, int *
SQLITE_DBCONFIG_ENABLE_TRIGGER	int, int *
SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER	int, int *
SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION	int, int *
SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE	int, int *
SQLITE_DBCONFIG_ENABLE_QPSG	int, int *
SQLITE_DBCONFIG_TRIGGER_EQP	int, int *
SQLITE_DBCONFIG_RESET_DATABASE	int, int *
SQLITE_DBCONFIG_DEFENSIVE	int, int *
SQLITE_DBCONFIG_WRITABLE_SCHEMA	int, int *
SQLITE_DBCONFIG_LEGACY_ALTER_TABLE	int, int *
SQLITE_DBCONFIG_ENABLE_VIEW	int, int *
SQLITE_DBCONFIG_LEGACY_FILE_FORMAT	int, int *
SQLITE_DBCONFIG_TRUSTED_SCHEMA	int, int *
SQLITE_DBCONFIG_STMT_SCANSTATUS	int, int *
SQLITE_DBCONFIG_REVERSE_SCANORDER	int, int *
SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE	int, int *
SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE	int, int *
SQLITE_DBCONFIG_ENABLE_COMMENTS	int, int *

◆ create_module() [1/2]

void create_module	(	const string_param &	name,
		const sqlite3_module *	mod )

inline

Register a virtual table implementation.

Equivalent to sqlite3_create_module_v2

Parameters

name	name of the module
mod	pointer to sqlite3_module "vtable"

◆ create_module() [2/2]

template<typename T >

void create_module	(	const string_param &	name,
		const sqlite3_module *	mod,
		T *	data,
		void(*	destructor )(T *) = nullptr )

inline

Register a virtual table implementation.

Equivalent to sqlite3_create_module_v2

Parameters

name	name of the module
mod	pointer to sqlite3_module "vtable"
data	data to be passed to virtual table xCreate function.
destructor	function to call when data is no longer needed. Can be omitted

◆ declare_vtab()

void declare_vtab ( const string_param & sdl )

inline

Declare the schema of a virtual table.

Equivalent to sqlite3_declare_vtab

◆ vtab_config()

template<int Code, class ... Args>

auto vtab_config ( Args &&... args ) -> void

inline

Configure virtual table.

Wraps sqlite3_vtab_config

Template Parameters

Code	One of the SQLITE_VTAB_ options. Needs to be explicitly specified
Args	depend on the `Code` template parameter

The following table lists required argument types for each option. Supplying wrong argument types will result in compile-time error.

| Code | Arguments | | -----— |--------—|

◆ vtab_on_conflict()

int vtab_on_conflict ( ) const

inlinenoexcept

Determine the virtual table conflict policy.

Equivalent to sqlite3_vtab_on_conflict

Returns: One of the SQLITE_ROLLBACK, SQLITE_IGNORE, SQLITE_FAIL, SQLITE_ABORT, or SQLITE_REPLACE conflict resolution modes

◆ drop_modules()

void drop_modules ( )

inline

Remove all virtual table modules from database connection.

Equivalent to sqlite3_drop_modules with nullptr second argument

Since: SQLite 3.30

◆ drop_modules_except() [1/3]

void drop_modules_except ( const char *const * keep )

inline

Remove virtual table modules from database connection.

Equivalent to sqlite3_drop_modules

Since: SQLite 3.30

◆ drop_modules_except() [2/3]

template<size_t N>

void drop_modules_except ( const char *const (&) keep[N] )

inline

Remove virtual table modules from database connection.

Equivalent to sqlite3_drop_modules

Since: SQLite 3.30

◆ drop_modules_except() [3/3]

template<class ... Args>

void drop_modules_except ( Args &&... args )

inline

Remove virtual table modules from database connection.

Equivalent to sqlite3_drop_modules

Parameters

args	Any combination of `const char *` and `std::string` arguments that specify names of the modules to keep

Since: SQLite 3.30

◆ extended_result_codes()

void extended_result_codes ( bool onoff )

inline

Enable or disable extended result codes.

Equivalent to sqlite3_extended_result_codes

◆ file_control()

void file_control	(	const string_param &	db_name,
		int	op,
		void *	data )

inline

Low-level control of database file.

Equivalent to sqlite3_file_control

◆ filename()

const char * filename ( const string_param & db_name ) const

inlinenoexcept

Return the filename for the database connection.

Equivalent to sqlite3_db_filename

◆ get_autocommit()

bool get_autocommit ( ) const

inlinenoexcept

Return the auto-commit mode.

Equivalent to sqlite3_get_autocommit

◆ interrupt()

void interrupt ( )

inlinenoexcept

Interrupt a long-running query.

Equivalent to sqlite3_interrupt

◆ is_interrupted()

bool is_interrupted ( )

inlinenoexcept

Returns whether or not an interrupt is currently in effect.

Equivalent to sqlite3_is_interrupted

Since: SQLite 3.41

◆ last_insert_rowid()

int64_t last_insert_rowid ( ) const

inlinenoexcept

Returns last insert rowid.

Equivalent to sqlite3_last_insert_rowid

◆ set_last_insert_rowid()

void set_last_insert_rowid ( int64_t value )

inlinenoexcept

Set the last insert rowid value.

Equivalent to sqlite3_set_last_insert_rowid

Since: SQLite 3.18

◆ limit()

int limit	(	int	id,
		int	new_val )

inlinenoexcept

Set or retrieve run-time limits.

Equivalent to sqlite3_limit

Parameters

id	one of the limit categories
new_val	new value or -1 to query

Returns: prior value of the limit or -1 on bad limit or other issues

◆ enable_load_extension()

void enable_load_extension ( bool val )

inline

Enable or disable extension loading.

Equivalent to sqlite3_enable_load_extension

◆ load_extension()

void load_extension	(	const string_param &	file,
		const string_param &	proc = nullptr )

Load an extension.

Equivalent to sqlite3_load_extension

◆ auto_extension()

void auto_extension ( void(* entry_point )(database *, const char **, const struct sqlite3_api_routines *) )

inline

Automatically load statically linked extension.

Equivalent to sqlite3_auto_extension

Since: SQLite 3.8.7

◆ cancel_auto_extension()

void cancel_auto_extension ( void(* entry_point )(database *, const char **, const struct sqlite3_api_routines *) )

inline

Cancel automatic extension Loading.

Equivalent to sqlite3_cancel_auto_extension

Since: SQLite 3.8.7

◆ reset_auto_extension()

void reset_auto_extension ( )

inlinenoexcept

Reset automatic extension loading.

Equivalent to sqlite3_reset_auto_extension

Since: SQLite 3.8.7

◆ mutex()

class mutex * mutex ( ) const

inlinenoexcept

Retrieve the mutex for the database connection.

Equivalent to sqlite3_db_mutex

◆ next_statement()

const class statement * next_statement ( const class statement * prev ) const

inlinenoexcept

Find the next prepared statement.

Equivalent to sqlite3_next_stmt

◆ overload_function()

void overload_function	(	const string_param &	name,
		int	arg_count )

inlinenoexcept

Overload a function for a virtual table.

Equivalent to sqlite3_overload_function

◆ progress_handler() [1/2]

template<class T >

void progress_handler	(	int	step_count,
		int(*	handler )(type_identity_t< T > data_ptr) noexcept,
		T	data_ptr ) const

inlinenoexcept

Register a callback to be called on query progress.

Equivalent to sqlite3_progress_handler

Parameters

step_count	An approximate number of virtual machine instructions that are evaluated between successive invocations of the callback. If less than one then the progress handler is disabled.
handler	A callback function that matches the type of `data_ptr` argument. Can be nullptr.
data_ptr	A pointer to callback data or nullptr.

◆ progress_handler() [2/2]

template<class T >

void progress_handler	(	int	step_count,
		T	handler_ptr ) const

noexcept

Register a callback to be called on query progress.

Equivalent to sqlite3_progress_handler

Parameters

step_count	An approximate number of virtual machine instructions that are evaluated between successive invocations of the callback. If less than one then the progress handler is disabled.
handler_ptr	A pointer to any C++ callable that can be invoked as (*handler_ptr)(); This invocation must be `noexcept`. This parameter can also be nullptr to reset the handler. The handler object must exist as long as it is set.

◆ readonly()

std::optional< bool > readonly ( const string_param & db_name ) const

noexcept

Determine if a database is read-only.

Equivalent to sqlite3_db_readonly

Parameters

db_name database name

Returns: true if the database named db_name is readonly, false if it is read/write or std::nullopt if db_name is not a name of a database on this connection.

◆ release_memory()

void release_memory ( ) const

inline

Free memory used by the database connection.

Equivalent to sqlite3_db_release_memory

◆ status()

struct status status	(	int	op,
		bool	reset = false ) const

Retrieve database connection status.

Equivalent to sqlite3_db_status

◆ table_column_metadata()

column_metadata table_column_metadata	(	const string_param &	db_name,
		const string_param &	table_name,
		const string_param &	column_name ) const

Extract metadata about a column of a table.

Equivalent to sqlite3_table_column_metadata

◆ total_changes()

int64_t total_changes ( ) const

inlinenoexcept

Returns total number of rows modified.

Equivalent to sqlite3_total_changes

◆ txn_state()

int txn_state ( const string_param & schema ) const

inlinenoexcept

Returns the transaction state of a database.

Equivalent to sqlite3_txn_state

Since: SQLite 3.34

◆ open_blob()

std::unique_ptr< blob > open_blob	(	const string_param &	dbname,
		const string_param &	table,
		const string_param &	column,
		int64_t	rowid,
		bool	writable )

Open a blob.

Equivalent to sqlite3_blob_open

◆ serialize()

std::pair< allocated_bytes, size_t > serialize ( const string_param & schema_name )

Serialize a database.

Equivalent to sqlite3_serialize with flags set 0

Since: SQLite 3.39

◆ serialize_reference()

span< std::byte > serialize_reference ( const string_param & schema_name )

noexcept

Serialize a database.

Equivalent to sqlite3_serialize with flags set SQLITE_SERIALIZE_NOCOPY

Since: SQLite 3.39

◆ deserialize() [1/3]

void deserialize	(	const string_param &	schema_name,
		std::byte *	buf,
		size_t	size,
		size_t	buf_size,
		unsigned	flags = 0 )

inline

Deserialize a database.

Equivalent to sqlite3_deserialize

Since: SQLite 3.39

◆ deserialize() [2/3]

void deserialize	(	const string_param &	schema_name,
		const std::byte *	buf,
		size_t	size,
		size_t	buf_size,
		unsigned	flags = 0 )

inline

Deserialize a database.

A convenience overload for immutable data

Equivalent to sqlite3_deserialize with SQLITE_DESERIALIZE_READONLY flag always added

Since: SQLite 3.39

◆ deserialize() [3/3]

void deserialize	(	const string_param &	schema_name,
		allocated_bytes	buf,
		size_t	size,
		size_t	buf_size,
		unsigned	flags = 0 )

Deserialize a database.

A convenience overload that takes ownership over passed pointer

Equivalent to sqlite3_deserialize with SQLITE_DESERIALIZE_FREEONCLOSE flag always added

Since: SQLite 3.39

◆ get_snapshot()

std::unique_ptr< snapshot > get_snapshot ( const string_param & schema )

Record a database snapshot.

Equivalent to sqlite3_snapshot_get

Requires THINSQLITEPP_ENABLE_EXPIREMENTAL macro defined to 1 as the underlying SQLite feature is experimental.

Since: SQLite 3.10

◆ open_snapshot()

void open_snapshot	(	const string_param &	schema,
		const snapshot &	snap )

inline

Start a read transaction on an historical snapshot.

Equivalent to sqlite3_snapshot_open

Requires THINSQLITEPP_ENABLE_EXPIREMENTAL macro defined to 1 as the underlying SQLite feature is experimental.

Since: SQLite 3.10

◆ recover_snapshot()

void recover_snapshot ( const string_param & db )

inline

Recover snapshots from a wal file.

Equivalent to sqlite3_snapshot_recover

Requires THINSQLITEPP_ENABLE_EXPIREMENTAL macro defined to 1 as the underlying SQLite feature is experimental.

Since: SQLite 3.10

◆ db_name()

const char * db_name ( int idx )

inlinenoexcept

Return schema names.

Equivalent to sqlite3_db_name

Parameters

idx	Schema index. 0 means the main database file and 1 is the "temp" schema. Larger values correspond to various ATTACH-ed databases.

Since: SQLite 3.39

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Class Documentation

◆ thinsqlitepp::database::column_metadata

◆ thinsqlitepp::database::status

Member Function Documentation

◆ open()

◆ busy_timeout()

◆ changes()

◆ exec() [1/2]

◆ exec() [2/2]

◆ busy_handler() [1/2]

◆ busy_handler() [2/2]

◆ collation_needed() [1/2]

◆ collation_needed() [2/2]

◆ commit_hook() [1/2]

◆ commit_hook() [2/2]

◆ rollback_hook() [1/2]

◆ rollback_hook() [2/2]

◆ update_hook() [1/2]

◆ update_hook() [2/2]

◆ preupdate_hook() [1/2]

◆ preupdate_hook() [2/2]

◆ wal_hook() [1/2]

◆ wal_hook() [2/2]

◆ preupdate_old()

◆ preupdate_new()

◆ preupdate_count()

◆ preupdate_depth()

◆ preupdate_blobwrite()

◆ checkpoint()

◆ autocheckpoint()

◆ create_collation() [1/2]

◆ create_collation() [2/2]

◆ create_function() [1/2]

◆ create_function() [2/2]

◆ create_window_function() [1/2]

◆ create_window_function() [2/2]

◆ cacheflush()

◆ config()

◆ create_module() [1/2]

◆ create_module() [2/2]

◆ declare_vtab()

◆ vtab_config()

◆ vtab_on_conflict()

◆ drop_modules()

◆ drop_modules_except() [1/3]

◆ drop_modules_except() [2/3]

◆ drop_modules_except() [3/3]

◆ extended_result_codes()

◆ file_control()

◆ filename()

◆ get_autocommit()

◆ interrupt()

◆ is_interrupted()

◆ last_insert_rowid()

◆ set_last_insert_rowid()

◆ limit()

◆ enable_load_extension()

◆ load_extension()

◆ auto_extension()

◆ cancel_auto_extension()

◆ reset_auto_extension()

◆ mutex()

◆ next_statement()

◆ overload_function()

◆ progress_handler() [1/2]

◆ progress_handler() [2/2]

◆ readonly()

◆ release_memory()

◆ status()

◆ table_column_metadata()

◆ total_changes()

◆ txn_state()

◆ open_blob()

◆ serialize()

◆ serialize_reference()

◆ deserialize() [1/3]