audacity::sqlite::Connection Class Reference

A class representing a connection to a SQLite database. More...

#include <Connection.h>

Collaboration diagram for audacity::sqlite::Connection:

Public Member Functions
	Connection ()=default
	Connection (const Connection &)=delete
	Connection (Connection &&) noexcept
Connection &	operator= (const Connection &)=delete
Connection &	operator= (Connection &&) noexcept
	~Connection ()
bool	IsOpen () const noexcept
	Returns true if the connection is open. More...
bool	CheckTableExists (std::string_view tableName) const
	Returns true if the table exists in the database. More...
Error	Execute (std::string_view sql) noexcept
	Executes the given SQL statement and returns the result. More...
Transaction	BeginTransaction (std::string name)
	Starts a new transaction. More...
Result< Statement >	CreateStatement (std::string_view sql) const
	Prepares the given SQL statement for execution. More...
template<typename ScalarFunctionType >
ScalarFunction	CreateScalarFunction (std::string name, ScalarFunctionType function)
	Registers a scalar function with the given name. More...
template<typename StepFunctionType , typename FinalFunctionType >
AggregateFunction	CreateAggregateFunction (std::string name, StepFunctionType stepFunction, FinalFunctionType finalFunction)
	Registers an aggregate function with the given name. More...
Result< Blob >	OpenBlob (const std::string &tableName, const std::string &columnName, int64_t rowId, bool readOnly, const std::string &databaseName="main") const
	Opens a BLOB for reading or writing. More...
	operator sqlite3 * () const noexcept
	Returns the underlying sqlite3* object. More...
	operator bool () const noexcept
	Returns true if the connection is open. More...
Error	Close (bool force) noexcept
	Closes the connection. More...
std::string_view	GetPath (const char *dbName={}) const noexcept
	Returns the path to the database. More...

Static Public Member Functions
static Result< Connection >	Open (std::string_view path, OpenMode mode=OpenMode::ReadWriteCreate, ThreadMode threadMode=ThreadMode::Serialized)
	Opens a connection to a database. More...
static Result< Connection >	Wrap (sqlite3 *connection)
static Result< Connection >	Reopen (const Connection &connection, OpenMode mode=OpenMode::ReadWriteCreate, ThreadMode threadMode=ThreadMode::Serialized)
static Result< Connection >	Reopen (sqlite3 *connection, OpenMode mode=OpenMode::ReadWriteCreate, ThreadMode threadMode=ThreadMode::Serialized)

Private Member Functions
	Connection (sqlite3 *connection, bool owned) noexcept

Static Private Member Functions
static Error	TransactionHandler (Connection &connection, Transaction::TransactionOperation operation, Transaction &name)

Private Attributes
sqlite3 *	mConnection {}
std::vector< Transaction * >	mPendingTransactions {}
bool	mInDestructor {}
bool	mIsOwned {}

Detailed Description

A class representing a connection to a SQLite database.

Definition at line 47 of file Connection.h.

Constructor & Destructor Documentation

Connection() [1/4]

audacity::sqlite::Connection::Connection ( )

default

Referenced by Open(), and Wrap().

Here is the caller graph for this function:

Connection() [2/4]

audacity::sqlite::Connection::Connection ( const Connection &  )

delete

Connection() [3/4]

audacity::sqlite::Connection::Connection ( Connection &&  rhs )

noexcept

Definition at line 114 of file Connection.cpp.

{
   *this = std::move(rhs);
}

~Connection()

audacity::sqlite::Connection::~Connection

(

)

Definition at line 129 of file Connection.cpp.

{
   mInDestructor = true;
   auto error = Close(true);
   assert(!error.IsError());
}

References Close(), and mInDestructor.

Here is the call graph for this function:

Connection() [4/4]

audacity::sqlite::Connection::Connection ( sqlite3 *  connection, bool  owned  )

privatenoexcept

Definition at line 108 of file Connection.cpp.

    : mConnection { connection }
    , mIsOwned { owned }
{
}

Member Function Documentation

BeginTransaction()

Transaction audacity::sqlite::Connection::BeginTransaction

(

std::string

name

)

Starts a new transaction.

Definition at line 200 of file Connection.cpp.

{
   return Transaction(*this, TransactionHandler, std::move(name));
}

References name, and TransactionHandler().

Here is the call graph for this function:

CheckTableExists()

bool audacity::sqlite::Connection::CheckTableExists

(

std::string_view

tableName

)

const

Returns true if the table exists in the database.

Definition at line 141 of file Connection.cpp.

{
   auto stmt = CreateStatement(
      "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?)");
 
   if (!stmt)
      return false;
 
   auto result = stmt->Prepare(tableName).Run();
 
   if (!result.HasRows())
      return false;
 
   for (auto row : result)
      return row.GetOr(0, false);
 
   return false;
}

References CreateStatement().

Here is the call graph for this function:

Close()

Error audacity::sqlite::Connection::Close ( bool  force )

noexcept

Closes the connection.

Definition at line 298 of file Connection.cpp.

{
   // If there is a transaction in progress,
   // rollback it.
   std::vector<Transaction*> pendingTransactions;
 
   for (auto* transaction : pendingTransactions)
      if (auto err = transaction->Abort(); !force && err.IsError())
         return err;
 
   if (mConnection != nullptr && mIsOwned)
      if(auto err = Error(sqlite3_close(mConnection)); err.IsError())
         return err;
 
   mConnection = nullptr;
 
   return {};
}

References audacity::sqlite::Error::IsError().

Referenced by ~Connection().

Here is the call graph for this function:

Here is the caller graph for this function:

CreateAggregateFunction()

template<typename StepFunctionType , typename FinalFunctionType >

AggregateFunction audacity::sqlite::Connection::CreateAggregateFunction ( std::string  name, StepFunctionType  stepFunction, FinalFunctionType  finalFunction  )

inline

Registers an aggregate function with the given name.

Definition at line 107 of file Connection.h.

   {
      return AggregateFunction { mConnection, std::move(name),
                                 std::move(stepFunction),
                                 std::move(finalFunction) };
   }

References name.

CreateScalarFunction()

template<typename ScalarFunctionType >

ScalarFunction audacity::sqlite::Connection::CreateScalarFunction ( std::string  name, ScalarFunctionType  function  )

inline

Registers a scalar function with the given name.

Definition at line 99 of file Connection.h.

   {
      return ScalarFunction { mConnection, std::move(name),
                              std::move(function) };
   }

References name.

CreateStatement()

Result< Statement > audacity::sqlite::Connection::CreateStatement

(

std::string_view

sql

)

const

Prepares the given SQL statement for execution.

Definition at line 253 of file Connection.cpp.

{
   if (mInDestructor || mConnection == nullptr)
      return Error(SQLITE_MISUSE);
 
   sqlite3_stmt* statement = nullptr;
 
   auto error = Error(sqlite3_prepare_v2(
      mConnection, sql.data(), sql.size(), &statement, nullptr));
 
   if (error.IsError())
      return error;
 
   return Result<Statement>(Statement(statement));
}

References mConnection, and mInDestructor.

Referenced by audacity::cloud::audiocom::sync::RemoteProjectSnapshot::AttachOriginalDB(), CheckTableExists(), audacity::cloud::audiocom::sync::CloudProjectsDatabase::DeleteProject(), audacity::cloud::audiocom::sync::anonymous_namespace{RemoteProjectSnapshot.cpp}::ListAttachedDatabases(), audacity::cloud::audiocom::sync::RemoteProjectSnapshot::RemoteProjectSnapshot(), audacity::cloud::audiocom::sync::RemoteProjectSnapshot::SetupBlocksCopy(), and audacity::cloud::audiocom::sync::RemoteProjectSnapshot::~RemoteProjectSnapshot().

Here is the caller graph for this function:

Execute()

Error audacity::sqlite::Connection::Execute ( std::string_view  sql )

noexcept

Executes the given SQL statement and returns the result.

Definition at line 160 of file Connection.cpp.

{
   if (mInDestructor || mConnection == nullptr)
      return Error(SQLITE_MISUSE);
 
   auto tx = BeginTransaction("Connection_Execute");
 
   auto first = sql.data();
   auto last = first + sql.size();
 
   while (first != last)
   {
      const char* next = nullptr;
      sqlite3_stmt* statement = nullptr;
 
      int result = sqlite3_prepare_v2 (
         mConnection, first, last - first, &statement, &next);
 
      if (result != SQLITE_OK)
         return Error(result);
 
      first = next;
 
      if (statement == nullptr)
         continue;
 
      auto finalizer = finally([statement] { sqlite3_finalize(statement); });
 
      result = sqlite3_step(statement);
 
      if (result != SQLITE_OK && result != SQLITE_DONE && result != SQLITE_ROW)
         return Error(result);
 
      while (result == SQLITE_ROW)
         result = sqlite3_step(statement);
   }
 
   return tx.Commit();
}

GetPath()

std::string_view audacity::sqlite::Connection::GetPath ( const char *  dbName = {} ) const

noexcept

Returns the path to the database.

Definition at line 317 of file Connection.cpp.

{
   auto path = sqlite3_db_filename(mConnection, dbName);
 
   if (path == nullptr)
      return {};
 
   return path;
}

Referenced by Reopen().

Here is the caller graph for this function:

IsOpen()

bool audacity::sqlite::Connection::IsOpen ( ) const

noexcept

Returns true if the connection is open.

Definition at line 136 of file Connection.cpp.

{
   return mConnection != nullptr;
}

References mConnection.

Referenced by Reopen().

Here is the caller graph for this function:

Open()

Result< Connection > audacity::sqlite::Connection::Open ( std::string_view  path, OpenMode  mode = OpenMode::ReadWriteCreate, ThreadMode  threadMode = ThreadMode::Serialized  )

static

Opens a connection to a database.

Definition at line 21 of file Connection.cpp.

{
   auto error = Initialize();
 
   if (error.IsError())
      return error;
 
   int flags = 0;
 
   switch (mode)
   {
   case OpenMode::ReadWrite:
      flags = SQLITE_OPEN_READWRITE;
      break;
   case OpenMode::ReadOnly:
      flags = SQLITE_OPEN_READONLY;
      break;
   case OpenMode::ReadWriteCreate:
      flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE;
      break;
   case OpenMode::Memory:
      flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_MEMORY;
      break;
   }
 
   switch (threadMode)
   {
   case ThreadMode::MultiThread:
      flags |= SQLITE_OPEN_NOMUTEX;
      break;
   case ThreadMode::Serialized:
      flags |= SQLITE_OPEN_FULLMUTEX;
      break;
   }
 
   sqlite3* connection = nullptr;
 
   // If the path is not null-terminated, copy it to a temporary string.
   std::string temp;
   if (*(path.data() + path.size()) != '\0')
   {
      temp = std::string(path);
      path = temp;
   }
 
   error = Error(sqlite3_open_v2(path.data(), &connection, flags, nullptr));
 
   if (error.IsError())
      return error;
 
   return Connection(connection, true);
}

References Connection(), audacity::sqlite::Initialize(), audacity::sqlite::Memory, audacity::sqlite::MultiThread, audacity::sqlite::ReadOnly, audacity::sqlite::ReadWrite, audacity::sqlite::ReadWriteCreate, and audacity::sqlite::Serialized.

Referenced by audacity::sqlite::SafeConnection::Open(), and Reopen().

Here is the call graph for this function:

Here is the caller graph for this function:

OpenBlob()

Result< Blob > audacity::sqlite::Connection::OpenBlob	(	const std::string &	tableName,
		const std::string &	columnName,
		int64_t	rowId,
		bool	readOnly,
		const std::string &	databaseName = "main"
	)		const

Opens a BLOB for reading or writing.

Definition at line 269 of file Connection.cpp.

{
   if (mInDestructor || mConnection == nullptr)
      return Error(SQLITE_MISUSE);
 
   sqlite3_blob* blob = nullptr;
 
   auto error = Error(sqlite3_blob_open(
      mConnection, databaseName.c_str(), tableName.c_str(), columnName.c_str(),
      rowId, readOnly ? 0 : 1, &blob));
 
   if (error.IsError())
      return error;
 
   return Blob { blob };
}

References mConnection, and mInDestructor.

operator bool()

audacity::sqlite::Connection::operator bool ( ) const

explicitnoexcept

Returns true if the connection is open.

Definition at line 293 of file Connection.cpp.

{
   return IsOpen();
}

operator sqlite3 *()

audacity::sqlite::Connection::operator sqlite3 * ( ) const

explicitnoexcept

Returns the underlying sqlite3* object.

Definition at line 288 of file Connection.cpp.

{
   return mConnection;
}

operator=() [1/2]

Connection & audacity::sqlite::Connection::operator= ( Connection &&  rhs )

noexcept

Definition at line 119 of file Connection.cpp.

{
   std::swap(mConnection, rhs.mConnection);
   std::swap(mIsOwned, rhs.mIsOwned);
   std::swap(mInDestructor, rhs.mInDestructor);
   std::swap(mPendingTransactions, rhs.mPendingTransactions);
 
   return *this;
}

References anonymous_namespace{NoteTrack.cpp}::swap().

Here is the call graph for this function:

operator=() [2/2]

Connection & audacity::sqlite::Connection::operator= ( const Connection &  )

delete

Reopen() [1/2]

Result< Connection > audacity::sqlite::Connection::Reopen ( const Connection &  connection, OpenMode  mode = OpenMode::ReadWriteCreate, ThreadMode  threadMode = ThreadMode::Serialized  )

static

Opens a new connection to the same database as the existing connection but with different parameters

Definition at line 82 of file Connection.cpp.

{
   if (!connection.IsOpen())
      return Error(SQLITE_MISUSE);
 
   auto path = connection.GetPath();
 
   // For memory and temporary databases, the path is empty.
   if (path.empty())
      return Error(SQLITE_MISUSE);
 
   return Open(path, mode, threadMode);
}

References GetPath(), IsOpen(), and Open().

Referenced by audacity::sqlite::SafeConnection::Reopen(), and Reopen().

Here is the call graph for this function:

Here is the caller graph for this function:

Reopen() [2/2]

Result< Connection > audacity::sqlite::Connection::Reopen ( sqlite3 *  connection, OpenMode  mode = OpenMode::ReadWriteCreate, ThreadMode  threadMode = ThreadMode::Serialized  )

static

Opens a new connection to the same database as the existing connection but with different parameters

Definition at line 98 of file Connection.cpp.

{
   auto result = Wrap(connection);
 
   if (!result)
      return result;
 
   return Reopen(*result, mode, threadMode);
}

References Reopen(), and Wrap().

Here is the call graph for this function:

TransactionHandler()

Error audacity::sqlite::Connection::TransactionHandler ( Connection &  connection, Transaction::TransactionOperation  operation, Transaction &  name  )

staticprivate

Definition at line 205 of file Connection.cpp.

{
   std::string sql;
 
   const auto& name = transaction.mName;
 
   switch (operation)
   {
   case Transaction::TransactionOperation::BeginOp:
      sql = std::string("SAVEPOINT ") + name;
      break;
   case Transaction::TransactionOperation::CommitOp:
      sql = std::string("RELEASE SAVEPOINT ") + name;
      break;
   case Transaction::TransactionOperation::RollbackOp:
      sql = std::string("ROLLBACK TO SAVEPOINT ") + name +
            std::string("; RELEASE SAVEPOINT ") + name;
      break;
   }
 
   auto error = Error(sqlite3_exec(
      connection.mConnection, sql.c_str(), nullptr, nullptr, nullptr));
 
   if (operation != Transaction::TransactionOperation::BeginOp)
   {
      transaction.mCommitted = true;
 
      connection.mPendingTransactions.erase(
         std::remove_if(
            connection.mPendingTransactions.begin(),
            connection.mPendingTransactions.end(),
            [tx = &transaction](auto lhs) { return lhs == tx; }),
         connection.mPendingTransactions.end());
   }
 
   if (error.IsError())
      return error;
 
   if (operation == Transaction::TransactionOperation::BeginOp)
   {
      connection.mPendingTransactions.push_back(&transaction);
   }
 
   return {};
}

References audacity::sqlite::Transaction::BeginOp, audacity::sqlite::Transaction::CommitOp, audacity::sqlite::Transaction::mCommitted, mConnection, audacity::sqlite::Transaction::mName, mPendingTransactions, name, and audacity::sqlite::Transaction::RollbackOp.

Referenced by BeginTransaction().

Here is the caller graph for this function:

Wrap()

Result< Connection > audacity::sqlite::Connection::Wrap ( sqlite3 *  connection )

static

Wraps an existing connection. The connection will not be closed when the object is destroyed.

Definition at line 74 of file Connection.cpp.

{
   if (connection == nullptr)
      return Error(SQLITE_MISUSE);
 
   return Connection(connection, false);
}

References Connection().

Referenced by Reopen().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

mConnection

sqlite3* audacity::sqlite::Connection::mConnection {}

private

Definition at line 141 of file Connection.h.

Referenced by CreateStatement(), IsOpen(), OpenBlob(), audacity::sqlite::SafeConnection::Lock::operator*(), audacity::sqlite::SafeConnection::Lock::operator->(), and TransactionHandler().

mInDestructor

bool audacity::sqlite::Connection::mInDestructor {}

private

Definition at line 145 of file Connection.h.

Referenced by CreateStatement(), OpenBlob(), and ~Connection().

mIsOwned

bool audacity::sqlite::Connection::mIsOwned {}

private

Definition at line 146 of file Connection.h.

mPendingTransactions

std::vector<Transaction*> audacity::sqlite::Connection::mPendingTransactions {}

private

Definition at line 143 of file Connection.h.

Referenced by TransactionHandler().

---

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

• Connection.h
• Connection.cpp