sqlite::command

sqlite::command owns a prepared statement (sqlite3_stmt*) and provides a uniform binding interface (bind() or operator %) for scalar, blob, optional, duration, and enum types. It is the base for higher-level helpers such as sqlite::execute and sqlite::query.

The helper struct null_type and the global sqlite::nil object are used to bind SQL NULLs via the streaming operator.

Use cases

• Designed for reuse—call clear() (or rely on step_once() doing it) to keep the statement cached in the parent connection.
• Parameter indexes are 1-based like the native C API. The streaming operator keeps track of the next index so you can write expressive chaining code.
• Throws database_exception_code on prepare/bind/step errors and annotates messages with the SQL text for easier debugging.

Example usage

Variadic operator() binds whatever you pass and then executes, while still respecting any parameters you bound earlier via operator%.

sqlite::command upsert{
    db,
    "INSERT INTO notes(id, text, edited_at) VALUES(?, ?, ?) "
    "ON CONFLICT(id) DO UPDATE SET text = excluded.text, edited_at = excluded.edited_at"
};

upsert % 42; // bind the id once
upsert(std::string_view{"Ship It"}, std::chrono::system_clock::now());

bool has_row = upsert.step_once(); // true only when a row was returned (rare for INSERT)

if (!has_row) {
    upsert.clear(); // optional: prepares for the next round with new parameters
}

sqlite::command audit{
    db,
    "INSERT INTO audit(entry, created_at) VALUES(?, ?)"
};

// All parameters bound via operator() in one go.
audit("created user", std::chrono::system_clock::now());

sqlite::command insert_named{
    db,
    "INSERT INTO metrics(name, value, created_at) VALUES(:name, @val, $created)"
};

insert_named % sqlite::named(":name", "uptime")
             % sqlite::named("@val", 42)
             % sqlite::named("$created", std::chrono::system_clock::now());

insert_named(sqlite::named(":name", "load"),
             sqlite::named("@val", 0.97),
             sqlite::named("$created", std::chrono::system_clock::now()));

If this pattern is only doing side-effect statements, swap it for sqlite::execute and skip the manual lifetime juggling.

Lifecycle

Binding API

Prefer named placeholders? wrap values with sqlite::named(":placeholder", value) and chain them through operator% or operator(); vsqlite++ resolves the parameter index under the hood.

Streaming operator (%)

Each overload increments an internal 1-based counter so you can write cmd % 1 % "text" % sqlite::nil; to bind arguments sequentially.

Protected helpers