New version of docs

Author: tarsil

.gitignore

@@ -14,3 +14,7 @@ testsuite.sqlite3
 test_testsuite.sqlite3
 /site
 /dist
+/docs/generated
+/docs/.generated.tmp
+/.cache
+.DS_Store

README.md

@@ -56,12 +56,12 @@ Databasez is suitable for integrating against any async Web framework, such as [
 [Starlette][starlette], [Sanic][sanic], [Responder][responder], [Quart][quart], [aiohttp][aiohttp],
 [Tornado][tornado], or [FastAPI][fastapi].
 
-Databasez was built for Python 3.9+ and on the top of the newest **SQLAlchemy 2** and gives you
+Databasez was built for Python 3.10+ and on the top of the newest **SQLAlchemy 2** and gives you
 simple asyncio support for a range of databases.
 
 ### Special notes
 
-This package couldn't exist without [Databases](https://www.encode.io/databasex/) and the continuous work
+This package couldn't exist without [Databases](https://www.encode.io/databases/) and the continuous work
 done by the amazing team behind it. For that reason, thank you!
 
 ## Installation
@@ -70,7 +70,7 @@ done by the amazing team behind it. For that reason, thank you!
 $ pip install databasez
 ```
 
-If you are interested in using the [test client](./test-client.md), you can also install:
+If you are interested in using the [test client](https://databasez.dymmond.com/test-client/), you can also install:
 
 ```shell
 $ pip install databasez[testing]

Taskfile.yaml

@@ -0,0 +1,27 @@
+version: 3
+
+tasks:
+  docs_prepare:
+    desc: Prepares documentation sources for Zensical
+    cmds:
+      - hatch run docs:prepare
+
+  docs_clean:
+    desc: Cleans generated docs artifacts
+    cmds:
+      - hatch run docs:clean
+
+  build:
+    desc: Builds the documentation
+    cmds:
+      - hatch run docs:build
+
+  serve:
+    desc: Runs the documentation in live mode
+    cmds:
+      - hatch run docs:serve
+
+  serve_dev:
+    desc: Runs the documentation in dev mode
+    cmds:
+      - hatch run docs:dev

docs/architecture-overview.md

@@ -0,0 +1,61 @@
+# Architecture Overview
+
+Databasez is built around a small set of objects:
+
+- `Database` for pool lifecycle and task-local connection routing.
+- `Connection` for query execution and transaction orchestration.
+- `Transaction` for context/decorator/manual transaction control.
+- Backend classes (`DatabaseBackend`, `ConnectionBackend`, `TransactionBackend`) for dialect-specific behavior.
+
+## Component relationships
+
+```mermaid
+flowchart TD
+    A["Database"] --> B["Connection"]
+    B --> C["Transaction"]
+    A --> D["DatabaseBackend"]
+    D --> E["ConnectionBackend"]
+    E --> F["TransactionBackend"]
+    D --> G["SQLAlchemy AsyncEngine"]
+```
+
+## Query lifecycle
+
+```mermaid
+sequenceDiagram
+    participant App as Application code
+    participant DB as Database
+    participant Conn as Connection
+    participant Backend as ConnectionBackend
+    participant Engine as AsyncEngine
+
+    App->>DB: fetch_all/execute/iterate
+    DB->>DB: resolve task-local or global connection
+    DB->>Conn: open context
+    Conn->>Backend: acquire()
+    Backend->>Engine: connect + execute
+    Engine-->>Backend: result
+    Backend-->>Conn: parsed rows/rowcount
+    Conn-->>DB: result
+    DB-->>App: return value
+    Conn->>Backend: release()
+```
+
+## Multiloop model
+
+Databasez is loop-aware. If the same `Database` is used from a different event loop, it can create a sub-database for that loop and proxy operations safely.
+
+```mermaid
+flowchart LR
+    L1["Loop A"] --> DB["Database (root)"]
+    L2["Loop B"] --> SUB["Sub-database (auto-created)"]
+    DB --> SUB
+    DB --> G["Global force_rollback connection"]
+    SUB --> G
+```
+
+For deeper details:
+
+- [Core Concepts](./core-concepts.md)
+- [Connections & Transactions](./connections-and-transactions.md)
+- [Extra drivers and overwrites](./extra-drivers-and-overwrites.md)

docs/connections-and-transactions.md

@@ -2,116 +2,131 @@
 
 ## Connections
 
-Connections are the heart-piece of databasez. They are enabling rollback behavior, via transactions
-and provide all manipulation functions.
-Despite there are shortcut methods on the [Database object](./database.md), they are all using
-connections internally.
-When wanting for performance reasons one connection doing multiple jobs, retrieving a connection via
-`connection()` and perform all tasks within the connection context (connections are async contextmanagers) are the way to go.
+Connections are the core execution unit in Databasez. Even when you call high-level methods on `Database`, those calls are routed through a `Connection`.
 
-### Multithreading
+If you want multiple operations in one scoped connection, use:
 
-`sqlalchemy`'s async addon is also multi-threading capable but we cannot use this for two reasons:
+```python
+async with database.connection() as connection:
+    await connection.execute(
+        "INSERT INTO notes(text) VALUES (:text)",
+        {"text": "example"},
+    )
+    rows = await connection.fetch_all("SELECT * FROM notes")
+```
+
+This is the recommended style for explicit control.
 
-- Only the `NullPool` is supported which is afaik just no pooling.
-- No global connection which is reliable resetted would be possible.
+## Task-local behavior
 
-Therefor `databasez` uses an other approach: `isolation`:
+Connections are task-local. Inside one task, repeated `database.connection()` calls reuse the same object. Different tasks receive different connections.
 
-Event-loops are per thread. So in this approach for every new event-loop detected the database object is copied and assigned to it.
-This way all connections are running in a per-thread pool. The global connection is a bit different from the rest.
-Whenever it is accessed by an other thread, asyncio.run_coroutine_threadsafe is used.
-In the full-isolation mode (default) the global connection is even moved to an own thread.
+## Global connection in rollback mode
 
-### Global connection with auto-rollback
+When `force_rollback=True`, `database.connection()` returns a global connection that is wrapped in rollback behavior.
 
-Sometimes, especially for tests, you want a connection in which all changes are resetted when the database is closed.
-For having this reliable, a global connection is lazily initialized when requested on the database object via the
-`force_rollback` contextmanager/parameter/pseudo-attribute.
+This is useful for tests, but remember:
 
-Whenever `connection()` is called, the same global connection is returned. It behaves nearly normally except you have just one connection
-available.
-This means you have to be careful when using `iterate` to not open another connection via `connection` (except you set `force_rollback` to False before opening the connection).
-Otherwise it will deadlock.
+- you are effectively sharing one connection
+- nested/parallel usage on the same connection must be planned carefully
 
-Example for `force_rollback`:
+Runnable example:
 
 ```python
 {!> ../docs_src/connections/force_rollback.py !}
 ```
 
-## Transactions
-
-Transactions are lazily initialized. You dont't need a connected database to create them via `database.transaction()`.
+## Multiloop and multithreading
 
-When created, there are three ways to activate the Transaction
+Databasez supports loop-aware routing:
 
-1. The async context manager way via `async with transaction: ...`
-2. Entering a method decorated with a transaction.
-3. The manual way via `await transaction`
+- same loop: direct call
+- different loop: operation is proxied using cross-loop helpers
+- optional full isolation: global rollback connection in a dedicated thread
 
-Whenever the transaction is activated, a connected database is required.
-
-A second way to get a transaction is via the `Connection`. It has also a `transaction()` method.
+```mermaid
+flowchart TD
+    A["Call from current loop"] --> B{"Loop matches database loop?"}
+    B -->|Yes| C["Execute directly"]
+    B -->|No| D{"Known sub-database for loop?"}
+    D -->|Yes| E["Forward to sub-database"]
+    D -->|No| F["Proxy call with async helper"]
+```
 
+## Transactions
 
-### The three ways to use a transaction
+Transactions are lazily initialized and can be used in three ways.
 
-#### Via the async context manager protocol
+### 1. Async context manager
 
 ```python
 {!> ../docs_src/transactions/async_context_database.py !}
 ```
-It can also be acquired from a specific database connection:
+
+Or from a specific connection:
 
 ```python
 {!> ../docs_src/transactions/async_context_connection.py !}
 ```
 
-#### Via decorating
-
-You can also use `.transaction()` as a function decorator on any async function:
+### 2. Decorator
 
 ```python
 {!> ../docs_src/transactions/decorating.py !}
 ```
 
-#### Manually
-
-For a lower-level transaction API:
+### 3. Manual control
 
 ```python
 {!> ../docs_src/transactions/manually.py !}
 ```
 
-### Auto-rollback (`force_rollback`)
+## Transaction options
+
+### `force_rollback`
 
-Transactions support an keyword parameter named `force_rollback` which default to `False`.
-When set to `True` at the end of the transaction a rollback is tried.
-This means all changes are undone.
+`transaction(force_rollback=True)` always rolls back on exit.
 
-This is a simpler variant of `force_rollback` of the database object.
 ```python
 {!> ../docs_src/transactions/force_rollback_transaction.py !}
 ```
 
-
 ### Isolation level
 
-The state of a transaction is liked to the connection used in the currently executing async task.
-If you would like to influence an active transaction from another task, the connection must be
-shared:
-
-Transaction isolation-level can be specified if the driver backend supports that:
+You can pass backend-supported isolation levels:
 
 ```python
 {!> ../docs_src/transactions/isolation_level.py !}
 ```
 
 ### Nested transactions
 
-Nested transactions are fully supported, and are implemented using database savepoints:
+Nested transactions are supported through savepoints:
 
 ```python
 {!> ../docs_src/transactions/nested_transactions.py !}
 ```
+
+## Transaction stack model
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant Conn as Connection
+    participant Stack as Transaction Stack
+
+    App->>Conn: begin outer transaction
+    Conn->>Stack: push outer
+    App->>Conn: begin nested transaction
+    Conn->>Stack: push savepoint
+    App->>Conn: rollback nested
+    Conn->>Stack: pop savepoint
+    App->>Conn: commit outer
+    Conn->>Stack: pop outer
+```
+
+## See also
+
+- [Database](./database.md)
+- [Queries](./queries.md)
+- [Troubleshooting](./troubleshooting.md)