From efcea3a80da7c4479d5fe168435ecc9fd06bdc72 Mon Sep 17 00:00:00 2001
From: John Turner <jturner.usa@gmail.com>
Date: Sun, 14 Sep 2025 00:16:10 -0400
Subject: Squashed 'subprojects/boost-sqlite/' content from commit 3378e35

git-subtree-dir: subprojects/boost-sqlite
git-subtree-split: 3378e353705271e569cf4ba15c467b840a39798c
---
 doc/reference/connection.adoc | 100 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 doc/reference/connection.adoc

(limited to 'doc/reference/connection.adoc')

diff --git a/doc/reference/connection.adoc b/doc/reference/connection.adoc
new file mode 100644
index 0000000..6d62c10
--- /dev/null
+++ b/doc/reference/connection.adoc
@@ -0,0 +1,100 @@
+== `sqlite/connection.hpp`
+[#connection]
+
+The `connection` object is the main object to access a database.
+
+.Definition
+[source,cpp]
+----
+// Utility constant for in-memory databases
+constexpr static cstring_ref in_memory = ":memory:";
+
+struct connection
+{
+    // The handle of the connection
+    using handle_type = sqlite3*;
+    // Returns the handle
+    handle_type handle() const;
+    // Release the owned handle.
+    handle_type release() &&;
+
+    //Default constructor
+    connection() = default;
+    // Construct the connection from a handle.
+    explicit connection(handle_type handle, bool take_ownership = true); // <1>
+    // Move constructor.
+    connection(connection && ) = default;
+    // Move assign operator.
+    connection& operator=(connection && ) = default;
+
+    // Construct a connection and connect it to `filename`. `flags` is set by `SQLITE_OPEN_*` flags.
+    connection(cstring_ref filename,
+               int flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE); // <2>
+    template<typename Path>
+    explicit connection(const Path & pth);
+
+
+    // Connect the database to `filename`.  `flags` is set by `SQLITE_OPEN_*` flags.
+    void connect(cstring_ref filename, int flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE); // <2>
+    void connect(cstring_ref filename, int flags, system::error_code & ec);
+
+    template<typename Path>
+    void connect(const Path & pth, int flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE);
+    template<typename Path>
+    void connect(const Path & pth, int flags, system::error_code & ec);
+
+    // Close the database connection.
+    void close();
+    void close(system::error_code & ec, error_info & ei);
+
+    // Check if the database holds a valid handle.
+    bool valid() const;
+
+    // Perform a query without parameters. Can only execute a single statement.
+    resultset query(
+            core::string_view q,
+            system::error_code & ec,
+            error_info & ei);
+    resultset query(core::string_view q);
+
+    template<typename T, bool Strict = false>
+    static_resultset<T, Strict> query(core::string_view q, system::error_code & ec, error_info & ei);
+    template<typename T, bool Strict = false>
+    static_resultset<T, Strict> query(core::string_view q);
+
+    // Perform a query without parametert, It execute a multiple statement.
+    void execute(cstring_ref q, system::error_code & ec, error_info & ei);
+    void execute(cstring_ref q);
+
+
+    // Preparse a a statement.
+    statement prepare(
+            core::string_view q,
+            system::error_code & ec,
+            error_info & ei);
+    statement prepare(core::string_view q);
+
+
+    // Check if the database has the table
+    bool has_table(
+        cstring_ref table,
+        cstring_ref db_name = "main") const;
+
+    // Check if the database has the table
+    bool has_column(
+        cstring_ref table,
+        cstring_ref column,
+        cstring_ref db_name = "main") const;
+};
+
+----
+<1> The `take_ownership` is usually only false when used from <<extension_modules, extension modules>>.
+<2> See https://www.sqlite.org/c3ref/c_open_autoproxy.html[the sqlite documentation for the available flags].
+
+.Example
+[source,cpp]
+----
+sqlite::connection conn;
+conn.connect("./my-database.db");
+conn.prepare("insert into log (text) values ($1)").execute(std::make_tuple("booting up"));
+----
\ No newline at end of file
-- 
cgit v1.2.3