From fe375392804e23d221face98bb6994795248d2a3 Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Fri, 31 Oct 2025 06:41:21 +0100
Subject: [PATCH 01/11] docs: test usage/index.rst

---
 docs/examples/usage/__init__.py     |  0
 docs/examples/usage/test_index_1.py | 22 ++++++++++++++++++++++
 docs/usage/index.rst                | 14 ++++----------
 pyproject.toml                      |  2 +-
 4 files changed, 27 insertions(+), 11 deletions(-)
 create mode 100644 docs/examples/usage/__init__.py
 create mode 100644 docs/examples/usage/test_index_1.py

diff --git a/docs/examples/usage/__init__.py b/docs/examples/usage/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/examples/usage/test_index_1.py b/docs/examples/usage/test_index_1.py
new file mode 100644
index 000000000..c2af81230
--- /dev/null
+++ b/docs/examples/usage/test_index_1.py
@@ -0,0 +1,22 @@
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+
+spec = SQLSpec()
+db = spec.add_config(SqliteConfig())
+with spec.provide_session(db) as session:
+    _ = session.execute("""
+    CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL
+    )
+    """)
+    _ = session.execute("""INSERT INTO users VALUES (1, 'alice')""")
+with spec.provide_session(db) as session:
+   result = session.execute("SELECT * FROM users WHERE id = ?", 1)
+   user = result.one()
+
+
+
+def test_index_1() -> None:
+
+    assert user is not None
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index 3961c70d7..8934ce45e 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -51,17 +51,11 @@ Quick Reference
 
 **Basic Query Execution**
 
-.. code-block:: python
-
-   from sqlspec import SQLSpec
-   from sqlspec.adapters.sqlite import SqliteConfig
-
-   spec = SQLSpec()
-   db = spec.add_config(SqliteConfig())
+.. literalinclude:: /examples/usage/test_index_1.py
+   :language: python
+   :caption: ``basic query execution``
+   :lines: 1-5, 14-16
 
-   with spec.provide_session(db) as session:
-       result = session.execute("SELECT * FROM users WHERE id = ?", 1)
-       user = result.one()
 
 **Using the Query Builder**
 
diff --git a/pyproject.toml b/pyproject.toml
index 231b90798..b0944e6b8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -322,7 +322,7 @@ markers = [
   "pymysql: marks tests using pymysql",
   "psqlpy: marks tests using psqlpy",
 ]
-testpaths = ["tests"]
+testpaths = ["tests", "docs/examples/usage"]
 
 [tool.mypy]
 exclude = ["tmp/", ".tmp/", ".bugs/"]

From fe0e3baf7a2bb7148c62cc511cde833ce4f80166 Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Fri, 31 Oct 2025 06:56:17 +0100
Subject: [PATCH 02/11] index 2

---
 docs/examples/usage/test_index_1.py |  6 ++----
 docs/examples/usage/test_index_2.py | 25 +++++++++++++++++++++++++
 docs/usage/index.rst                | 12 ++++--------
 3 files changed, 31 insertions(+), 12 deletions(-)
 create mode 100644 docs/examples/usage/test_index_2.py

diff --git a/docs/examples/usage/test_index_1.py b/docs/examples/usage/test_index_1.py
index c2af81230..151fc5f55 100644
--- a/docs/examples/usage/test_index_1.py
+++ b/docs/examples/usage/test_index_1.py
@@ -12,11 +12,9 @@
     """)
     _ = session.execute("""INSERT INTO users VALUES (1, 'alice')""")
 with spec.provide_session(db) as session:
-   result = session.execute("SELECT * FROM users WHERE id = ?", 1)
-   user = result.one()
-
+    result = session.execute("SELECT * FROM users WHERE id = ?", 1)
+    user = result.one()
 
 
 def test_index_1() -> None:
-
     assert user is not None
diff --git a/docs/examples/usage/test_index_2.py b/docs/examples/usage/test_index_2.py
new file mode 100644
index 000000000..ab3dc8543
--- /dev/null
+++ b/docs/examples/usage/test_index_2.py
@@ -0,0 +1,25 @@
+from sqlspec import SQLSpec, sql
+from sqlspec.adapters.sqlite import SqliteConfig
+
+spec = SQLSpec()
+db = spec.add_config(SqliteConfig())
+with spec.provide_session(db) as session:
+    _ = session.execute("""
+    CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT,
+        active BOOLEAN NOT NULL DEFAULT 1
+    )
+    """)
+    _ = session.execute("""INSERT INTO users VALUES (1, 'alice', 'alice@example.com', 1),
+                           (2, 'bob', 'bob@example.com', 0),
+                           (3, 'carol', 'carol@examplecom', 1)""")
+
+query = sql.select("id", "name", "email").from_("users").where("active = ?")
+result = session.execute(query, True)  # noqa: FBT003
+users = result.all()
+
+
+def test_index_2() -> None:
+    assert len(users) > 0
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index 8934ce45e..a06762d4c 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -56,16 +56,12 @@ Quick Reference
    :caption: ``basic query execution``
    :lines: 1-5, 14-16
 
-
 **Using the Query Builder**
 
-.. code-block:: python
-
-   from sqlspec import sql
-
-   query = sql.select("id", "name", "email").from_("users").where("active = ?")
-   result = session.execute(query, True)
-   users = result.all()
+.. literalinclude:: /examples/usage/test_index_2.py
+   :language: python
+   :caption: ``using query builder``
+   :lines: 19-21
 
 **Loading from SQL Files**
 

From 0ff8ddce550945c0e75fbbe2bcd6a59caad649a7 Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Fri, 31 Oct 2025 07:37:34 +0100
Subject: [PATCH 03/11] index 3

---
 docs/examples/usage/test_index_3.py | 33 +++++++++++++++++++++++++++++
 docs/usage/index.rst                | 29 +++++++++++++------------
 2 files changed, 48 insertions(+), 14 deletions(-)
 create mode 100644 docs/examples/usage/test_index_3.py

diff --git a/docs/examples/usage/test_index_3.py b/docs/examples/usage/test_index_3.py
new file mode 100644
index 000000000..c6dfcdb2b
--- /dev/null
+++ b/docs/examples/usage/test_index_3.py
@@ -0,0 +1,33 @@
+from pathlib import Path
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+from sqlspec.loader import SQLFileLoader
+
+spec = SQLSpec()
+db = spec.add_config(SqliteConfig())
+with spec.provide_session(db) as session:
+    _   = session.execute("""
+    CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT,
+        active BOOLEAN NOT NULL DEFAULT 1
+    )
+    """)
+    _   = session.execute("""INSERT INTO users VALUES (1, 'alice', 'alice
+@example.com', 1),
+                           (2, 'bob', 'bob@example.com', 0),
+                           (3, 'carol', 'carol@examplecom', 1)""")
+
+
+
+loader = SQLFileLoader()
+loader.load_sql(Path(__file__) / "queries/users.sql")
+
+user_query = loader.get_sql("get_user_by_id", user_id=2)
+result = session.execute(user_query)
+
+
+def test_index_3() -> None:
+    assert result is not None
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index a06762d4c..a09bb25f1 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -51,29 +51,30 @@ Quick Reference
 
 **Basic Query Execution**
 
-.. literalinclude:: /examples/usage/test_index_1.py
-   :language: python
+.. literalinclude:: /docs/examples/usage/test_index_1.py
+   :langage: python
    :caption: ``basic query execution``
-   :lines: 1-5, 14-16
+   :lines: 4-16
+   :dedent: 2
+
 
 **Using the Query Builder**
 
-.. literalinclude:: /examples/usage/test_index_2.py
-   :language: python
-   :caption: ``using query builder``
+.. literalinclude:: /docs/examples/usage/test_index_2.py
+   :langage: python
+   :caption: ``using the qery builder``
    :lines: 19-21
+   :dedent: 2
 
-**Loading from SQL Files**
-
-.. code-block:: python
 
-   from sqlspec.loader import SQLFileLoader
+**Loading from SQL Files**
 
-   loader = SQLFileLoader()
-   loader.load_sql("queries/users.sql")
+.. literalinclude:: /docs/examples/usage/test_index_3.py
+   :langage: python
+   :caption: ``loading fron sql files``
+   :lines: 25-29
+   :dedent: 2
 
-   user_query = loader.get_sql("get_user_by_id", user_id=123)
-   result = session.execute(user_query)
 
 Next Steps
 ----------

From c42b25c69716be44953504d4816db11757037296 Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Fri, 31 Oct 2025 08:03:18 +0100
Subject: [PATCH 04/11] 3

---
 docs/examples/usage/test_index_3.py |  9 +++++----
 docs/usage/index.rst                | 10 +++++-----
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/examples/usage/test_index_3.py b/docs/examples/usage/test_index_3.py
index c6dfcdb2b..ec3468402 100644
--- a/docs/examples/usage/test_index_3.py
+++ b/docs/examples/usage/test_index_3.py
@@ -7,7 +7,7 @@
 spec = SQLSpec()
 db = spec.add_config(SqliteConfig())
 with spec.provide_session(db) as session:
-    _   = session.execute("""
+    _ = session.execute("""
     CREATE TABLE users (
         id INTEGER PRIMARY KEY,
         name TEXT NOT NULL,
@@ -15,15 +15,16 @@
         active BOOLEAN NOT NULL DEFAULT 1
     )
     """)
-    _   = session.execute("""INSERT INTO users VALUES (1, 'alice', 'alice
+    _ = session.execute("""INSERT INTO users VALUES (1, 'alice', 'alice
 @example.com', 1),
                            (2, 'bob', 'bob@example.com', 0),
                            (3, 'carol', 'carol@examplecom', 1)""")
 
 
-
+p = Path(__file__).parent.parent / "queries/users.sql"
+assert p.exists()
 loader = SQLFileLoader()
-loader.load_sql(Path(__file__) / "queries/users.sql")
+loader.load_sql(p)
 
 user_query = loader.get_sql("get_user_by_id", user_id=2)
 result = session.execute(user_query)
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index a09bb25f1..6a3169ead 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -52,7 +52,7 @@ Quick Reference
 **Basic Query Execution**
 
 .. literalinclude:: /docs/examples/usage/test_index_1.py
-   :langage: python
+   :language: python
    :caption: ``basic query execution``
    :lines: 4-16
    :dedent: 2
@@ -61,8 +61,8 @@ Quick Reference
 **Using the Query Builder**
 
 .. literalinclude:: /docs/examples/usage/test_index_2.py
-   :langage: python
-   :caption: ``using the qery builder``
+   :language: python
+   :caption: ``using the query builder``
    :lines: 19-21
    :dedent: 2
 
@@ -70,8 +70,8 @@ Quick Reference
 **Loading from SQL Files**
 
 .. literalinclude:: /docs/examples/usage/test_index_3.py
-   :langage: python
-   :caption: ``loading fron sql files``
+   :language: python
+   :caption: ``loading from sql files``
    :lines: 25-29
    :dedent: 2
 

From 218800e6a11639fd5ea49e6af3c96aad5f591f2d Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Fri, 31 Oct 2025 08:08:42 +0100
Subject: [PATCH 05/11] correct lines

---
 docs/usage/index.rst | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index 6a3169ead..5daaa953e 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -51,30 +51,24 @@ Quick Reference
 
 **Basic Query Execution**
 
-.. literalinclude:: /docs/examples/usage/test_index_1.py
+.. literalinclude:: /examples/usage/test_index_1.py
    :language: python
    :caption: ``basic query execution``
-   :lines: 4-16
-   :dedent: 2
-
+   :lines: 14-16
 
 **Using the Query Builder**
 
-.. literalinclude:: /docs/examples/usage/test_index_2.py
+.. literalinclude:: /examples/usage/test_index_2.py
    :language: python
    :caption: ``using the query builder``
    :lines: 19-21
-   :dedent: 2
-
 
 **Loading from SQL Files**
 
-.. literalinclude:: /docs/examples/usage/test_index_3.py
+.. literalinclude:: /examples/usage/test_index_3.py
    :language: python
    :caption: ``loading from sql files``
-   :lines: 25-29
-   :dedent: 2
-
+   :lines: 24-30
 
 Next Steps
 ----------

From cbbb7ebbecfd75654e11fe70c1bc7a0e8faee445 Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Sun, 2 Nov 2025 14:55:10 +0100
Subject: [PATCH 06/11] Update SQLite example to set defaults for created_at
 and updated_at fields to CURRENT_TIMESTAMP

Signed-off-by: euri10 <benoit.barthelet@gmail.com>
---
 docs/examples/usage/test_index_3.py | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/examples/usage/test_index_3.py b/docs/examples/usage/test_index_3.py
index ec3468402..8f6c3189d 100644
--- a/docs/examples/usage/test_index_3.py
+++ b/docs/examples/usage/test_index_3.py
@@ -10,12 +10,14 @@
     _ = session.execute("""
     CREATE TABLE users (
         id INTEGER PRIMARY KEY,
-        name TEXT NOT NULL,
+        username TEXT NOT NULL,
         email TEXT,
-        active BOOLEAN NOT NULL DEFAULT 1
+        active BOOLEAN NOT NULL DEFAULT 1,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     )
     """)
-    _ = session.execute("""INSERT INTO users VALUES (1, 'alice', 'alice
+    _ = session.execute("""INSERT INTO users(id, username, email, active) VALUES (1, 'alice', 'alice
 @example.com', 1),
                            (2, 'bob', 'bob@example.com', 0),
                            (3, 'carol', 'carol@examplecom', 1)""")
@@ -26,8 +28,8 @@
 loader = SQLFileLoader()
 loader.load_sql(p)
 
-user_query = loader.get_sql("get_user_by_id", user_id=2)
-result = session.execute(user_query)
+user_query = loader.get_sql("get_user_by_id")
+result = session.execute(user_query, user_id=2)
 
 
 def test_index_3() -> None:

From 75c07337a567bfce72fe05a4c7e5a95ddffe7c39 Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Sun, 2 Nov 2025 18:11:53 +0100
Subject: [PATCH 07/11] Update test_index_3.py to include minor formatting
 changes and remove unnecessary assertion.

Signed-off-by: euri10 <benoit.barthelet@gmail.com>
---
 docs/examples/usage/test_index_3.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/examples/usage/test_index_3.py b/docs/examples/usage/test_index_3.py
index 8f6c3189d..e2df35901 100644
--- a/docs/examples/usage/test_index_3.py
+++ b/docs/examples/usage/test_index_3.py
@@ -6,6 +6,7 @@
 
 spec = SQLSpec()
 db = spec.add_config(SqliteConfig())
+
 with spec.provide_session(db) as session:
     _ = session.execute("""
     CREATE TABLE users (
@@ -24,7 +25,6 @@
 
 
 p = Path(__file__).parent.parent / "queries/users.sql"
-assert p.exists()
 loader = SQLFileLoader()
 loader.load_sql(p)
 

From 04806fd67477bee1868ef48de9173e30d31af17e Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Mon, 3 Nov 2025 17:34:21 +0100
Subject: [PATCH 08/11] Updated SQL query example in users.sql and modified
 usage documentation to improve clarity and scope of example inclusion.

Signed-off-by: euri10 <benoit.barthelet@gmail.com>
---
 docs/examples/queries/users.sql | 1 +
 docs/usage/index.rst            | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/examples/queries/users.sql b/docs/examples/queries/users.sql
index ccd4c49db..7d88d60f1 100644
--- a/docs/examples/queries/users.sql
+++ b/docs/examples/queries/users.sql
@@ -4,6 +4,7 @@
 -- name: get_user_by_id
 -- Get a single user by their ID
 SELECT
+
     id,
     username,
     email,
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index 5daaa953e..8f5556e88 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -54,14 +54,14 @@ Quick Reference
 .. literalinclude:: /examples/usage/test_index_1.py
    :language: python
    :caption: ``basic query execution``
-   :lines: 14-16
+   :lines: 1-5,14-17
 
 **Using the Query Builder**
 
 .. literalinclude:: /examples/usage/test_index_2.py
    :language: python
    :caption: ``using the query builder``
-   :lines: 19-21
+   :lines: 1-5,19-22
 
 **Loading from SQL Files**
 

From fbc7a4d025997abe02a9c9e0e5d65749d1634e43 Mon Sep 17 00:00:00 2001
From: euri10 <benoit.barthelet@gmail.com>
Date: Mon, 3 Nov 2025 17:48:05 +0100
Subject: [PATCH 09/11] Reverted formatting change in users.sql to remove an
 extra blank line; adjusted line numbers in index.rst to their original state
 for documentation clarity.

Signed-off-by: euri10 <benoit.barthelet@gmail.com>
---
 docs/examples/queries/users.sql | 1 -
 docs/usage/index.rst            | 6 +++---
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/examples/queries/users.sql b/docs/examples/queries/users.sql
index 7d88d60f1..ccd4c49db 100644
--- a/docs/examples/queries/users.sql
+++ b/docs/examples/queries/users.sql
@@ -4,7 +4,6 @@
 -- name: get_user_by_id
 -- Get a single user by their ID
 SELECT
-
     id,
     username,
     email,
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index 8f5556e88..ac687f13e 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -54,21 +54,21 @@ Quick Reference
 .. literalinclude:: /examples/usage/test_index_1.py
    :language: python
    :caption: ``basic query execution``
-   :lines: 1-5,14-17
+   :lines: 1-5,14-16
 
 **Using the Query Builder**
 
 .. literalinclude:: /examples/usage/test_index_2.py
    :language: python
    :caption: ``using the query builder``
-   :lines: 1-5,19-22
+   :lines: 1-5,19-21
 
 **Loading from SQL Files**
 
 .. literalinclude:: /examples/usage/test_index_3.py
    :language: python
    :caption: ``loading from sql files``
-   :lines: 24-30
+   :lines: 1-8,27-32
 
 Next Steps
 ----------

From ab1c8463f2a6ccc5a474f26fe11667dfeb4866c9 Mon Sep 17 00:00:00 2001
From: Cody Fincher <cody@litestar.dev>
Date: Mon, 10 Nov 2025 01:21:45 +0000
Subject: [PATCH 10/11] refactor: reorganize usage examples and update
 documentation references

---
 docs/examples/usage/test_index_1.py     | 20 -------------
 docs/examples/usage/test_index_2.py     | 25 ----------------
 docs/examples/usage/test_index_3.py     | 36 -----------------------
 docs/examples/usage/usage_index_1.py    | 23 +++++++++++++++
 docs/examples/usage/usage_index_2.py    | 32 ++++++++++++++++++++
 docs/examples/usage/usage_index_3.py    | 39 +++++++++++++++++++++++++
 docs/usage/index.rst                    | 15 ++++++----
 pyproject.toml                          |  2 +-
 specs/guides/docs_examples_alignment.md |  4 +--
 9 files changed, 106 insertions(+), 90 deletions(-)
 delete mode 100644 docs/examples/usage/test_index_1.py
 delete mode 100644 docs/examples/usage/test_index_2.py
 delete mode 100644 docs/examples/usage/test_index_3.py
 create mode 100644 docs/examples/usage/usage_index_1.py
 create mode 100644 docs/examples/usage/usage_index_2.py
 create mode 100644 docs/examples/usage/usage_index_3.py

diff --git a/docs/examples/usage/test_index_1.py b/docs/examples/usage/test_index_1.py
deleted file mode 100644
index 151fc5f55..000000000
--- a/docs/examples/usage/test_index_1.py
+++ /dev/null
@@ -1,20 +0,0 @@
-from sqlspec import SQLSpec
-from sqlspec.adapters.sqlite import SqliteConfig
-
-spec = SQLSpec()
-db = spec.add_config(SqliteConfig())
-with spec.provide_session(db) as session:
-    _ = session.execute("""
-    CREATE TABLE users (
-        id INTEGER PRIMARY KEY,
-        name TEXT NOT NULL
-    )
-    """)
-    _ = session.execute("""INSERT INTO users VALUES (1, 'alice')""")
-with spec.provide_session(db) as session:
-    result = session.execute("SELECT * FROM users WHERE id = ?", 1)
-    user = result.one()
-
-
-def test_index_1() -> None:
-    assert user is not None
diff --git a/docs/examples/usage/test_index_2.py b/docs/examples/usage/test_index_2.py
deleted file mode 100644
index ab3dc8543..000000000
--- a/docs/examples/usage/test_index_2.py
+++ /dev/null
@@ -1,25 +0,0 @@
-from sqlspec import SQLSpec, sql
-from sqlspec.adapters.sqlite import SqliteConfig
-
-spec = SQLSpec()
-db = spec.add_config(SqliteConfig())
-with spec.provide_session(db) as session:
-    _ = session.execute("""
-    CREATE TABLE users (
-        id INTEGER PRIMARY KEY,
-        name TEXT NOT NULL,
-        email TEXT,
-        active BOOLEAN NOT NULL DEFAULT 1
-    )
-    """)
-    _ = session.execute("""INSERT INTO users VALUES (1, 'alice', 'alice@example.com', 1),
-                           (2, 'bob', 'bob@example.com', 0),
-                           (3, 'carol', 'carol@examplecom', 1)""")
-
-query = sql.select("id", "name", "email").from_("users").where("active = ?")
-result = session.execute(query, True)  # noqa: FBT003
-users = result.all()
-
-
-def test_index_2() -> None:
-    assert len(users) > 0
diff --git a/docs/examples/usage/test_index_3.py b/docs/examples/usage/test_index_3.py
deleted file mode 100644
index e2df35901..000000000
--- a/docs/examples/usage/test_index_3.py
+++ /dev/null
@@ -1,36 +0,0 @@
-from pathlib import Path
-
-from sqlspec import SQLSpec
-from sqlspec.adapters.sqlite import SqliteConfig
-from sqlspec.loader import SQLFileLoader
-
-spec = SQLSpec()
-db = spec.add_config(SqliteConfig())
-
-with spec.provide_session(db) as session:
-    _ = session.execute("""
-    CREATE TABLE users (
-        id INTEGER PRIMARY KEY,
-        username TEXT NOT NULL,
-        email TEXT,
-        active BOOLEAN NOT NULL DEFAULT 1,
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-    )
-    """)
-    _ = session.execute("""INSERT INTO users(id, username, email, active) VALUES (1, 'alice', 'alice
-@example.com', 1),
-                           (2, 'bob', 'bob@example.com', 0),
-                           (3, 'carol', 'carol@examplecom', 1)""")
-
-
-p = Path(__file__).parent.parent / "queries/users.sql"
-loader = SQLFileLoader()
-loader.load_sql(p)
-
-user_query = loader.get_sql("get_user_by_id")
-result = session.execute(user_query, user_id=2)
-
-
-def test_index_3() -> None:
-    assert result is not None
diff --git a/docs/examples/usage/usage_index_1.py b/docs/examples/usage/usage_index_1.py
new file mode 100644
index 000000000..5b51fd42b
--- /dev/null
+++ b/docs/examples/usage/usage_index_1.py
@@ -0,0 +1,23 @@
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+
+
+def test_index_1() -> None:
+    db_manager = SQLSpec()
+    db = db_manager.add_config(SqliteConfig())
+
+    with db_manager.provide_session(db) as session:
+        _ = session.execute(
+            """
+            CREATE TABLE users (
+                id INTEGER PRIMARY KEY,
+                name TEXT NOT NULL
+            )
+            """
+        )
+        _ = session.execute("INSERT INTO users VALUES (?, ?)", 1, "alice")
+
+    with db_manager.provide_session(db) as session:
+        user = session.select_one("SELECT * FROM users WHERE id = ?", 1)
+
+    assert user == {"id": 1, "name": "alice"}
diff --git a/docs/examples/usage/usage_index_2.py b/docs/examples/usage/usage_index_2.py
new file mode 100644
index 000000000..31b7e9d8d
--- /dev/null
+++ b/docs/examples/usage/usage_index_2.py
@@ -0,0 +1,32 @@
+from sqlspec import SQLSpec, sql
+from sqlspec.adapters.sqlite import SqliteConfig
+
+
+def test_index_2() -> None:
+    db_manager = SQLSpec()
+    db = db_manager.add_config(SqliteConfig())
+    query = sql.select("id", "name", "email").from_("users").where("active = ?")
+
+    with db_manager.provide_session(db) as session:
+        _ = session.execute(
+            """
+            CREATE TABLE users (
+                id INTEGER PRIMARY KEY,
+                name TEXT NOT NULL,
+                email TEXT,
+                active BOOLEAN NOT NULL DEFAULT 1
+            )
+            """
+        )
+        _ = session.execute(
+            """
+            INSERT INTO users VALUES
+                (1, 'alice', 'alice@example.com', 1),
+                (2, 'bob', 'bob@example.com', 0),
+                (3, 'carol', 'carol@example.com', 1)
+            """
+        )
+        users = session.select(query, True)  # noqa: FBT003
+
+    names = [user["name"] for user in users]
+    assert names == ["alice", "carol"]
diff --git a/docs/examples/usage/usage_index_3.py b/docs/examples/usage/usage_index_3.py
new file mode 100644
index 000000000..51c46e05f
--- /dev/null
+++ b/docs/examples/usage/usage_index_3.py
@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+from sqlspec.loader import SQLFileLoader
+
+QUERIES_PATH = Path(__file__).parent.parent / "queries" / "users.sql"
+
+
+def test_index_3() -> None:
+    db_manager = SQLSpec()
+    db = db_manager.add_config(SqliteConfig())
+    loader = SQLFileLoader()
+    loader.load_sql(QUERIES_PATH)
+    get_user_by_id = loader.get_sql("get_user_by_id")
+
+    with db_manager.provide_session(db) as session:
+        _ = session.execute(
+            """
+            CREATE TABLE users (
+                id INTEGER PRIMARY KEY,
+                username TEXT NOT NULL,
+                email TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+            """
+        )
+        _ = session.execute(
+            """
+            INSERT INTO users(id, username, email)
+            VALUES (1, 'alice', 'alice@example.com'),
+                   (2, 'bob', 'bob@example.com')
+            """
+        )
+        user = session.select_one(get_user_by_id, user_id=2)
+
+    assert user["username"] == "bob"
+    assert user["email"] == "bob@example.com"
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index ac687f13e..2f31063f9 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -51,24 +51,27 @@ Quick Reference
 
 **Basic Query Execution**
 
-.. literalinclude:: /examples/usage/test_index_1.py
+.. literalinclude:: /examples/usage/usage_index_1.py
    :language: python
    :caption: ``basic query execution``
-   :lines: 1-5,14-16
+   :lines: 1-23
+   :dedent: 4
 
 **Using the Query Builder**
 
-.. literalinclude:: /examples/usage/test_index_2.py
+.. literalinclude:: /examples/usage/usage_index_2.py
    :language: python
    :caption: ``using the query builder``
-   :lines: 1-5,19-21
+   :lines: 1-32
+   :dedent: 4
 
 **Loading from SQL Files**
 
-.. literalinclude:: /examples/usage/test_index_3.py
+.. literalinclude:: /examples/usage/usage_index_3.py
    :language: python
    :caption: ``loading from sql files``
-   :lines: 1-8,27-32
+   :lines: 1-39
+   :dedent: 4
 
 Next Steps
 ----------
diff --git a/pyproject.toml b/pyproject.toml
index 8aad476a8..b6e7631f6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -287,7 +287,7 @@ exclude_lines = [
 addopts = ["-q", "-ra"]
 asyncio_default_fixture_loop_scope = "function"
 asyncio_mode = "auto"
-python_files = ["test_*.py", "quickstart_*.py"]
+python_files = ["test_*.py", "quickstart_*.py", "usage_*.py"]
 filterwarnings = [
   "ignore::DeprecationWarning:pkg_resources.*",
   "ignore:pkg_resources is deprecated as an API:DeprecationWarning",
diff --git a/specs/guides/docs_examples_alignment.md b/specs/guides/docs_examples_alignment.md
index 545883356..148ac5c8c 100644
--- a/specs/guides/docs_examples_alignment.md
+++ b/specs/guides/docs_examples_alignment.md
@@ -18,11 +18,11 @@
 ## Testing Command Examples
 
 ```bash
-uv run pytest docs/examples/quickstart -q
+uv run pytest docs/examples/quickstart docs/examples/usage -q
 ```
 
 - `docs/examples/quickstart/conftest.py` sets `SQLSPEC_QUICKSTART_PG_*` from `pytest-databases` so `quickstart_5.py` stays copy/paste friendly in the docs.
-- Async or adapter-specific samples no longer need separate commands—pytest collects `quickstart_4.py` and `quickstart_5.py` automatically via `python_files`.
+- Usage samples are function-based (`usage_*.py`) and collected automatically because `python_files` now includes that pattern.
 - Prefer smaller batches (per topic/section) to keep feedback loops fast.
 
 ## Review Checklist

From 725634c04eb43e47043fa0321890675ee27524ca Mon Sep 17 00:00:00 2001
From: Cody Fincher <cody@litestar.dev>
Date: Mon, 10 Nov 2025 01:25:57 +0000
Subject: [PATCH 11/11] docs: add __all__ declaration to usage examples

---
 docs/examples/usage/usage_index_1.py | 2 ++
 docs/examples/usage/usage_index_2.py | 2 ++
 docs/examples/usage/usage_index_3.py | 3 +++
 3 files changed, 7 insertions(+)

diff --git a/docs/examples/usage/usage_index_1.py b/docs/examples/usage/usage_index_1.py
index 5b51fd42b..a8a48516b 100644
--- a/docs/examples/usage/usage_index_1.py
+++ b/docs/examples/usage/usage_index_1.py
@@ -1,6 +1,8 @@
 from sqlspec import SQLSpec
 from sqlspec.adapters.sqlite import SqliteConfig
 
+__all__ = ("test_index_1",)
+
 
 def test_index_1() -> None:
     db_manager = SQLSpec()
diff --git a/docs/examples/usage/usage_index_2.py b/docs/examples/usage/usage_index_2.py
index 31b7e9d8d..aac40079a 100644
--- a/docs/examples/usage/usage_index_2.py
+++ b/docs/examples/usage/usage_index_2.py
@@ -1,6 +1,8 @@
 from sqlspec import SQLSpec, sql
 from sqlspec.adapters.sqlite import SqliteConfig
 
+__all__ = ("test_index_2",)
+
 
 def test_index_2() -> None:
     db_manager = SQLSpec()
diff --git a/docs/examples/usage/usage_index_3.py b/docs/examples/usage/usage_index_3.py
index 51c46e05f..3e7db4bff 100644
--- a/docs/examples/usage/usage_index_3.py
+++ b/docs/examples/usage/usage_index_3.py
@@ -4,6 +4,9 @@
 from sqlspec.adapters.sqlite import SqliteConfig
 from sqlspec.loader import SQLFileLoader
 
+__all__ = ("test_index_3",)
+
+
 QUERIES_PATH = Path(__file__).parent.parent / "queries" / "users.sql"