@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/guides/core-concepts/persistent/search-typesense.md

@@ -1,9 +1,9 @@
 # Search & Typesense
 
-IGNIS ships a **typesense connector** under `@venizia/ignis/typesense` for full-text and faceted search. It plugs into the same `@model`/`@repository`/`@datasource` decorators as the PostgreSQL connector, but documents replace Drizzle tables and the query surface is intentionally narrower - search engines are not relational databases.
+IGNIS ships a **typesense connector** under `@venizia/ignis/typesense` for full-text and faceted search. It plugs into the same `@model`/`@repository`/`@datasource` decorators as the PostgreSQL connector. Documents replace Drizzle tables, and the query surface is intentionally narrower - search engines are not relational databases.
 
 > [!IMPORTANT] Subpath-only import
-> `typesense` is an **optional peer dependency** - the typesense connector is not re-exported from the `@venizia/ignis` root barrel (unlike `postgres`), so apps that don't use search never pull in the `typesense` client. Always import from `@venizia/ignis/typesense`:
+> `typesense` is an **optional peer dependency**. Unlike `postgres`, the typesense connector is not re-exported from the `@venizia/ignis` root barrel, so apps that don't use search never pull in the `typesense` client. Always import from `@venizia/ignis/typesense`:
 >
 > ```typescript
 > import {
@@ -77,7 +77,7 @@ The same `@model` settings you use with Drizzle entities - `hiddenProperties`, `
 | `field.geopoint(name, flags?)` | `geopoint` (`[number, number]`) |                                                                                                                                                                                       |
 | `field.vector(name, opts)`     | `float[]`                       | Embedding vector for semantic/hybrid search. Its `opts` carry `dimensions`/`distance`/`embed` rather than the shared flags - see [Vector Fields](#vector-fields-for-semantic-search). |
 
-Each `flags` object may set `searchable`, `filterable`, `facet`, `sortable`, `optional` (all `boolean`). Note: `searchable`/`filterable` have no direct Typesense wire equivalent (Typesense indexes every field by default) and are dropped at compile time - only `facet`, `optional`, and `sortable` (mapped to Typesense's `sort`) actually reach the compiled collection schema. They're still worth setting for documentation/intent and for future engines that do distinguish them.
+Each `flags` object may set `searchable`, `filterable`, `facet`, `sortable`, `optional` (all `boolean`). Note: `searchable`/`filterable` have no direct Typesense wire equivalent - Typesense indexes every field by default - so they're dropped at compile time. Only `facet`, `optional`, and `sortable` (mapped to Typesense's `sort`) actually reach the compiled collection schema. They're still worth setting for documentation/intent and for future engines that do distinguish them.
 
 `defineSearchCollection` validates at call time: throws on an empty `name`, empty `fields`, duplicate field names, a non-`string` `id` field, or an unknown `defaultSort` field reference.
 
@@ -128,7 +128,7 @@ field.vector('embedding', {
 });
 ```
 
-The `model` config is camelCase and maps to Typesense's snake_case `model_config` at compile time (`name` becomes `model_name`, `apiKey` becomes `api_key`, `accessToken` becomes `access_token`, and so on); any provider field not modeled is passed through unchanged. Never hardcode `apiKey` into a committed schema - source it from an environment variable.
+The `model` config is camelCase and maps to Typesense's snake_case `model_config` at compile time (`name` becomes `model_name`, `apiKey` becomes `api_key`, `accessToken` becomes `access_token`, and so on). Any provider field not modeled is passed through unchanged. Never hardcode `apiKey` into a committed schema - source it from an environment variable.
 
 **Client-provided vectors** - you compute the embedding yourself and send it with each document. Declare `dimensions` and a distance metric instead of `embed`:
 
@@ -160,7 +160,7 @@ static override schema = defineSearchCollection({
 });
 ```
 
-Declarative `synonyms` are provisioned as one **synonym set** per collection (named `<collection>_synonyms`) and linked to it - matching Typesense v30+'s global synonym-sets model (the pre-v30 per-collection synonyms API was removed). For runtime management outside the declarative schema, the connector exposes the synonym-set verbs through the raw client escape hatch:
+Declarative `synonyms` are provisioned as one **synonym set** per collection (named `<collection>_synonyms`) and linked to it. That matches Typesense v30+'s global synonym-sets model - the pre-v30 per-collection synonyms API was removed. For runtime management outside the declarative schema, the connector exposes the synonym-set verbs through the raw client escape hatch:
 
 ```typescript
 const connector = repository.dataSource.getConnector();
@@ -241,26 +241,38 @@ export class ArticleRepository extends DefaultSearchRepository<TArticleDocument>
 }
 ```
 
-`find()`/`findOne()`/`findById()`/`count()`/`existsWith()` accept the same `TFilter`/`TWhere` shape as PostgreSQL repositories - the `TypesenseQueryDialect` translates `where` into Typesense's `filter_by` syntax, `order` into `sort_by` (max 3 fields - a Typesense limit), `limit`/`skip` into `per_page`/`page`, and `fields` into `include_fields`. `filter.include` is **not supported** and throws - there is no relation model for documents.
+`find()`/`findOne()`/`findById()`/`count()`/`existsWith()` accept the same `TFilter`/`TWhere` shape as PostgreSQL repositories. The `TypesenseQueryDialect` translates `where` into Typesense's `filter_by` syntax, `order` into `sort_by` (max 3 fields - a Typesense limit), `limit`/`skip` into `per_page`/`page`, and `fields` into `include_fields`. `filter.include` is **not supported** and throws - there is no relation model for documents.
+
+Search engines index asynchronously, so a document can be missing right after a write. `find()`/`findOne()`/`findById()` accept the same `options.retry` as PostgreSQL - re-read until the document shows up:
+
+```typescript
+const article = await articleRepository.findById({
+  id,
+  options: { retry: { maxAttempts: 4 } },
+});
+```
+
+Same options, same rules as PostgreSQL - see [Read Retry](/references/base/repositories/advanced#read-retry-replica-lag). The only difference is moot: retry skips inside a transaction, and search has no transactions to begin with.
 
 ### Envelope differences vs. PostgreSQL
 
 |                                            | PostgreSQL repositories                             | Search repositories                                                                                                                            |
 | ------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | Range queries                              | Extra `COUNT(*)` query for `shouldQueryRange: true` | Single search call already returns `found` - no second query needed                                                                            |
-| `updateAll`/`deleteAll` with empty `where` | Requires `force: true`                              | `updateAll` **refuses** an unfiltered bulk update outright (throws, no override); `deleteAll` with no effective filter (no `where` and no `@model defaultFilter`) also throws unless `options.force: true` is passed - only then does it truncate the whole collection |
+| `updateAll`/`deleteAll` with empty `where` | Requires `force: true`                              | `updateAll` **refuses** an unfiltered bulk update outright (throws, no override). `deleteAll` with no effective filter (no `where` and no `@model defaultFilter`) also throws. Passing `options.force: true` truncates the whole collection instead |
 | Returning updated/deleted rows             | Native SQL `RETURNING`                              | No `RETURNING` equivalent - `updateAll`/`deleteAll` are **count-only**: `data` is always `null` and `shouldReturn` is rejected at the type level (no hidden engine read is bolted on). Read the affected documents explicitly before the write when you need them |
 | `createAll`                                | Native bulk insert, returns each row                | Delegates to Typesense's bulk import; "created" rows are the input rows whose per-row response didn't report `success: false`                  |
 
 ### Write error semantics (shared by both search engines)
 
-- **`create()` with a duplicate id throws `409` (`messageCode: 'core.search_engine.already_exists'`)** on both Typesense and Meilisearch - a duplicate is a conflict, never a silent overwrite. If you want last-write-wins, call `upsert()` explicitly. (On Meilisearch the pre-check is not atomic - see the [Meilisearch guide](./search-meilisearch); use `upsert()` when concurrent same-id creates are possible.)
-- **`updateById()` against a missing id throws `404` (`messageCode: 'core.search_engine.not_found'`)** on both engines. This is the deliberate divergence from the PostgreSQL connector, where a missing-id `updateById` is a silent `{ count: 0 }`.
+- **`create()` with a duplicate id throws `409`** (`normalized.code: 'core.search_engine.already_exists'`) on both Typesense and Meilisearch. A duplicate is a conflict, never a silent overwrite - call `upsert()` explicitly for last-write-wins.
+- On Meilisearch, the duplicate pre-check is not atomic, so two concurrent creates of the same id can both pass it. See the [Meilisearch guide](./search-meilisearch) and use `upsert()` when that's possible.
+- **`updateById()` against a missing id throws `404` (`normalized.code: 'core.search_engine.not_found'`)** on both engines. This is the deliberate divergence from the PostgreSQL connector, where a missing-id `updateById` is a silent `{ count: 0 }`.
 - **`deleteById()` against a missing id is silent** (`{ count: 0, data: null }`), matching the relational connectors.
 
 ## Searching with `search({ mode })`
 
-Beyond the `find()` tier (filter-only reads that return documents), `search()` is the search-engine entry point. It is one method whose shape is selected by `mode`, so TypeScript narrows the options to just that mode's fields - you never juggle every parameter at once. `mode` defaults to `keyword`.
+Beyond the `find()` tier (filter-only reads that return documents), `search()` is the search-engine entry point. It is one method whose shape is selected by `mode`, so TypeScript narrows the options to just that mode's fields. You never juggle every parameter at once. `mode` defaults to `keyword`.
 
 The `keyword`/`semantic`/`hybrid` modes reuse the same filter translation as `find()` (`@model defaultFilter`, `hiddenProperties`, `where`/`order`/`limit`), then layer the search term or vector on top. The `raw` mode is a full passthrough with no translation.
 
@@ -299,7 +311,7 @@ await repository.search({
 ```
 
 > [!NOTE]
-> `semantic` and `hybrid` default `prefix=false`: prefix matching is meaningless for vector search, and remote embedders (OpenAI/Google/...) reject it (`Prefix search is not supported for remote embedders`). Pass `engineParams: { prefix: true }` to override.
+> `semantic` and `hybrid` default `prefix=false`: prefix matching is meaningless for vector search. Remote embedders (OpenAI/Google/...) reject it too (`Prefix search is not supported for remote embedders`). Pass `engineParams: { prefix: true }` to override.
 
 **`raw`** - native Typesense params, no `TFilter`/`defaultFilter`/`hiddenProperties` translation. Use it for any engine feature the modes above do not model:
 
@@ -313,9 +325,9 @@ await repository.search({
 > [!NOTE]
 > `raw` skips `@model defaultFilter`, so it can surface documents the `find()`/`keyword` tiers would hide (for example non-`published` articles). Apply any tenant or visibility filtering explicitly in `params.filter_by` when exposing raw search over HTTP.
 
-All non-`raw` modes accept the same optional camelCase tuning fields, mapped to Typesense's snake_case at the dialect boundary: faceting (`facetBy`, `facetQuery`, `maxFacetValues`), highlighting (`highlightFields`, `highlightFullFields`, `highlightStartTag`/`highlightEndTag`, `snippetThreshold`), grouping (`groupBy`, `groupLimit`, `groupMissingValues`), and `queryByWeights`. These are the ENGINE-NEUTRAL fields - every search engine supports them.
+All non-`raw` modes accept the same optional camelCase tuning fields, mapped to Typesense's snake_case at the dialect boundary. That covers faceting (`facetBy`, `facetQuery`, `maxFacetValues`), highlighting (`highlightFields`, `highlightFullFields`, `highlightStartTag`/`highlightEndTag`, `snippetThreshold`), grouping (`groupBy`, `groupLimit`, `groupMissingValues`), and `queryByWeights`. These are the ENGINE-NEUTRAL fields - every search engine supports them.
 
-Typesense-specific tuning (`num_typos`, `prefix`, `infix`, `use_cache`, `cache_ttl`, `exhaustive_search`, `pinned_hits`, `hidden_hits`, `prioritize_exact_match`, `drop_tokens_threshold`, `preset`) goes through `engineParams`, passed verbatim to the engine with WIRE names - the neutral input schema no longer carries knobs only one engine understands:
+Typesense-specific tuning (`num_typos`, `prefix`, `infix`, `use_cache`, `cache_ttl`, `exhaustive_search`, `pinned_hits`, `hidden_hits`, `prioritize_exact_match`, `drop_tokens_threshold`, `preset`) goes through `engineParams`, passed verbatim to the engine with WIRE names. The neutral input schema no longer carries knobs only one engine understands:
 
 ```typescript
 await repository.search({
@@ -381,7 +393,7 @@ await repository.dataSource.multiSearch({
 Both `searches` entries and `commonParams` are camelCase (`filterBy`, `queryBy`, `perPage`); the datasource maps them to Typesense's snake_case wire format the same way single-collection `search()` does. For native snake_case access, `getConnector().multiSearch(...)` takes the engine's own params.
 
 > [!NOTE]
-> `multiSearch` injects each collection's `@model hiddenProperties` into that entry's `excludeFields` automatically - hidden fields never leak on the multi-search route, just as they don't on single-collection `search()`. An entry naming a collection IGNIS did not discover (not a bound `@repository` model) passes through untouched: the **caller owns exclusion** for unknown collections. The raw `getConnector().multiSearch(...)` escape hatch performs no injection at all.
+> `multiSearch` injects each collection's `@model hiddenProperties` into that entry's `excludeFields` automatically. Hidden fields never leak on the multi-search route, just as they don't on single-collection `search()`. An entry naming a collection IGNIS did not discover (not a bound `@repository` model) passes through untouched: the **caller owns exclusion** for unknown collections. The raw `getConnector().multiSearch(...)` escape hatch performs no injection at all.
 
 ## Search Controller Factory
 
@@ -403,7 +415,7 @@ const _SearchController = SearchControllerFactory.defineSearchController({
 export const ArticleSearchController = _SearchController;
 ```
 
-It registers `POST /search` (request body is the mode-discriminated schema, so validation and OpenAPI come for free and the handler dispatches to `repository.search`) and `POST /multi-search` (dispatches to `dataSource.multiSearch`). For anything the factory does not cover, write a custom `BaseRestController` calling `repository.search()` or `getClient()` directly.
+It registers `POST /search` (request body is the mode-discriminated schema, so validation and OpenAPI come for free, and the handler dispatches to `repository.search`). It also registers `POST /multi-search`, which dispatches to `dataSource.multiSearch`. For anything the factory does not cover, write a custom `BaseRestController` calling `repository.search()` or `getClient()` directly.
 
 ## Transactions and Locking
 
@@ -413,7 +425,7 @@ The typesense connector has no transaction or row-level-locking model. Passing a
 await articleRepository.updateById({
   id: '123',
   data: { title: 'New' },
-  options: { transaction: tx }, // throws: 501, messageCode 'core.not_supported'
+  options: { transaction: tx }, // throws: 501, normalized.code 'core.not_supported'
 });
 ```
 

package/content/guides/core-concepts/persistent/sqlite.md

@@ -0,0 +1,296 @@
+# SQLite
+
+IGNIS ships a **SQLite connector** at `@venizia/ignis/sqlite`, driven by libsql. It is the second engine on the engine-neutral relational tier, so `@model`, `@repository`, `@datasource`, filters, transactions and soft delete all mean the same thing they mean on Postgres.
+
+They do not all *do* the same thing. Read this table first - it is what a Postgres user needs before anything else.
+
+| Capability | PostgreSQL | SQLite | What happens |
+| :--- | :--- | :--- | :--- |
+| `ilike` | native `ILIKE` | none | Maps onto `LIKE`, which already folds ASCII case |
+| `like` | case-**sensitive** | case-**insensitive** | Silently matches more rows than on Postgres |
+| `regexp`, `iregexp` | native | none | Throws `501` `core.not_supported` |
+| `contains`, `containedBy`, `overlaps` | array operators | no array type | Throws `501` `core.not_supported` |
+| `lock` (`SELECT ... FOR UPDATE`) | row locks | file locks only | Throws `501` `core.not_supported` |
+| Isolation levels | three (`IsolationLevels`) | none | `isolationLevel` throws; pass `beginMode` instead |
+| Storage classes | ~28 types | five | `jsonb` -> json-mode `text`, `bytea` -> `blob`, `boolean` -> 0/1 `integer` |
+| JSON paths | `col #>> '{a,b}'` | `json_extract(col, '$."a"."b"')` | Same filter syntax, different SQL |
+| Timestamps | `timestamptz` | no date type | ISO 8601 UTC strings in a `text` column |
+| NULL sort order | NULL sorts **high** | NULL sorts **low** | `order: ['score ASC']` puts NULLs last on Postgres, first here |
+
+Every refusal throws `501 Not Implemented` with `normalized.code: 'core.not_supported'`. None of them silently emits different SQL.
+
+The two divergences that do not throw are the dangerous ones. `like` widens, and `nlike` narrows - on SQLite `{ nlike: 'alpha' }` **drops** the row holding `Alpha`. NULL ordering inverts. Both are pinned per engine by the conformance suite.
+
+> [!IMPORTANT] Optional peer dependency
+> `@libsql/client` is an optional peer, and the connector never reaches the `@venizia/ignis` root barrel. Import from the sub-path.
+>
+> ```bash
+> bun add @libsql/client
+> ```
+
+## What does work
+
+- **Every CRUD verb**, including `.returning()` on insert, update and delete. MySQL cannot do that, so nothing here is emulated with a read-then-write.
+- **Real transactions**, with `commit()`, `rollback()` and the same transaction object your services already pass around.
+- **The whole filter vocabulary** minus the four operators above - `and`/`or`, `between`, `inq`, `nin`, `gt`, `like`, null handling, nested logical groups.
+- **JSON path filtering and JSON path updates**, through `json_extract` and `json_set`.
+- **Relations, hidden properties, default filters, soft delete, `count`, `skip`/`limit`.**
+- **One driver for four deployments**: `:memory:`, a local file, a remote Turso database and an embedded replica.
+
+## Wiring the datasource
+
+```typescript
+import { createClient } from '@libsql/client';
+import type { Client } from '@libsql/client';
+import { datasource } from '@venizia/ignis';
+import type { TAnyDataSourceSchema, ValueOrPromise } from '@venizia/ignis';
+import { BaseSqliteDataSource } from '@venizia/ignis/sqlite';
+import type { ISqliteDataSourceSettings } from '@venizia/ignis/sqlite';
+import { LibSqlDriver } from '@venizia/ignis/sqlite/libsql';
+
+@datasource({ driver: LibSqlDriver })
+export class SqliteDataSource extends BaseSqliteDataSource<
+  ISqliteDataSourceSettings,
+  TAnyDataSourceSchema,
+  {},
+  Client
+> {
+  constructor() {
+    super({
+      name: SqliteDataSource.name,
+      config: { url: process.env.APP_ENV_SQLITE_URL ?? 'file:./data.db' },
+    });
+  }
+
+  override configure(): ValueOrPromise<void> {
+    this.client = createClient(this.settings);
+  }
+}
+```
+
+There is no `getConnectionString()` override. SQLite inherits one that returns `settings.url` - the libsql URL **is** the connection string. Postgres leaves the method abstract because no framework code can guess a `postgresql://` URL.
+
+| Setting | Type | Meaning |
+| :--- | :--- | :--- |
+| `url` | `string` | `:memory:`, `file:./data.db`, `libsql://<host>`, or an embedded-replica URL |
+| `authToken` | `string` | Turso credential; omit for a local file |
+
+## Models
+
+Same decorators, `sqliteTable` instead of `pgTable`, and the enrichers come from `@venizia/ignis/sqlite`:
+
+```typescript
+import { model } from '@venizia/ignis';
+import {
+  BaseSqliteEntity,
+  generateIdColumnDefs,
+  generateTzColumnDefs,
+} from '@venizia/ignis/sqlite';
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+@model({ type: 'entity' })
+export class Product extends BaseSqliteEntity<typeof Product.schema> {
+  static override schema = sqliteTable('Product', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...generateTzColumnDefs(),
+    name: text('name').notNull(),
+    isActive: integer('is_active', { mode: 'boolean' }).notNull().default(true),
+    metadata: text('metadata', { mode: 'json' }).$type<Record<string, unknown>>(),
+  });
+}
+```
+
+Three column choices differ from the Postgres twin:
+
+- **JSON is a json-mode `text` column.** Declare the mode. A JSON path on a plain `text` column is rejected rather than compiled into a `json_extract` that quietly returns `NULL`.
+- **Booleans are `integer(..., { mode: 'boolean' })`** - SQLite stores 0 and 1.
+- **Timestamps are ISO 8601 strings.** `generateTzColumnDefs()` handles this, defaulting to `(strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`. Comparisons stay lexicographic, so ordering by a timestamp still works.
+
+`generateIdColumnDefs` accepts `dataType: 'string'` and `dataType: 'number'`. There is no `'big-number'` - an integer primary key in SQLite is already the 64-bit rowid.
+
+## Repositories
+
+`DefaultSqliteRepository` is the base most repositories want. `ReadableSqliteRepository`, `PersistableSqliteRepository` and `SoftDeletableSqliteRepository` sit beside it, mirroring the Postgres chain.
+
+```typescript
+import { repository } from '@venizia/ignis';
+import { DefaultSqliteRepository } from '@venizia/ignis/sqlite';
+
+@repository({ model: Product, dataSource: SqliteDataSource })
+export class ProductRepository extends DefaultSqliteRepository<typeof Product.schema> {}
+```
+
+Reads look exactly like Postgres reads:
+
+```typescript
+await this.productRepository.find({
+  filter: {
+    where: { and: [{ isActive: true }, { name: { like: 'wid%' } }] },
+    order: ['createdAt DESC'],
+    limit: 20,
+  },
+});
+```
+
+Remember that `like` is case-insensitive here, so `{ like: 'wid%' }` also matches `Widget`. Non-ASCII is not folded, so `'ÉCOLE' LIKE 'é%'` is still false. Never set `PRAGMA case_sensitive_like=ON` - it would break `ilike` too.
+
+JSON paths use the same dot notation as Postgres and compile to SQLite syntax:
+
+```typescript
+{ where: { 'metadata.tier': { eq: 'gold' } } }
+// SQL: json_extract("metadata", '$."tier"') = ?
+
+{ where: { 'metadata.score': { gt: 50 } } }
+// SQL: json_extract("metadata", '$."score"') > ?  -- no cast; json_extract is already typed
+```
+
+Postgres needs a numeric cast because `#>>` always returns text. SQLite does not, because `json_extract` hands back a JSON number as `INTEGER` or `REAL`. See [JSON/JSONB Filtering](/references/base/filter-system/json-filtering) for the path grammar.
+
+## Transactions
+
+SQLite has no isolation levels. Every SQLite transaction is already serializable, so the axis is a **locking mode**:
+
+| `beginMode` | Statement | Takes the write lock |
+| :--- | :--- | :--- |
+| `SqliteBeginModes.IMMEDIATE` (default) | `BEGIN IMMEDIATE` | At `BEGIN` |
+| `SqliteBeginModes.DEFERRED` | `BEGIN DEFERRED` | At the first write |
+| `SqliteBeginModes.EXCLUSIVE` | `BEGIN EXCLUSIVE` | At `BEGIN`, blocking readers too |
+
+```typescript
+import { SqliteBeginModes } from '@venizia/ignis/sqlite';
+
+const transaction = await this.dataSource.beginTransaction({
+  beginMode: SqliteBeginModes.IMMEDIATE,
+});
+
+try {
+  await this.productRepository.create({ data: { name: 'widget' }, options: { transaction } });
+  await transaction.commit();
+} catch (error) {
+  // Nested: a first rollback that itself fails throws, and would replace the original error.
+  try {
+    await transaction.rollback();
+  } catch (rollbackError) {
+    this.logger.error('Rollback failed | %s', rollbackError);
+  }
+
+  throw error;
+}
+```
+
+`commit()` and `rollback()` throw on failure, exactly as they do on Postgres. See [Transactions](./transactions) for the full contract.
+
+The default is `IMMEDIATE`, not SQLite's own `DEFERRED`. A deferred transaction takes its write lock at the first write, and that upgrade fails outright with `SQLITE_BUSY` when another writer got there first. `IMMEDIATE` waits on the busy timeout instead.
+
+Passing `isolationLevel` throws rather than being ignored. Ignoring it would leave you believing `SERIALIZABLE` was honoured.
+
+A `beginMode` outside those three throws too. The mode is written straight into the `BEGIN` statement, which the driver runs verbatim, so it has to come from the closed set. Matching is exact - `'immediate'` is refused, because nothing upper-cases it for you.
+
+### One connection, so writes serialise
+
+`beginTransaction()` borrows the single libsql connection from a 1-slot pool. A second transaction waits. SQLite allows one writer at a time regardless, so this costs no throughput SQLite was going to give.
+
+Reads are the part to watch. A query on the pooled connector while a transaction is open runs **inside** that transaction. Pass `options.transaction` when the work belongs to the transaction, and route work that must stay outside through the driver's `acquire()`.
+
+> [!WARNING] Transactions need a local database
+> `beginTransaction()` throws `501` when the libsql client is not a `file:` or `:memory:` one. A remote client opens a stream per statement and closes it, so `BEGIN` would neither hold nor error - the transaction would silently not exist. Use a local file or an embedded replica.
+
+### The acquire timeout
+
+A transaction that never commits holds the one slot forever. Without a bound, every later `beginTransaction()` in the process hangs silently. So the wait is bounded:
+
+| Option | Type | Default | Meaning |
+| :--- | :--- | :--- | :--- |
+| `acquireTimeoutMs` | `number` | `LibSqlDriver.DEFAULT_ACQUIRE_TIMEOUT_MS` (30000) | Max ms to wait for the connection before rejecting |
+| `maxWaitingClients` | `number` | unlimited | Max queued waiters; over the limit, `acquire()` rejects immediately |
+| `scope` | `string` | `'LibSqlDriver'` | Logger scope |
+| `client` | `Client` | required | The libsql client the driver borrows |
+
+The timeout bounds the **wait for the connection**, never the transaction itself. It fires only under contention, so a migration or a bulk seed running alone never trips it. When it does fire you get a named error, not a dead process:
+
+```
+[LibSqlDriver][acquire] Could not borrow the single libsql connection
+| [acquire] Acquire timed out after 30000ms.
+| An unreleased transaction still holds it - commit/rollback it, or raise `acquireTimeoutMs`
+```
+
+To change any of these, construct the driver yourself with `useDriver()`. That assigns the driver and builds the connector in one step, and bypasses `@datasource({ driver })`:
+
+```typescript
+override configure(): void {
+  const client = createClient(this.settings);
+
+  this.useDriver({
+    driver: new LibSqlDriver({ client, acquireTimeoutMs: 120_000 }),
+    schema: this.getSchema(),
+  });
+}
+```
+
+`size` is not an option. One slot **is** the mutual exclusion the single connection lacks, so it is pinned at 1.
+
+## Schema and migrations
+
+drizzle-kit, with the `sqlite` dialect:
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './src/models/**/*.model.ts',
+  out: './migrations',
+  dbCredentials: { url: 'file:./data.db' },
+});
+```
+
+Use `dialect: 'turso'` instead for a remote database - it adds `authToken` to `dbCredentials`.
+
+```bash
+bun run drizzle-kit generate
+```
+
+Apply them at boot, before the first repository call:
+
+```typescript
+import { drizzle } from 'drizzle-orm/libsql';
+import { migrate } from 'drizzle-orm/libsql/migrator';
+
+export const applyMigrations = async (opts: { dataSource: SqliteDataSource }): Promise<void> => {
+  const client = opts.dataSource.getClient();
+
+  await migrate(drizzle({ client }), { migrationsFolder: './migrations' });
+};
+```
+
+## Out of scope in this release
+
+Three components declare their models as `pgTable` and are Postgres-only for now. A SQLite datasource cannot back them:
+
+| Component | Why |
+| :--- | :--- |
+| **Authentication** | `User`, `Role`, `Permission` and `PolicyDefinition` are `pgTable` models |
+| **Authorization** | The Casbin adapters type their connector as Drizzle's `PgDatabase` |
+| **StaticAssetComponent** | Its base model is a `pgTable` with `jsonb` and Postgres indexes |
+
+Everything else - your own models, repositories, services, controllers, REST routes - works on either engine.
+
+## Runnable example
+
+`examples/sqlite-quickstart/` is this page as an app: a `sqliteTable` model with a `text` id and `text({ mode: 'json' })` metadata, `generateTzColumnDefs` for the timestamp default, and the same repository and controller the PGlite example uses.
+
+```bash
+cd examples/sqlite-quickstart
+bun install
+bun run start        # http://localhost:3000/api/notes
+```
+
+## See Also
+
+- [PGlite](./pglite) - the other embedded engine, with real Postgres semantics
+- [Postgres Drivers & Supabase](./postgres-drivers) - the driver seam
+- [DataSources](./datasources) - schema auto-discovery and `configure()`
+- [Transactions](./transactions) - the transaction object and connection safety
+- [JSON/JSONB Filtering](/references/base/filter-system/json-filtering) - the JSON path grammar
+- [Connectors](/references/base/connectors) - the engine-neutral contract

package/content/guides/core-concepts/persistent/transactions.md

@@ -3,7 +3,7 @@
 IGNIS supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
 
 > [!NOTE] PostgreSQL-only capability
-> Real transactions are a **PostgreSQL connector** capability - `BasePostgresDataSource.getCapabilities()` returns `{ transactions: true }` and its `beginTransaction()` opens a real database transaction, as documented below. The typesense connector inherits the engine-neutral `AbstractDataSource` default: calling `beginTransaction()` on it throws a `501 Not Implemented` (`messageCode: 'core.not_supported'`) via the shared `throwNotSupported` utility. See [Connectors](/references/base/connectors) for the capabilities model.
+> Real transactions are a **PostgreSQL connector** capability - `BasePostgresDataSource.getCapabilities()` returns `{ transactions: true }` and its `beginTransaction()` opens a real database transaction, as documented below. The typesense connector inherits the engine-neutral `AbstractDataSource` default. Calling `beginTransaction()` on it throws a `501 Not Implemented` (`normalized.code: 'core.not_supported'`) via the shared `throwNotSupported` utility. See [Connectors](/references/base/connectors) for the capabilities model.
 
 ## Using Transactions
 
@@ -51,18 +51,18 @@ try {
 > `COMMIT` can genuinely fail - a deadlock, a serialization failure under `SERIALIZABLE`, a dropped
 > connection, a deferred constraint firing at commit time. When it does, `commit()` throws rather
 > than resolving, so you never report success on a write that was never persisted. The connection is
-> then destroyed instead of being returned to the pool, because it may still hold an open
+> then destroyed instead of being returned to the pool. It may still hold an open
 > transaction that the next borrower would inherit.
 >
 > `rollback()` behaves the same way when it is the FIRST verb to fail. One deliberate exception
-> keeps the everyday `catch { await tx.rollback(); throw error; }` pattern safe: calling
+> keeps the everyday `catch { await tx.rollback(); throw error; }` pattern safe. Calling
 > `rollback()` on a transaction that already ended BY FAILURE (a failed `COMMIT` or a failed prior
-> `ROLLBACK`) is a silent no-op - nothing was committed and the connection is already destroyed, so
+> `ROLLBACK`) is a silent no-op. Nothing was committed and the connection is already destroyed, so
 > the rollback's goal is achieved and your original error survives. The nested-try form above is
 > still the safest general pattern, because a FIRST rollback that itself fails does throw.
 >
-> The destroy half is **driver-specific**: node-postgres (`pg`) discards the poisoned connection,
-> but postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so under the
+> The destroy half is **driver-specific**: node-postgres (`pg`) discards the poisoned connection.
+> But postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so under the
 > postgres-js driver the connection returns to the pool anyway. See
 > [Postgres Drivers & Supabase](./postgres-drivers) for the full asymmetry.
 
@@ -78,7 +78,7 @@ try {
 | `commit()` | `Promise<void>` | Commit and release the connection. **Throws** if `COMMIT` fails, and destroys the connection rather than pooling it |
 | `rollback()` | `Promise<void>` | Rollback and release the connection. **Throws** if `ROLLBACK` fails, and destroys the connection rather than pooling it |
 
-Calling `commit()` or `rollback()` on an already-ended transaction throws an error, with one exception: `rollback()` after the transaction ended BY FAILURE is a silent no-op (see the warning above).
+Calling `commit()` or `rollback()` on an already-ended transaction throws an error. The one exception: `rollback()` after the transaction ended BY FAILURE is a silent no-op (see the warning above).
 
 ## Isolation Levels
 
@@ -95,9 +95,10 @@ IGNIS supports standard PostgreSQL isolation levels:
 
 ## Best Practices
 
-1.  **Always use `try...catch`, and nest the rollback**: `rollback()` throws when `ROLLBACK` fails, so a bare `await tx.rollback()` inside a `catch` would discard the error that sent you there. Wrap it in its own `try...catch`, log the rollback failure, and rethrow the original cause.
-2.  **Keep it short**: Long-running transactions hold database connections from the pool and can cause connection exhaustion.
-3.  **Pass explicit options**: When calling other services inside a transaction, ensure they accept and use the `transaction` option.
+1.  **Always use `try...catch`, and nest the rollback**: `rollback()` throws when `ROLLBACK` fails. A bare `await tx.rollback()` inside a `catch` would discard the error that sent you there.
+2.  **Wrap the rollback in its own `try...catch`**: log the rollback failure, and rethrow the original cause.
+3.  **Keep it short**: Long-running transactions hold database connections from the pool and can cause connection exhaustion.
+4.  **Pass explicit options**: When calling other services inside a transaction, ensure they accept and use the `transaction` option.
 
 ```typescript
 // Service method supporting transactions
@@ -196,7 +197,7 @@ export class OrderController extends BaseRestController {
 
 ## How Transactions Work Internally
 
-When you pass a `transaction` option to a repository method, the repository uses the transaction's `connector` (a Drizzle instance bound to the transaction's dedicated connection) instead of the default datasource connector. This ensures all operations within the transaction use the same database connection and see a consistent view of the data.
+When you pass a `transaction` option to a repository method, the repository uses the transaction's `connector` instead of the default datasource connector. That connector is a Drizzle instance bound to the transaction's dedicated connection. All operations within the transaction therefore use the same database connection and see a consistent view of the data.
 
 ```typescript
 // Inside PostgresBaseRepository (simplified)