Core API

The low-level SQL API: connections, statements, result cursors and transactions. More...

Classes
struct	Lightweight::SqlConnectionString
struct	Lightweight::SqlConnectionDataSource
struct	Lightweight::SqliteConnectionSettings
	Connection-level settings applied when a connection to a SQLite database is established. More...
class	Lightweight::SqlConnection
	Represents a connection to a SQL database. More...
struct	Lightweight::SqlErrorInfo
	Represents an ODBC SQL error. More...
class	Lightweight::SqlLogger
class	Lightweight::SqlPreparedStatementCache
	A bounded LRU pool of already-prepared ODBC statement handles, owned by a SqlConnection. More...
struct	Lightweight::SqlSchema::Column
struct	Lightweight::SqlSchema::Table
class	Lightweight::SqlScopedLock
class	Lightweight::SqlStatement
	High level API for (prepared) raw SQL statements. More...
class	Lightweight::SqlResultCursor
struct	Lightweight::SqlLatencyHistogram
struct	Lightweight::SqlOperationStatistics
struct	Lightweight::SqlPoolStatistics
struct	Lightweight::SqlStatisticsSnapshot
class	Lightweight::SqlStatistics
class	Lightweight::SqlStatisticsScope
class	Lightweight::SqlTransactionException
class	Lightweight::SqlTransaction

Enumerations
enum class	Lightweight::SqlEncryptionMode : std::uint8_t { SqlEncryptionMode::DriverDefault = 0 , SqlEncryptionMode::Disabled = 1 , SqlEncryptionMode::Enabled = 2 }
	Whether the client/server connection is TLS-encrypted. More...
enum class	Lightweight::SqlStringTruncationMode : uint8_t { SqlStringTruncationMode::Truncate , SqlStringTruncationMode::Error }
	How a connection treats a string or binary value written into a column too small to hold it. More...
enum class	Lightweight::SqliteJournalMode : uint8_t {   SqliteJournalMode::Unchanged , SqliteJournalMode::Delete , SqliteJournalMode::Truncate , SqliteJournalMode::Persist ,   SqliteJournalMode::Memory , SqliteJournalMode::Wal , SqliteJournalMode::Off }
	The SQLite journal mode a connection requests when it is established. More...
enum class	Lightweight::SqlHandleOwnership : uint8_t { SqlHandleOwnership::Owned , SqlHandleOwnership::Borrowed }
	How a connection relates to its ODBC handles. More...
enum class	Lightweight::SqlPreparedStatementCaching : uint8_t { SqlPreparedStatementCaching::Enabled , SqlPreparedStatementCaching::Disabled }
	Whether a single SqlStatement takes part in its connection's prepared-statement cache. More...
enum class	Lightweight::SqlStatisticsOperation : std::uint8_t {   SqlStatisticsOperation::Execute , SqlStatisticsOperation::ExecuteDirect , SqlStatisticsOperation::ExecuteBatch , SqlStatisticsOperation::Prepare ,   SqlStatisticsOperation::Fetch , SqlStatisticsOperation::PoolAcquire , SqlStatisticsOperation::Count }

Functions
LIGHTWEIGHT_API std::string_view	Lightweight::ToStringView (SqlStatisticsOperation operation) noexcept

Detailed Description

The low-level SQL API: connections, statements, result cursors and transactions.

This is the thin layer directly over ODBC. Use it when you want to write SQL yourself and keep full control over binding and fetching. The higher-level Data Mapper and Query Builder layers are built on top of these types and interoperate with them.

Enumeration Type Documentation

SqlEncryptionMode

enum class Lightweight::SqlEncryptionMode : std::uint8_t

strong

Whether the client/server connection is TLS-encrypted.

Maps onto the Microsoft SQL Server ODBC connection attribute SQL_COPT_SS_ENCRYPT, which must be set on the connection handle before connecting. This is the only way to request encryption on the DSN-based connect path (SQLConnect), where there is no connection string for an Encrypt= keyword to live in.

See also

https://learn.microsoft.com/en-us/sql/relational-databases/native-client-odbc-api/sqlsetconnectattr

Enumerator
DriverDefault	Leave the attribute untouched — whatever the driver, DSN, or connection string configures wins. This is the default, so an application that does not opt in behaves exactly as before.
Disabled	Request an unencrypted connection (SQL_EN_OFF).
Enabled	Request an encrypted connection (SQL_EN_ON).

Definition at line 50 of file SqlConnectInfo.hpp.

SqlStringTruncationMode

enum class Lightweight::SqlStringTruncationMode : uint8_t

strong

How a connection treats a string or binary value written into a column too small to hold it.

The mode is applied per connection. On Microsoft SQL Server it is realised by toggling the session's ANSI_WARNINGS setting when the connection is established.

Enumerator
Truncate	The value is silently shortened to the column width (SET ANSI_WARNINGS OFF on SQL Server). This matches the historical behaviour of some legacy data layers that clamp a value to the column width before sending it. Warning On SQL Server this is ANSI_WARNINGS OFF, which also turns an arithmetic overflow into a NULL rather than an error and suppresses the NULL-in-aggregate warning, and makes INSERT/UPDATE fail on tables carrying an indexed view, a filtered index, or an index over a computed column. Prefer Error unless bug-for-bug compatibility with such a legacy layer is required.
Error	The server rejects the write with an error (SET ANSI_WARNINGS ON on SQL Server, which is also the server default). No data is silently lost.

Definition at line 52 of file SqlConnection.hpp.

SqliteJournalMode

enum class Lightweight::SqliteJournalMode : uint8_t

strong

The SQLite journal mode a connection requests when it is established.

Each enumerator other than Unchanged maps onto the matching PRAGMA journal_mode value. See https://sqlite.org/pragma.html#pragma_journal_mode for the semantics of each mode.

Note

SQLite may decline a requested mode without reporting an error, e.g. an in-memory database can only use MEMORY or OFF, so asking it for Wal leaves it in MEMORY.

Enumerator
Unchanged	Leave the journal mode alone: whatever the database file (or the driver) already uses stays in effect. This is the default, so a connection that does not opt in behaves exactly as before.
Delete	PRAGMA journal_mode=DELETE — the rollback journal, deleted at the end of each transaction (SQLite's own default).
Truncate	PRAGMA journal_mode=TRUNCATE — the rollback journal, truncated rather than deleted.
Persist	PRAGMA journal_mode=PERSIST — the rollback journal, kept and its header zeroed.
Memory	PRAGMA journal_mode=MEMORY — the rollback journal, kept in memory.
Wal	PRAGMA journal_mode=WAL — write-ahead logging, in which readers and writers do not block each other. The mode is persistent: it is recorded in the database file and stays in effect for every later connection to it. Requires a file database.
Off	PRAGMA journal_mode=OFF — no rollback journal; a crash or ROLLBACK can corrupt the database.

Definition at line 78 of file SqlConnection.hpp.

SqlHandleOwnership

enum class Lightweight::SqlHandleOwnership : uint8_t

strong

How a connection relates to its ODBC handles.

Enumerator
Owned	The connection allocated its handles, connects them and frees them on Close().
Borrowed	Another component allocated and connected the handle and keeps owning it; the connection only runs statements on it (see SqlConnection::Borrow).

Definition at line 136 of file SqlConnection.hpp.

SqlPreparedStatementCaching

enum class Lightweight::SqlPreparedStatementCaching : uint8_t

strong

Whether a single SqlStatement takes part in its connection's prepared-statement cache.

Statements opt in by default, which only has an effect once the owning connection was given a non-zero cache capacity (see SqlConnection::SetPreparedStatementCacheCapacity). Individual call sites that must not reuse a plan — for instance a statement that straddles a schema change — opt out via SqlStatement::SetPreparedStatementCaching.

Enumerator
Enabled	Reuse a pooled handle when one matches, and hand the handle back to the pool afterwards.
Disabled	Never take a handle from, nor give one to, the connection's cache.

Definition at line 30 of file SqlPreparedStatementCache.hpp.

SqlStatisticsOperation

enum class Lightweight::SqlStatisticsOperation : std::uint8_t

strong

Identifies the operation class a statistics sample belongs to.

The enumerators are contiguous and Count is the array extent used by SqlStatisticsSnapshot — this is the data-driven table key, not a switch-ladder discriminator.

Enumerator
Execute	SQLExecute of a prepared statement.
ExecuteDirect	SQLExecDirect of a one-shot statement.
ExecuteBatch	SQLExecute with a bound parameter array (batch insert/update).
Prepare	SQLPrepare of a statement.
Fetch	Row / block retrieval (SQLFetch, SQLFetchScroll). @note The library does not currently time its fetch paths, so this slot reads back zero unless your own code records into it. Row throughput is reported instead by @ref SqlStatisticsSnapshot::rowsFetched and @ref SqlStatisticsSnapshot::blockFetches.
PoolAcquire	Connection acquisition from a Pool.
Count	Number of enumerators; not an operation itself.

Definition at line 41 of file SqlStatistics.hpp.

Function Documentation

ToStringView()

LIGHTWEIGHT_API std::string_view Lightweight::ToStringView ( SqlStatisticsOperation  operation )

noexcept

Human-readable name of an operation class, for exporters and log output.

Parameters

operation

The operation to name.

Returns

A stable, dot-free identifier (e.g. "Execute"), or "Unknown" for an out-of-range value.