Botan::Sqlite3_Database Class Reference

#include <sqlite3.h>

Inheritance diagram for Botan::Sqlite3_Database:

Public Types
enum class	Column_Type : uint8_t { Blob , String , Integer }

Public Member Functions
void	create_table (const Table_Schema &schema) override
virtual size_t	exec (std::string_view sql)
bool	is_threadsafe () const override
virtual bool	is_valid_table_name (std::string_view table) const
std::shared_ptr< Statement >	new_statement (std::string_view sql) const override
Sqlite3_Database &	operator= (const Sqlite3_Database &other)=delete
Sqlite3_Database &	operator= (Sqlite3_Database &&other)=delete
size_t	row_count (std::string_view table_name) override
size_t	rows_changed_by_last_statement () override
virtual std::shared_ptr< Statement >	select (std::string_view columns, std::string_view table, std::string_view where={}, std::optional< size_t > limit=std::nullopt) const
	Sqlite3_Database (const Sqlite3_Database &other)=delete
	Sqlite3_Database (Sqlite3_Database &&other)=delete
BOTAN_FUTURE_EXPLICIT	Sqlite3_Database (std::string_view file, std::optional< int > sqlite_open_flags=std::nullopt)
std::shared_ptr< Statement >	upsert (std::string_view table, std::initializer_list< std::string_view > columns) const override
	~Sqlite3_Database () override

Detailed Description

An SQL_Database implementation backed by SQLite3

Definition at line 24 of file sqlite3.h.

Member Enumeration Documentation

Column_Type

enum class Botan::SQL_Database::Column_Type : uint8_t

stronginherited

The supported column types

Enumerator
Blob
String
Integer

Definition at line 196 of file database.h.

                             : uint8_t {
         Blob,
         String,
         Integer,
      };

Constructor & Destructor Documentation

Sqlite3_Database() [1/3]

Botan::Sqlite3_Database::Sqlite3_Database	(	std::string_view	file,
		std::optional< int >	sqlite_open_flags = std::nullopt )

Create a new SQLite database handle from a file.

Parameters

file	path to the database file be opened and/or created
sqlite_open_flags	flags that will be passed to sqlite3_open_v2() (default: SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX)

Definition at line 18 of file sqlite3.cpp.

                                                                                                 {
   // SQLITE_OPEN_FULLMUTEX ensures that the database object can be used
   // concurrently from multiple threads.
   const int open_flags =
      sqlite_open_flags.value_or(SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX);
   sqlite3* db = nullptr;
   const int rc = ::sqlite3_open_v2(std::string(db_filename).c_str(), &db, open_flags, nullptr);
 
   if(rc != 0) [[unlikely]] {
      const std::string err_msg = (db != nullptr) ? ::sqlite3_errmsg(db) : "unknown error";
      ::sqlite3_close_v2(db);
      throw SQL_DB_Error("sqlite3_open failed - " + err_msg);
   }
 
   m_db = std::shared_ptr<sqlite3>(db, [](sqlite3* p) noexcept { ::sqlite3_close_v2(p); });
}

Referenced by operator=(), operator=(), Sqlite3_Database(), and Sqlite3_Database().

~Sqlite3_Database()

Botan::Sqlite3_Database::~Sqlite3_Database ( )

overridedefault

Sqlite3_Database() [2/3]

Botan::Sqlite3_Database::Sqlite3_Database ( const Sqlite3_Database & other )

delete

References Sqlite3_Database().

Sqlite3_Database() [3/3]

Botan::Sqlite3_Database::Sqlite3_Database ( Sqlite3_Database && other )

delete

References Sqlite3_Database().

Member Function Documentation

create_table()

void Botan::Sqlite3_Database::create_table ( const Table_Schema & schema )

overridevirtual

Create a table

Parameters

schema

the name and columns of the table to create

Implements Botan::SQL_Database.

Definition at line 78 of file sqlite3.cpp.

                                                              {
   BOTAN_ARG_CHECK(!schema.name().empty(), "create_table requires a table name");
   BOTAN_ARG_CHECK(!schema.columns().empty(), "create_table requires at least one column");
 
   std::string sql = "CREATE TABLE ";
   if(schema.is_if_not_exists()) {
      sql += "IF NOT EXISTS ";
   }
   sql += schema.name();
   sql += " (";
   bool first = true;
   for(const auto& col : schema.columns()) {
      if(!first) {
         sql += ", ";
      }
      sql += col.name();
      sql += ' ';
      switch(col.type()) {
         case Column_Type::Blob:
            sql += "BLOB";
            break;
         case Column_Type::String:
            sql += "TEXT";
            break;
         case Column_Type::Integer:
            sql += "INTEGER";
            break;
      }
      if(col.is_primary_key()) {
         sql += " PRIMARY KEY";
      }
      if(col.is_unique()) {
         sql += " UNIQUE";
      }
      if(col.is_not_null()) {
         sql += " NOT NULL";
      }
      first = false;
   }
   sql += ")";
 
   char* errmsg = nullptr;
   const int rc = ::sqlite3_exec(m_db.get(), sql.c_str(), nullptr, nullptr, &errmsg);
 
   if(rc != SQLITE_OK) {
      const std::string err_msg = (errmsg != nullptr) ? errmsg : "unknown error";
      ::sqlite3_free(errmsg);
      throw SQL_DB_Error("sqlite3_exec for create_table failed - " + err_msg, rc);
   }
}

References Botan::SQL_Database::Blob, BOTAN_ARG_CHECK, Botan::SQL_Database::Table_Schema::columns(), Botan::SQL_Database::Integer, Botan::SQL_Database::Table_Schema::is_if_not_exists(), Botan::SQL_Database::Table_Schema::name(), and Botan::SQL_Database::String.

Referenced by operator=().

exec()

virtual size_t Botan::SQL_Database::exec ( std::string_view sql )

inlinevirtualinherited

Prepare and run a statement to completion

Parameters

sql	the SQL text to execute

Returns

the number of result rows which were stepped over

Definition at line 342 of file database.h.

{ return new_statement(sql)->spin(); }

References new_statement().

is_threadsafe()

bool Botan::Sqlite3_Database::is_threadsafe ( ) const

overridevirtual

Query whether this database may be used from multiple threads

Returns

true if SQLite3 was compiled with threading support

Reimplemented from Botan::SQL_Database.

Definition at line 135 of file sqlite3.cpp.

                                           {
   // sqlite3_db_mutex() returns the connection's mutex if the connection is in
   // serialized mode, and nullptr otherwise. This reflects both the compile-time
   // SQLITE_THREADSAFE setting and the per-connection SQLITE_OPEN_(FULL|NO)MUTEX
   // open flags actually used.
   //
   // https://www.sqlite.org/c3ref/db_mutex.html
   return ::sqlite3_db_mutex(m_db.get()) != nullptr;
}

Referenced by operator=().

is_valid_table_name()

bool Botan::SQL_Database::is_valid_table_name ( std::string_view table ) const

virtualinherited

Return true if the given name seems to be valid as the name for a table

Default implementation accepts non-empty [a-zA-Z0-9_]

Parameters

table

the name to check

Returns

true if the name is acceptable as a table name

Definition at line 14 of file database.cpp.

                                                                 {
   if(table.empty()) {
      return false;
   }
 
   constexpr auto valid_table_name_char = CharacterValidityTable::alpha_numeric_plus("_");
   for(const char c : table) {
      if(!valid_table_name_char(c)) {
         return false;
      }
   }
   return true;
}

References Botan::CharacterValidityTable::alpha_numeric_plus().

new_statement()

std::shared_ptr< SQL_Database::Statement > Botan::Sqlite3_Database::new_statement ( std::string_view sql ) const

overridevirtual

Create a new statement for execution

Parameters

sql	the SQL text of the statement

Returns

the prepared statement

Implements Botan::SQL_Database.

Definition at line 37 of file sqlite3.cpp.

                                                                                                  {
   return std::make_shared<Sqlite3_Statement>(m_db, base_sql);
}

Referenced by operator=(), row_count(), and upsert().

operator=() [1/2]

Sqlite3_Database & Botan::Sqlite3_Database::operator= ( const Sqlite3_Database & other )

delete

References Sqlite3_Database().

Referenced by operator=().

operator=() [2/2]

Sqlite3_Database & Botan::Sqlite3_Database::operator= ( Sqlite3_Database && other )

delete

References create_table(), is_threadsafe(), new_statement(), operator=(), row_count(), rows_changed_by_last_statement(), Sqlite3_Database(), and upsert().

row_count()

size_t Botan::Sqlite3_Database::row_count ( std::string_view table_name )

overridevirtual

Count the rows of a table

Parameters

table_name

the table to count

Returns

the number of rows in the table

Implements Botan::SQL_Database.

Definition at line 68 of file sqlite3.cpp.

                                                            {
   auto stmt = new_statement(fmt("select count(*) from {}", table_name));
 
   if(stmt->step()) {
      return stmt->get_size_t(0);
   } else {
      throw SQL_DB_Error(fmt("Querying size of table '{}' failed", table_name));
   }
}

References Botan::fmt(), and new_statement().

Referenced by operator=().

rows_changed_by_last_statement()

size_t Botan::Sqlite3_Database::rows_changed_by_last_statement ( )

overridevirtual

Count the rows modified by the most recently executed statement

Returns

the number of rows inserted, updated or deleted

Implements Botan::SQL_Database.

Definition at line 129 of file sqlite3.cpp.

                                                        {
   const auto result = ::sqlite3_changes64(m_db.get());
   BOTAN_ASSERT_NOMSG(result >= 0);
   return static_cast<size_t>(result);
}

References BOTAN_ASSERT_NOMSG.

Referenced by operator=().

select()

std::shared_ptr< SQL_Database::Statement > Botan::SQL_Database::select ( std::string_view columns, std::string_view table, std::string_view where = {}, std::optional< size_t > limit = std::nullopt ) const

virtualinherited

Prepare a "SELECT <columns> FROM <table> [WHERE <where>] [LIMIT <limit>]" statement. where is the body of the WHERE clause (e.g. "id = ?1 AND name = ?2"); pass an empty string for no WHERE clause. Use ?1, ?2, ... for bound parameters. Virtual so backends can override if helpful.

Parameters

columns	the columns to select
table	the table to select from
where	the body of the WHERE clause, or empty for no WHERE clause
limit	the maximum number of rows, or nullopt for no limit

Returns

the prepared statement

Definition at line 28 of file database.cpp.

                                                                                               {
   std::string sql = "SELECT ";
   sql += columns;
   sql += " FROM ";
   sql += table;
   if(!where.empty()) {
      sql += " WHERE ";
      sql += where;
   }
   if(limit.has_value()) {
      sql += " LIMIT ";
      sql += std::to_string(*limit);
   }
   return new_statement(sql);
}

References new_statement().

Referenced by new_statement().

upsert()

std::shared_ptr< SQL_Database::Statement > Botan::Sqlite3_Database::upsert ( std::string_view table, std::initializer_list< std::string_view > columns ) const

overridevirtual

Prepare an insert-or-replace statement

Parameters

table	the table to upsert into
columns	the columns to write, in placeholder order

Returns

the prepared statement

Implements Botan::SQL_Database.

Definition at line 41 of file sqlite3.cpp.

                                                                            {
   BOTAN_ARG_CHECK(columns.size() > 0, "upsert requires at least one column");
 
   std::string sql = "INSERT OR REPLACE INTO ";
   sql += table;
   sql += " (";
   bool first = true;
   for(const auto& col : columns) {
      if(!first) {
         sql += ", ";
      }
      sql += col;
      first = false;
   }
   sql += ") VALUES (";
   for(size_t i = 1; i <= columns.size(); ++i) {
      if(i > 1) {
         sql += ", ";
      }
      sql += fmt("?{}", i);
   }
   sql += ")";
 
   return new_statement(sql);
}

References BOTAN_ARG_CHECK, Botan::fmt(), and new_statement().

Referenced by operator=().

---

The documentation for this class was generated from the following files:

• src/lib/utils/sqlite3/sqlite3.h
• src/lib/utils/sqlite3/sqlite3.cpp