Classes
struct	boost::sqlite::blob
	An object that owns a binary large object. More...

struct	boost::sqlite::blob_handle
	an object that holds a binary large object. Can be obtained by using blob_handle. More...

struct	boost::sqlite::blob_view
	a view to a binary large object More...

struct	boost::sqlite::connection
	main object for a connection to a database. More...

struct	boost::sqlite::context< Args >
	A context that can be passed into scalar functions. More...

struct	boost::sqlite::vtab::cursor< ColumnType >
	Cursor needs the following member. More...

struct	boost::sqlite::vtab::cursor< void >
	Cursor needs the following member. More...

struct	boost::sqlite::error
	An error containing both a code & optional message. More...

struct	boost::sqlite::error_info
	Additional information about error conditions stored in an sqlite-allocate string. More...

struct	boost::sqlite::field
	A holder for a sqlite field, i.e. something returned from a query. More...

struct	boost::sqlite::vtab::in
	Utility function that can be used in `xFilter` for the `in` operator. More...

struct	boost::sqlite::vtab::index_info

struct	boost::sqlite::memory_tag

struct	boost::sqlite::vtab::modifiable
	Group of functions for modifications. More...

struct	boost::sqlite::param_ref
	A reference to a value to temporary bind for an execute statement. Most values are captures by reference. More...

struct	boost::sqlite::vtab::recursive_transaction
	Support for recursive transactions. More...

struct	boost::sqlite::vtab::renamable
	Make the vtable renamable. More...

struct	boost::sqlite::resultset
	Representation of a result from a database. More...

struct	boost::sqlite::row
	Representation of a row in a database. More...

struct	boost::sqlite::savepoint
	A simple transaction guard implementing RAAI for savepoints. Savepoints can be used recursively. More...

struct	boost::sqlite::statement
	A statement used for a prepared-statement. More...

struct	boost::sqlite::static_resultset< T >
	A typed resultset using a tuple or a described struct. More...

struct	boost::sqlite::transaction
	A simple transaction guard implementing RAAI for transactions. More...

struct	boost::sqlite::vtab::transaction
	Group of functions to support transactions. More...

struct	boost::sqlite::value
	A holder for a sqlite values used for internal APIs. More...

Macros
#define	BOOST_SQLITE_EXTENSION(Name, Conn)
	Declare a sqlite module.

Enumerations
enum class	boost::sqlite::value_type
	The type of a value. More...

enum class	boost::sqlite::zero_blob : sqlite3_uint64
	Helper type to pass a blob full of zeroes without allocating extra memory.

Functions
template<typename Func >
bool	boost::sqlite::commit_hook (connection &conn, Func &&func)
	Install a commit hook.

template<typename T >
auto	boost::sqlite::create_module (connection &conn, cstring_ref name, T &&module, system::error_code &ec, error_info &ei) -> typename std::decay< T >::type &
	Register a vtable.

template<typename Func >
bool	boost::sqlite::preupdate_hook (connection &conn, Func &&func)

template<typename Func >
bool	boost::sqlite::rollback_hook (connection &conn, Func &&func)
	Install a rollback hook.

template<typename Func >
bool	boost::sqlite::update_hook (connection &conn, Func &&func)
	Install an update hook.

void	boost::sqlite::backup (connection &source, connection &target, cstring_ref source_name, cstring_ref target_name, system::error_code &ec, error_info &ei)
	Backup a database.

void	boost::sqlite::backup (connection &source, connection &target, cstring_ref source_name="main", cstring_ref target_name="main")
	Backup a database.

template<typename Func >
void	boost::sqlite::create_collation (connection &conn, cstring_ref name, Func &&func, typename std::enable_if< std::is_convertible< decltype(func(string_view(), string_view())), int >::value, system::error_code >::type &ec)

template<typename Func >
auto	boost::sqlite::create_collation (connection &conn, cstring_ref name, Func &&func)

template<typename Func >
auto	boost::sqlite::create_scalar_function (connection &conn, cstring_ref name, Func &&func, system::error_code &ec)
	create a scalar function

template<typename Func >
auto	boost::sqlite::create_scalar_function (connection &conn, cstring_ref name, Func &&func) -> typename std::enable_if< std::is_same< decltype(detail::create_scalar_function(static_cast< sqlite3 * >(nullptr), name, std::declval< Func >())), int >::value >::type
	create a scalar function

template<typename Func >
void	boost::sqlite::create_aggregate_function (connection &conn, cstring_ref name, Func &&func, system::error_code &ec, error_info &ei)
	create a aggregate function

template<typename Func >
void	boost::sqlite::create_aggregate_function (connection &conn, cstring_ref name, Func &&func)
	create a aggregate function

template<typename Func >
void	boost::sqlite::create_window_function (connection &conn, cstring_ref name, Func &&func, system::error_code &ec)
	create a aggregate window function

template<typename Func >
void	boost::sqlite::create_window_function (connection &conn, cstring_ref name, Func &&func)
	create a aggregate window function

bool	boost::sqlite::is_json (const value &v)
	Check if the value or field is a json.

bool	boost::sqlite::is_json (const field &f)
	Check if the value or field is a json.

json::value	boost::sqlite::as_json (const value &v, json::storage_ptr ptr={})
	Convert the value or field to a json.

json::value	boost::sqlite::as_json (const field &f, json::storage_ptr ptr={})
	Convert the value or field to a json.

Detailed Description

This page contains the documentation of the sqlite high-level API.

Class Documentation

◆ boost::sqlite::memory_tag

struct boost::sqlite::memory_tag

A tag to allow operator new

Definition at line 15 of file memory.hpp.

Macro Definition Documentation

◆ BOOST_SQLITE_EXTENSION

#define BOOST_SQLITE_EXTENSION	(		Name,
			Conn )

Value:

void sqlite_##Name##_impl (boost::sqlite::connection Conn);               \
extern "C" BOOST_SYMBOL_EXPORT                                            \
int sqlite3_##Name##_init(                                                \
    sqlite3 *db,                                                          \
    char **pzErrMsg,                                                      \
    const sqlite3_api_routines *pApi)                                     \
{                                                                         \
  using boost::sqlite::sqlite3_api;                                       \
  SQLITE_EXTENSION_INIT2(pApi);                                           \
                                                                          \
  BOOST_SQLITE_TRY                                                        \
  {                                                                       \
    sqlite_##Name##_impl(boost::sqlite::connection{db, false});           \
    return SQLITE_OK;                                                     \
  }                                                                       \
  BOOST_SQLITE_CATCH_ASSIGN_STR_AND_RETURN(*pzErrMsg);                    \
}                                                                         \
void sqlite_##Name##_impl(boost::sqlite::connection Conn)

Declare a sqlite module.

Parameters

Name	The name of the module
Conn	The parameter name of the connection

This macro can be used to create an sqlite extension.

Note: When defining BOOST_SQLITE_COMPILE_EXTENSION (was is done in extension.hpp) sqlite will use an inline namespace to avoid symbol clashes.

Examples

BOOST_SQLITE_EXTENSION(extension, conn)
{
   create_scalar_function(
       conn, "assert",
       [](boost::sqlite::context<>, boost::span<boost::sqlite::value, 1u> sp)
       {
           if (sp.front().get_int() == 0)
             throw std::logic_error("assertion failed");
       });
}

{.cpp}

Definition at line 47 of file extension.hpp.

Enumeration Type Documentation

◆ value_type

enum class boost::sqlite::value_type

strong

The type of a value.

Function Documentation

◆ backup() [1/2]

void boost::sqlite::backup	(	connection &	source,
		connection &	target,
		cstring_ref	source_name,
		cstring_ref	target_name,
		system::error_code &	ec,
		error_info &	ei )

Backup a database.

This function will create a backup of an existing database. This can be useful to write an in memory database to disk et vice versa.

Parameters

source	The source database to backup
target	The target of the backup
source_name	The source database to read the backup from. Default is 'main'.
target_name	The target database to write the backup to. Default is 'main'.

Error Handling

Exceptions

system_error from overload without ec & ei

or you need to pass

Parameters

ec	The system::error_code to capture any possibly errors
ei	Additional error_info when error occurs.

Example

sqlite::connection conn{":memory:"};
{
   sqlite::connection read{"./read_only_db.db", SQLITE_READONLY};
   backup(read, target);
}

◆ backup() [2/2]

void boost::sqlite::backup	(	connection &	source,
		connection &	target,
		cstring_ref	source_name = "main",
		cstring_ref	target_name = "main" )

Backup a database.

This function will create a backup of an existing database. This can be useful to write an in memory database to disk et vice versa.

Parameters

source	The source database to backup
target	The target of the backup
source_name	The source database to read the backup from. Default is 'main'.
target_name	The target database to write the backup to. Default is 'main'.

Error Handling

Exceptions

system_error from overload without ec & ei

or you need to pass

Parameters

ec	The system::error_code to capture any possibly errors
ei	Additional error_info when error occurs.

Example

sqlite::connection conn{":memory:"};
{
   sqlite::connection read{"./read_only_db.db", SQLITE_READONLY};
   backup(read, target);
}

◆ commit_hook()

template<typename Func >

bool boost::sqlite::commit_hook	(	connection &	conn,
		Func &&	func )

Install a commit hook.

See also: related sqlite documentation

The commit hook gets called before a commit gets performed. If func returns true, the commit goes, otherwise it gets rolled back.

Note: If the function is not a free function pointer, this function will NOT take ownership.; If func is a nullptr the hook gets reset.

Parameters

conn	The database connection to install the hook in
func	The hook function

Returns: true if an hook has been replaced.

Definition at line 276 of file hooks.hpp.

◆ create_aggregate_function() [1/2]

template<typename Func >

void boost::sqlite::create_aggregate_function	(	connection &	conn,
		cstring_ref	name,
		Func &&	func )

create a aggregate function

Parameters

conn	The connection to add the function to.
name	The name of the function
func	The function to be added
ec	The system::error_code

Exceptions

`system::system_error` when the overload without ec is used.

func needs to be an object with two functions:

void step(State &, boost::span<sqlite::value, N> args);

T final(State &);

State can be any type and will get deduced together with N. An aggregrate function will create a new State for a new aggregate and call step for every step. When the aggregation is done final is called and the result is returned to sqlite.

Example

extern sqlite::connection conn;
 
struct aggregate_func
{
    void step(std::size_t & counter, boost::span<sqlite::value, 1u> val)
    {
      counter += val[0].get_text().size();
    }
 
    std::size_t final(std::size_t & counter)
    {
      return counter;
    }
};
 
sqlite::create_function(
  conn, "char_counter",
  aggregate_func{});

Definition at line 299 of file function.hpp.

◆ create_aggregate_function() [2/2]

template<typename Func >

void boost::sqlite::create_aggregate_function	(	connection &	conn,
		cstring_ref	name,
		Func &&	func,
		system::error_code &	ec,
		error_info &	ei )

create a aggregate function

Parameters

conn	The connection to add the function to.
name	The name of the function
func	The function to be added
ec	The system::error_code

Exceptions

`system::system_error` when the overload without ec is used.

func needs to be an object with two functions:

void step(State &, boost::span<sqlite::value, N> args);

T final(State &);

State can be any type and will get deduced together with N. An aggregrate function will create a new State for a new aggregate and call step for every step. When the aggregation is done final is called and the result is returned to sqlite.

Example

extern sqlite::connection conn;
 
struct aggregate_func
{
    void step(std::size_t & counter, boost::span<sqlite::value, 1u> val)
    {
      counter += val[0].get_text().size();
    }
 
    std::size_t final(std::size_t & counter)
    {
      return counter;
    }
};
 
sqlite::create_function(
  conn, "char_counter",
  aggregate_func{});

Definition at line 279 of file function.hpp.

◆ create_collation() [1/2]

template<typename Func >

auto boost::sqlite::create_collation	(	connection &	conn,
		cstring_ref	name,
		Func &&	func )

Define a custom collation function

Parameters

conn	A connection to the database in which to install the collation.
name	The name of the collation.
func	The function

The function must be callable with two string_view and return an int, indicating the comparison results.

Example

// a case insensitive string omparison, e.g. from boost.urls
int ci_compare(string_view s0, string_view s1) noexcept;
 
extern sqlite::connection conn;
 
// Register the collation
sqlite::create_collation(conn, "iequal", &ci_compare);
 
// use the collation to get by name, case insensitively
conn.query("select first_name, last_name from people where first_name = 'Klemens' collate iequal;");
 
// order by names case insensitively
conn.query("select * from people order by last_name collate iequal asc;");

Definition at line 88 of file collation.hpp.

◆ create_collation() [2/2]

template<typename Func >

void boost::sqlite::create_collation	(	connection &	conn,
		cstring_ref	name,
		Func &&	func,
		typename std::enable_if< std::is_convertible< decltype(func(string_view(), string_view())), int >::value, system::error_code >::type &	ec )

Define a custom collation function

Parameters

conn	A connection to the database in which to install the collation.
name	The name of the collation.
func	The function

The function must be callable with two string_view and return an int, indicating the comparison results.

Example

// a case insensitive string omparison, e.g. from boost.urls
int ci_compare(string_view s0, string_view s1) noexcept;
 
extern sqlite::connection conn;
 
// Register the collation
sqlite::create_collation(conn, "iequal", &ci_compare);
 
// use the collation to get by name, case insensitively
conn.query("select first_name, last_name from people where first_name = 'Klemens' collate iequal;");
 
// order by names case insensitively
conn.query("select * from people order by last_name collate iequal asc;");

Definition at line 49 of file collation.hpp.

◆ create_module()

template<typename T >

auto boost::sqlite::create_module	(	connection &	conn,
		cstring_ref	name,
		T &&	module,
		system::error_code &	ec,
		error_info &	ei ) -> typename std::decay<T>::type &

Register a vtable.

See also: Sqlite vtab Reference vtab

Parameters

conn	The connection to install the vtable into
name	The name for the vtable
module	The module to install as a vtable. See vtab_module_prototype for the structure required
ec	The system::error_code used to deliver errors for the exception less overload.
info	The error_info used to deliver errors for the exception less overload.
The	requirements for `module`.

Template Parameters

T	The implementation type of the module. It must inherit

Returns: A reference to the module as stored in the database. It's lifetime is managed by the database.

Definition at line 566 of file vtable.hpp.

◆ create_scalar_function() [1/2]

template<typename Func >

auto boost::sqlite::create_scalar_function	(	connection &	conn,
		cstring_ref	name,
		Func &&	func ) -> typename std::enable_if< std::is_same< decltype( detail::create_scalar_function( static_cast<sqlite3*>(nullptr), name, std::declval<Func>()) ), int>::value>::type

create a scalar function

Parameters

conn	The connection to add the function to.
name	The name of the function
func	The function to be added
ec	The system::error_code

Exceptions

`system::system_error` when the overload without ec is used.

func must take context<Args...> as the first and a span<value, N> as the second value. If N is not dynamic_extent it will be used to deduce the number of arguments for the function.

Example

extern sqlite::connection conn;
 
sqlite::create_function(
  conn, "to_upper",
  [](sqlite::context<> ctx,
     boost::span<sqlite::value, 1u> args) -> std::string
  {
      std::string res;
      auto txt = val[0].get_text();
      res.resize(txt.size());
      std::transform(txt.begin(), txt.end(), res.begin(),
                     [](char c){return std::toupper(c);});
      return value;
  });

Definition at line 209 of file function.hpp.

◆ create_scalar_function() [2/2]

template<typename Func >

auto boost::sqlite::create_scalar_function	(	connection &	conn,
		cstring_ref	name,
		Func &&	func,
		system::error_code &	ec )

create a scalar function

Parameters

conn	The connection to add the function to.
name	The name of the function
func	The function to be added
ec	The system::error_code

Exceptions

`system::system_error` when the overload without ec is used.

func must take context<Args...> as the first and a span<value, N> as the second value. If N is not dynamic_extent it will be used to deduce the number of arguments for the function.

Example

extern sqlite::connection conn;
 
sqlite::create_function(
  conn, "my_sum",,
  [](sqlite::context<std::size_t> ctx,
     boost::span<sqlite::value, 1u> args) -> std::size_t
  {
      auto value = args[0].get_int64();
      auto p = ctx.get_if<0>();
      if (p != nullptr) // increment the counter
          return (*p) += value;
      else // set the initial value
          ctx.set<0>(value);
      return value;
  });

Definition at line 154 of file function.hpp.

◆ create_window_function() [1/2]

template<typename Func >

void boost::sqlite::create_window_function	(	connection &	conn,
		cstring_ref	name,
		Func &&	func )

create a aggregate window function

Parameters

conn	The connection to add the function to.
name	The name of the function
func	The function to be added
ec	The system::error_code

Exceptions

`system::system_error` when the overload without ec is used.

func needs to be an object with three functions:

void step(State &, boost::span<sqlite::value, N> args);
void inverse(State & , boost::span<sqlite::value, N> args);
T final(State &);

State can be any type and will get deduced together with N. An aggregrate function will create a new State for a new aggregate and call step for every step. When an element is removed from the window inverse is called. When the aggregation is done final is called and the result is returned to sqlite.

Example

extern sqlite::connection conn;
 
struct window_func
{
    void step(std::size_t & counter, boost::span<sqlite::value, 1u> val)
    {
      counter += val[0].get_text().size();
    }
 
    void inverse(std::size_t & counter, boost::span<sqlite::value, 1u> val)
    {
      counter -= val[0].get_text().size();
    }
 
    std::size_t final(std::size_t & counter)
    {
      return counter;
    }
};
 
sqlite::create_function(
  conn, "win_char_counter",
  aggregate_func{});

Definition at line 382 of file function.hpp.

◆ create_window_function() [2/2]

template<typename Func >

void boost::sqlite::create_window_function	(	connection &	conn,
		cstring_ref	name,
		Func &&	func,
		system::error_code &	ec )

create a aggregate window function

Parameters

conn	The connection to add the function to.
name	The name of the function
func	The function to be added
ec	The system::error_code

Exceptions

`system::system_error` when the overload without ec is used.

func needs to be an object with three functions:

void step(State &, boost::span<sqlite::value, N> args);
void inverse(State & , boost::span<sqlite::value, N> args);
T final(State &);

State can be any type and will get deduced together with N. An aggregrate function will create a new State for a new aggregate and call step for every step. When an element is removed from the window inverse is called. When the aggregation is done final is called and the result is returned to sqlite.

Example

extern sqlite::connection conn;
 
struct window_func
{
    void step(std::size_t & counter, boost::span<sqlite::value, 1u> val)
    {
      counter += val[0].get_text().size();
    }
 
    void inverse(std::size_t & counter, boost::span<sqlite::value, 1u> val)
    {
      counter -= val[0].get_text().size();
    }
 
    std::size_t final(std::size_t & counter)
    {
      return counter;
    }
};
 
sqlite::create_function(
  conn, "win_char_counter",
  aggregate_func{});

Definition at line 367 of file function.hpp.

◆ preupdate_hook()

template<typename Func >

bool boost::sqlite::preupdate_hook	(	connection &	conn,
		Func &&	func )

A hook for pre-update events.

Note: This is only available if sqlite was compiled with SQLITE_ENABLE_PREUPDATE_HOOK enabled.

See also: related sqlite documentation

The function will get called

Note: If the function is not a free function pointer, this function will NOT take ownership.; If func is a nullptr the hook gets reset.

Parameters

conn	The database connection to install the hook in
func	The hook function

Returns: true if an hook has been replaced.

The signature of the handler is as following (it must noexcept):

void preupdate_hook(sqlite::preupdate_context ctx,
                    int op,
                    const char * db_name,
                    const char * table_name,
                    sqlite3_int64 current_key,
                    sqlite3_int64 new_key);

Definition at line 336 of file hooks.hpp.

◆ rollback_hook()

template<typename Func >

bool boost::sqlite::rollback_hook	(	connection &	conn,
		Func &&	func )

Install a rollback hook.

See also: related sqlite documentation

The rollback hook gets called when a rollback gets performed.

Note: If the function is not a free function pointer, this function will NOT take ownership.; If func is a nullptr the hook gets reset.

Parameters

conn	The database connection to install the hook in
func	The hook function

Returns: true if an hook has been replaced.

Definition at line 298 of file hooks.hpp.

◆ update_hook()

template<typename Func >

bool boost::sqlite::update_hook	(	connection &	conn,
		Func &&	func )

Install an update hook.

See also: related sqlite documentation

The update hook gets called when an update was performed.

Note: If the function is not a free function pointer, this function will NOT take ownership.

The signature of the function is void(int op, core::string_view db, core::string_view table, sqlite3_int64 id). op is either SQLITE_INSERT, SQLITE_DELETE and SQLITE_UPDATE.

Note: If func is a nullptr the hook gets reset.

Parameters

conn	The database connection to install the hook in
func	The hook function

Returns: true if an hook has been replaced.

Definition at line 363 of file hooks.hpp.

Enumerator
integer	An integral value.
floating	A floating piont value.
text	A textual value.
blob	A binary value.
null	No value.

Classes

Macros

Enumerations

Functions

Detailed Description

Class Documentation

◆ boost::sqlite::memory_tag

Macro Definition Documentation

◆ BOOST_SQLITE_EXTENSION

Enumeration Type Documentation

◆ value_type

Function Documentation

◆ backup() [1/2]

◆ backup() [2/2]

◆ commit_hook()

◆ create_aggregate_function() [1/2]

◆ create_aggregate_function() [2/2]

◆ create_collation() [1/2]

◆ create_collation() [2/2]

◆ create_module()

◆ create_scalar_function() [1/2]

◆ create_scalar_function() [2/2]

◆ create_window_function() [1/2]

◆ create_window_function() [2/2]

◆ preupdate_hook()

◆ rollback_hook()

◆ update_hook()