Added example demonstrating migration and compile-time checking with …

…SQLite extensions

Cargo.toml

@@ -21,6 +21,7 @@ members = [
     "examples/postgres/mockable-todos",
     "examples/postgres/transaction",
     "examples/sqlite/todos",
+    "examples/sqlite/extension",
 ]
 
 [workspace.package]

examples/sqlite/extension/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "sqlx-example-sqlite-extension"
+version = "0.1.0"
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+authors.workspace = true
+
+[dependencies]
+sqlx = { path = "../../../", features = [ "sqlite", "runtime-tokio", "tls-native-tls" ] }
+tokio = { version = "1.20.0", features = ["rt", "macros"]}
+anyhow = "1.0"
+
+[lints]
+workspace = true

examples/sqlite/extension/download-extension.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# This grabs a pre-compiled version of the extension used in this
+# example, and stores it in a temporary directory. That's a bit
+# unusual. Normally, any extensions you need will be installed into a
+# directory on the library search path, either by using the system
+# package manager or by compiling and installing it yourself.
+
+mkdir /tmp/sqlite3-lib && wget -O /tmp/sqlite3-lib/ipaddr.so https://github.com/nalgeon/sqlean/releases/download/0.15.2/ipaddr.so

examples/sqlite/extension/migrations/20250203094951_addresses.sql

@@ -0,0 +1,25 @@
+create table addresses (address text, family integer);
+
+-- The `ipfamily` function is provided by the
+-- [ipaddr](https://github.com/nalgeon/sqlean/blob/main/docs/ipaddr.md)
+-- sqlite extension, and so this migration can not run if that
+-- extension is not loaded.
+insert into addresses (address, family) values
+  ('fd04:3d29:9f41::1', ipfamily('fd04:3d29:9f41::1')),
+  ('10.0.0.1', ipfamily('10.0.0.1')),
+  ('10.0.0.2', ipfamily('10.0.0.2')),
+  ('fd04:3d29:9f41::2', ipfamily('fd04:3d29:9f41::2')),
+  ('fd04:3d29:9f41::3', ipfamily('fd04:3d29:9f41::3')),
+  ('10.0.0.3', ipfamily('10.0.0.3')),
+  ('fd04:3d29:9f41::4', ipfamily('fd04:3d29:9f41::4')),
+  ('fd04:3d29:9f41::5', ipfamily('fd04:3d29:9f41::5')),
+  ('fd04:3d29:9f41::6', ipfamily('fd04:3d29:9f41::6')),
+  ('10.0.0.4', ipfamily('10.0.0.4')),
+  ('10.0.0.5', ipfamily('10.0.0.5')),
+  ('10.0.0.6', ipfamily('10.0.0.6')),
+  ('10.0.0.7', ipfamily('10.0.0.7')),
+  ('fd04:3d29:9f41::7', ipfamily('fd04:3d29:9f41::7')),
+  ('fd04:3d29:9f41::8', ipfamily('fd04:3d29:9f41::8')),
+  ('10.0.0.8', ipfamily('10.0.0.8')),
+  ('fd04:3d29:9f41::9', ipfamily('fd04:3d29:9f41::9')),
+  ('10.0.0.9', ipfamily('10.0.0.9'));

examples/sqlite/extension/sqlx.toml

@@ -0,0 +1,12 @@
+[common.drivers.sqlite]
+# Including the full path to the extension is somewhat unusual,
+# because normally an extension will be installed in a standard
+# directory which is part of the library search path. If that were the
+# case here, the load-extensions value could just be `["ipaddr"]`
+#
+# When the extension file is installed in a non-standard location, as
+# in this example, there are two options:
+# * Provide the full path the the extension, as seen below.
+# * Add the non-standard location to the library search path, which on
+#   Linux means adding it to the LD_LIBRARY_PATH environment variable.
+load-extensions = ["/tmp/sqlite3-lib/ipaddr"]

examples/sqlite/extension/src/main.rs

@@ -0,0 +1,33 @@
+use std::str::FromStr;
+
+use sqlx::{query, sqlite::{SqlitePool, SqliteConnectOptions}};
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> anyhow::Result<()> {
+    let opts = SqliteConnectOptions::from_str(&std::env::var("DATABASE_URL")?)?
+        // The sqlx.toml file controls loading extensions for the CLI
+        // and for the query checking macros, *not* for the
+        // application while it's running. Thus, if we want the
+        // extension to be available during program execution, we need
+        // to load it.
+        //
+        // Note that while in this case the extension path is the same
+        // when checking the program (sqlx.toml) and when running it
+        // (here), this is not required. The runtime environment can
+        // be entirely different from the development one.
+        //
+        // The extension can be described with a full path, as seen
+        // here, but in many cases that will not be necessary. As long
+        // as the extension is installed in a directory on the library
+        // search path, it is sufficient to just provide the extension
+        // name, like "ipaddr"
+        .extension("/tmp/sqlite3-lib/ipaddr");
+
+    let db = SqlitePool::connect_with(opts).await?;
+
+    query!("insert into addresses (address, family) values (?1, ipfamily(?1))", "10.0.0.10").execute(&db).await?;
+
+    println!("Query which requires the extension was successfully executed.");
+
+    Ok(())
+}

examples/x.py

@@ -85,3 +85,4 @@ def project(name, database=None, driver=None):
 project("mysql/todos", driver="mysql_8", database="todos")
 project("postgres/todos", driver="postgres_12", database="todos")
 project("sqlite/todos", driver="sqlite", database="todos.db")
+project("sqlite/extension", driver="sqlite", database="extension.db")