@venizia/ignis-docs 0.1.0 → 0.2.0

package/content/best-practices/data-modeling.md

@@ -296,7 +296,7 @@ DataSources automatically discover their schema from the repositories that bind
 // src/datasources/postgres.datasource.ts
 import { datasource, ValueOrPromise } from '@venizia/ignis';
 import { BasePostgresDataSource } from '@venizia/ignis/postgres';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDataSourceConfigs {
@@ -307,7 +307,7 @@ interface IDataSourceConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
   constructor() {
     super({
@@ -319,11 +319,11 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
 
   override configure(): ValueOrPromise<void> {
     // getSchema() automatically collects all schemas from bound repositories
-    const schema = this.getSchema();
+    this.logger.debug('[configure] Auto-discovered schema | Keys: %o', Object.keys(this.getSchema()));
 
-    // Keep the pool on this.client - beginTransaction() resolves its driver from it
+    // Keep the pool on this.client - naming NodePostgresDriver above is what wires the driver
+    // and Drizzle connector; beginTransaction() resolves its driver from this.client lazily.
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 
   override getConnectionString(): ValueOrPromise<string> {

package/content/best-practices/performance-optimization.md

@@ -207,13 +207,16 @@ Connection pooling significantly improves performance by reusing database connec
 
 ```typescript
 import { Pool } from 'pg';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { datasource } from '@venizia/ignis';
 import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 
 // IDataSourceConfigs: your settings interface (host/port/user/password/database)
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
   override configure(): void {
-    // Keep the pool on `this.client` - beginTransaction() resolves its driver from it
+    // Keep the pool on `this.client` - NodePostgresDriver above wires the driver and Drizzle
+    // connector from it lazily, on first getConnector()/beginTransaction()
     this.client = new Pool({
       host: this.settings.host,
       port: this.settings.port,
@@ -228,8 +231,6 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
       connectionTimeoutMillis: 5000, // Fail if can't connect in 5s
       maxUses: 7500,                // Close connection after 7500 queries
     });
-
-    this.connector = drizzle({ client: this.client, schema: this.getSchema() });
   }
 }
 ```

package/content/extensions/helpers/kafka/compile-binary.md

@@ -0,0 +1,92 @@
+# Compiling to a Single Binary
+
+`bun build --compile` produces a standalone executable that crashes on startup when the application
+imports any Kafka helper, unless the build registers `platformaticWasmPlugin`.
+
+```
+ENOENT: no such file or directory, open '/$bunfs/dist/native.wasm'
+```
+
+The failure happens while the module graph is still loading -- before the IGNIS application boots, so
+no log line, no lifecycle hook, and no error handler of yours ever runs.
+
+## Why it happens
+
+`@platformatic/kafka` computes Kafka's CRC32C checksums and lz4/snappy compression in WebAssembly,
+through `@platformatic/wasm-utils`. The default entrypoint of that package reads the wasm payload
+from disk at module load time:
+
+```javascript
+// @platformatic/wasm-utils/dist/index.js
+const wasm = readFileSync(new URL('../dist/native.wasm', import.meta.url));
+```
+
+`bun build --compile` embeds JavaScript modules only -- assets such as `native.wasm` are not carried
+into the executable. Inside the binary, `import.meta.url` resolves against the virtual `/$bunfs`
+filesystem, the file is not there, and the read throws.
+
+Running from source (`bun run`, `bun .`) is unaffected: `node_modules` is on disk, so the read
+succeeds. The bug only exists in compiled binaries.
+
+## The fix
+
+`@platformatic/wasm-utils` ships a second entrypoint, `@platformatic/wasm-utils/bundled`, exposing
+the same API with the wasm payload inlined as base64 -- no filesystem read. `platformaticWasmPlugin`
+swaps one entrypoint for the other at bundle time.
+
+Compile through a Bun build script instead of the `bun build --compile` CLI, which cannot register
+plugins:
+
+```typescript
+// scripts/compile.ts
+import { platformaticWasmPlugin } from '@venizia/ignis-helpers/kafka';
+
+const built = await Bun.build({
+  entrypoints: ['./dist/index.js'],
+  target: 'bun',
+  minify: { whitespace: true, syntax: true },
+  sourcemap: 'linked',
+  compile: {
+    target: process.env.BUN_TARGET ?? 'bun-linux-x64',
+    outfile: './dist/bin',
+  },
+  plugins: [platformaticWasmPlugin()],
+});
+
+if (!built.success) {
+  console.error(built.logs);
+  process.exit(1);
+}
+```
+
+```json
+{
+  "scripts": {
+    "compile": "bun run ./scripts/compile.ts"
+  }
+}
+```
+
+The plugin resolves `@platformatic/wasm-utils/bundled` from the importing module's own directory, so
+it works with hoisted and isolated `node_modules` layouts alike, and pins no package version.
+
+## Verifying
+
+A correctly built binary contains no reference to the wasm file on disk:
+
+```bash
+grep -c 'native.wasm' ./dist/bin   # 0 -- the payload is inlined
+./dist/bin                         # boots instead of throwing ENOENT
+```
+
+The binary grows by roughly 76 KB, the base64 form of the 57 KB wasm module.
+
+## Notes
+
+- Upgrading `@platformatic/kafka` does not remove the need for the plugin: every release to date,
+  including 2.6.1, imports the default `@platformatic/wasm-utils` entrypoint.
+- Applications that never import a Kafka helper need no plugin -- nothing pulls in
+  `@platformatic/wasm-utils`, and the plugin's resolver never fires.
+- Patching `node_modules` during the build achieves the same result, but mutates a dependency in
+  place, pins the store path to one version, and leaves the tree dirty when a build fails. The
+  plugin needs neither.

package/content/extensions/helpers/kafka/index.md

@@ -88,6 +88,9 @@ import type {
 > [!NOTE]
 > Kafka helpers are **not** re-exported from the main `@venizia/ignis-helpers` entry point. You must use the `@venizia/ignis-helpers/kafka` subpath import. This keeps the optional `@platformatic/kafka` peer dependency isolated for tree-shaking.
 
+> [!WARNING]
+> Compiling an application that uses these helpers with `bun build --compile` produces a binary that dies on startup with `ENOENT: /$bunfs/dist/native.wasm`. The build must register `platformaticWasmPlugin` from `@venizia/ignis-helpers/kafka` -- see [Compiling to a Single Binary](./compile-binary.md).
+
 ### Installation
 
 ```bash

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

@@ -14,7 +14,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -25,7 +25,7 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -42,16 +42,11 @@ export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    // getSchema() auto-discovers models from @repository bindings
-    const schema = this.getSchema();
-
-    this.logger.debug(
-      '[configure] Auto-discovered schema | Keys: %o',
-      Object.keys(schema),
-    );
+    const schema = Object.keys(this.getSchema());
+    this.logger.debug('[configure] Auto-discovered schema | Keys: %o', schema);
 
+    // That is all - naming NodePostgresDriver above is what wires the driver and connector.
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 
   override getConnectionString(): ValueOrPromise<string> {
@@ -62,22 +57,22 @@ export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
 ```
 
 > [!NOTE] Driver seam: the raw client goes on `this.client`
-> `this.client = new Pool(...)` is the short path: IGNIS resolves a `node-postgres` driver from that client on first use. There is no `pool` field - the raw-client slot is `client`, whatever the client happens to be. The alternative is to wire a driver yourself: `configure()` calls `this.useDriver({ driver, schema? })`, which assigns `this.driver` **and** builds `this.connector` in one step (so the half-wired state cannot exist). That is also how you select the `postgres-js` driver or run on Supabase. See [Postgres Drivers & Supabase](./postgres-drivers).
+> `this.client = new Pool(...)` is the short path: `configure()` builds only the client, and `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over it - `NodePostgresDriver` here. There is no `pool` field - the raw-client slot is `client`, whatever the client happens to be. Naming the driver class (rather than a driver-name string) is what carries `pg` into the app's bundle - a bundler only packages a real value reference, never text. The alternative is to wire a driver yourself for a custom or third-party driver: `configure()` calls `this.useDriver({ driver, schema? })`, which assigns `this.driver` **and** builds `this.connector` in one step (so the half-wired state cannot exist), bypassing `@datasource({ driver })` entirely. See [Postgres Drivers & Supabase](./postgres-drivers) for `postgres-js` and Supabase.
 
 **How auto-discovery works:**
 
 1. `@repository` decorators register model-datasource bindings in the `MetadataRegistry`
-2. When `configure()` is called, `getSchema()` invokes `discoverSchema()` which calls `MetadataRegistry.buildSchema({ dataSource })` to collect all bound models and their relations
-3. Drizzle is initialized with the complete schema (tables + Drizzle relations)
+2. `getSchema()` invokes `discoverSchema()` which calls `MetadataRegistry.buildSchema({ dataSource })` to collect all bound models and their relations
+3. The lazily-built Drizzle connector is initialized with the complete schema (tables + Drizzle relations)
 
-You can disable auto-discovery per datasource via `@datasource({ driver: 'node-postgres', autoDiscovery: false })`.
+You can disable auto-discovery per datasource via `@datasource({ driver: NodePostgresDriver, autoDiscovery: false })`.
 
 ## Manual Schema (Optional)
 
 If you need explicit control, you can still provide schema manually:
 
 ```typescript
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -99,7 +94,7 @@ export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
 AbstractDataSource extends BaseHelper        # engine-neutral, src/base - no pool, no Drizzle
   └── AbstractPostgresDataSource              # connectors/postgres - adds pool, connector
         └── BasePostgresDataSource (alias: BaseDataSource)
-              ├── configure()               # Setup pool + Drizzle connector (abstract)
+              ├── configure()               # Assign this.client (abstract) - base wires driver + connector
               ├── getConnectionString()     # Build connection URL (abstract)
               ├── getSchema()               # Auto-discover from @repository bindings
               ├── discoverSchema()          # Internal: reads MetadataRegistry
@@ -135,7 +130,7 @@ DataSources are bound as **singletons** to ensure connection pool sharing across
 
 ```typescript
 import { BasePostgresDataSource, datasource, ValueOrPromise } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -146,7 +141,7 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -162,9 +157,7 @@ export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 
   override getConnectionString(): ValueOrPromise<string> {

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

@@ -49,7 +49,7 @@ export class User extends BasePostgresEntity<typeof User.schema> {
 }
 
 // 2. Create a DataSource
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -65,9 +65,7 @@ export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
-    this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
+    this.client = new Pool(this.settings); // NodePostgresDriver above wires the driver + connector
   }
 
   override getConnectionString(): ValueOrPromise<string> {

package/content/guides/core-concepts/persistent/postgres-drivers.md

@@ -8,7 +8,7 @@ IGNIS talks to PostgreSQL through a **driver seam**: `IRelationalDriver` owns co
 Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies the **driver**, not the SQL dialect. The `@venizia/ignis/postgres/supabase` submodule adds the two things Supabase deployments actually need - pooler presets and an RLS auth-context helper.
 
 > [!IMPORTANT] Every database client is optional
-> `pg` and `postgres` are both **optional peer dependencies**. The `@venizia/ignis/postgres` module pulls in neither - each driver is imported lazily, only when the client you built selects it. Install the one your app uses:
+> `pg` and `postgres` are both **optional peer dependencies**. The `@venizia/ignis/postgres` module pulls in neither - only the driver class you import and name in `@datasource({ driver })` reaches your bundle. Install the one your app uses:
 >
 > ```bash
 > bun add pg          # node-postgres
@@ -19,60 +19,89 @@ Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies
 
 | Import | Contents | Loads |
 | :--- | :--- | :--- |
-| `@venizia/ignis/postgres` | `BasePostgresDataSource`, `IRelationalDriver`, `resolveDatabaseDriver`, repository hierarchy | no client library |
+| `@venizia/ignis/postgres` | `BasePostgresDataSource`, `IRelationalDriver`, repository hierarchy | no client library |
 | `@venizia/ignis/postgres/node-postgres` | `NodePostgresDriver` | `pg` |
 | `@venizia/ignis/postgres/postgres-js` | `PostgresJsDriver` | `postgres` |
 | `@venizia/ignis/postgres/supabase` | `PoolerModes`, `buildPostgresJsOptions`, `withAuthContext`, Supabase role re-exports | `drizzle-orm/supabase` |
 
-## The Default: a Bare Pool
+## Naming the Driver Class
 
-Hand IGNIS a `pg.Pool` on `this.client` and it adopts it into a `NodePostgresDriver` on first use - no driver import needed:
+`@datasource({ driver })` takes the driver **class**, not a driver-name string:
 
 ```typescript
-import { DataSourceDrivers, datasource } from '@venizia/ignis';
+import { datasource, ValueOrPromise } from '@venizia/ignis';
 import { BasePostgresDataSource } from '@venizia/ignis/postgres';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
-@datasource({ driver: DataSourceDrivers.NODE_POSTGRES })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
-  configure() {
-    this.client = new Pool({ connectionString: this.getConnectionString() });
-    this.connector = drizzle({ client: this.client, schema: this.getSchema() });
+  override configure(): ValueOrPromise<void> {
+    this.client = new Pool({ connectionString: this.getConnectionString() }); // that is all
   }
 }
 ```
 
-`this.client` is the raw-client slot: the `pg.Pool` (or postgres-js `Sql`) your `configure()` built. `getClient()` hands it back as the escape hatch, and `beginTransaction()` resolves a driver from it lazily. A datasource that sets neither `this.client` nor a driver throws `No driver and no client` on its first transaction.
+`configure()` only builds `this.client` - the raw `pg.Pool` (or postgres-js `Sql`) your app's connection settings produce. The base class wires the driver **and** the connector lazily, on first call to `getConnector()` or `beginTransaction()`: it reads the class named in `@datasource({ driver })`, instantiates it over `this.client`, and builds the pooled Drizzle connector from that. `getClient()` hands `this.client` back as the raw-client escape hatch. A datasource that sets neither `this.client` nor a driver (via `useDriver()`, below) throws `No driver and no client` on first use.
+
+> [!IMPORTANT] Why a class, not a name
+> A driver-name string cannot carry `pg` or `postgres` into your bundle - it is just text. A dynamic `import('./node-postgres.js')` keyed off that string would defer *execution*, not *packaging*: every bundler statically resolves a literal specifier and packages whatever it points to, so a build that only used node-postgres would still fail with `Could not resolve: "postgres"` the moment postgres-js's import appeared anywhere in the module graph reachable at build time. Naming the class instead makes the driver module a real value reference - the one thing a bundler is forced to keep - which is what lets `pg` and `postgres` stay genuinely optional peers. A bare side-effect import (`import '@venizia/ignis/postgres/node-postgres'`) would not work either: `@venizia/ignis` declares `sideEffects: false`, so a bundler is free to drop an import whose exports go unused.
+>
+> Two tests pin this from different angles: `packages/core/src/__tests__/connectors/postgres/no-eager-driver-import.test.ts` proves no barrel **loads** a driver package in a fresh process (the runtime module graph), and `packages/core/src/__tests__/connectors/postgres/bundle/optional-peers.test.ts` proves no barrel gets a driver package **packaged** by a real bundler.
 
 ## Using postgres-js
 
-Wire a driver explicitly with `useDriver()` - it assigns the driver **and** builds the pooled connector in one step, so the half-wired state (driver set, connector forgotten) cannot exist:
+Same shape, different class:
 
 ```typescript
-import { DataSourceDrivers, datasource } from '@venizia/ignis';
+import { datasource, ValueOrPromise } from '@venizia/ignis';
 import { BasePostgresDataSource } from '@venizia/ignis/postgres';
 import { PostgresJsDriver } from '@venizia/ignis/postgres/postgres-js';
 import postgres from 'postgres';
 import type { Sql } from 'postgres';
 
-@datasource({ driver: DataSourceDrivers.POSTGRES_JS })
+@datasource({ driver: PostgresJsDriver })
 export class PostgresDataSource extends BasePostgresDataSource<
   IDataSourceConfigs,
   typeof schema,
   {},
   Sql // getClient() is now honestly typed as postgres-js's Sql, not pg.Pool
 > {
-  configure() {
+  override configure(): ValueOrPromise<void> {
+    this.client = postgres(this.getConnectionString());
+  }
+}
+```
+
+The fourth type parameter (`Client`) defaults to `pg.Pool`; declare it when the raw client escape hatch (`getClient()`) should carry the real type.
+
+## Driver Constructors Validate Their Client
+
+Both shipped drivers throw immediately if constructed with the wrong shape of client, instead of failing later inside a query:
+
+```typescript
+new NodePostgresDriver({ client: pool }); // client must expose connect() AND totalCount (pool accounting)
+new PostgresJsDriver({ client: sql });    // client must expose reserve() AND unsafe()
+```
+
+`NodePostgresDriver` rejects a bare `pg.Client` - it exposes `connect()` too, but has no pool accounting and cannot hand out a dedicated connection per transaction. `PostgresJsDriver` rejects a `pg.Pool` the same way. You will not normally construct these yourself: `wireDriverFromMetadata()` does it for you from `this.client`, so this validation fires the first time a datasource wired the wrong client behind the wrong `@datasource({ driver })` class.
+
+## Custom or Third-Party Drivers: `useDriver()`
+
+For a driver IGNIS does not ship, wire it explicitly with `useDriver()` - it assigns the driver **and** builds the pooled connector in one step, so the half-wired state (driver set, connector forgotten) cannot exist:
+
+```typescript
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure(): ValueOrPromise<void> {
     this.useDriver({
-      driver: new PostgresJsDriver({ client: postgres(this.getConnectionString()) }),
+      driver: new MyCustomDriver({ client: myClient }),
       schema: this.getSchema(),
     });
   }
 }
 ```
 
-The fourth type parameter (`Client`) defaults to `pg.Pool`; declare it when the raw client escape hatch (`getClient()`) should carry the real type.
+`useDriver()` bypasses `@datasource({ driver })` entirely - you never need to name a class in the decorator when you wire the driver yourself in `configure()`.
 
 > [!WARNING] postgres-js cannot destroy a poisoned connection
 > After a failed `COMMIT` or `ROLLBACK`, node-postgres **destroys** the connection instead of pooling it - the session may still hold an open transaction that the next borrower would inherit. postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so the connection is returned to the pool anyway. This asymmetry is real and IGNIS does not paper over it; it is pinned by the driver's own tests.
@@ -117,18 +146,23 @@ Supabase exposes three ways in, and one of them silently breaks prepared stateme
 The transaction pooler (Supavisor) rebinds the backend per transaction, so a server-side prepared statement created on one backend simply is not there next time. `buildPostgresJsOptions` encodes this so you cannot forget it:
 
 ```typescript
-import { buildPostgresJsOptions, PoolerModes } from '@venizia/ignis/postgres/supabase';
+import { datasource } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
 import { PostgresJsDriver } from '@venizia/ignis/postgres/postgres-js';
+import { buildPostgresJsOptions, PoolerModes } from '@venizia/ignis/postgres/supabase';
 import postgres from 'postgres';
 
-const client = postgres(connectionString, {
-  ...buildPostgresJsOptions({ mode: PoolerModes.TRANSACTION, max: 10 }),
-});
-
-this.useDriver({ driver: new PostgresJsDriver({ client }), schema: this.getSchema() });
+@datasource({ driver: PostgresJsDriver })
+export class SupabaseDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure() {
+    this.client = postgres(connectionString, {
+      ...buildPostgresJsOptions({ mode: PoolerModes.TRANSACTION, max: 10 }),
+    });
+  }
+}
 ```
 
-`prepare: false` is emitted only for `TRANSACTION` mode; `max` is forwarded only when you pass it, so postgres-js's own default survives.
+`prepare: false` is emitted only for `TRANSACTION` mode; `max` is forwarded only when you pass it, so postgres-js's own default survives. Naming `PostgresJsDriver` in `@datasource` is what wires it - `configure()` only needs to build the client, same as node-postgres.
 
 ### Row Level Security
 
@@ -164,4 +198,4 @@ The submodule also re-exports Drizzle's Supabase helpers (`anonRole`, `authentic
 
 ## Adding a Driver
 
-One file under `src/connectors/postgres/drivers/`, implementing the four verbs above, plus a fake client and a test that runs the shared conformance suite (`run({ driver, resolveDatabaseDriver })` in `src/__tests__/connectors/postgres/drivers/conformance/`). Register a sub-path export and an optional peer dependency; never re-export the driver from the drivers barrel - that is what would make its package load eagerly for everyone.
+One file under `src/connectors/postgres/drivers/`, implementing the four verbs above, plus a fake client and a test that runs the shared conformance suite (`run({ driver, buildDriverProbe })` in `src/__tests__/connectors/postgres/drivers/conformance/`). Register a sub-path export and an optional peer dependency; never re-export the driver from the drivers barrel - that is what would make its package load eagerly for everyone.

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

@@ -61,10 +61,12 @@ The `searchable` and `filterable` flags are **load-bearing here** and are silent
 import { datasource } from '@venizia/ignis';
 import { MeilisearchDataSource } from '@venizia/ignis/meilisearch';
 
-@datasource({ driver: 'meilisearch' })
+@datasource()
 export class ArticleSearchDataSource extends MeilisearchDataSource {}
 ```
 
+No `driver` in the decorator, and that is not an omission. A relational datasource has to name one, because a single `BasePostgresDataSource` runs on either `pg` or `postgres` and something must pick. A search datasource has already picked: `extends MeilisearchDataSource` **is** the engine reference, and it is what carries the `meilisearch` package into your bundle. Naming the engine twice would just be a second chance to disagree with yourself.
+
 Configured through `IMeilisearchDataSourceSettings`:
 
 ```typescript

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

@@ -176,11 +176,11 @@ await connector.linkSynonymSets({ collection: 'articles', synonymSets: ['article
 
 ```typescript
 // src/datasources/search.datasource.ts
-import { DataSourceDrivers, datasource } from '@venizia/ignis';
+import { datasource } from '@venizia/ignis';
 import { TypesenseDataSource } from '@venizia/ignis/typesense';
 import { applicationEnvironment, int } from '@venizia/ignis-helpers';
 
-@datasource({ driver: DataSourceDrivers.TYPESENSE })
+@datasource()
 export class SearchDataSource extends TypesenseDataSource {
   constructor() {
     super({
@@ -201,6 +201,8 @@ export class SearchDataSource extends TypesenseDataSource {
 }
 ```
 
+No `driver` in the decorator, and that is not an omission. A relational datasource has to name one, because a single `BasePostgresDataSource` runs on either `pg` or `postgres` and something must pick. A search datasource has already picked: `extends TypesenseDataSource` **is** the engine reference, and it is what carries the `typesense` package into your bundle. Naming the engine twice would just be a second chance to disagree with yourself.
+
 `TypesenseDataSource` extends `BaseSearchDataSource` (adds auto-discovery/provisioning) which extends `AbstractSearchDataSource` (engine contract: `getDriver()`, `getQueryDialect()`, `compileCollection()`, `ensureCollection()`) which extends the engine-neutral `AbstractDataSource`. Since `TypesenseDataSource` never overrides `beginTransaction()`, it inherits the neutral `NotSupported` default - see [Connectors](/references/base/connectors).
 
 On `configure()`, the datasource auto-provisions every discovered collection (`ensureCollection()` per definition, plus any declared `synonyms`) unless constructed with `autoProvision: false`.

package/content/guides/tutorials/building-a-crud-api.md

@@ -179,7 +179,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -195,15 +195,14 @@ interface IDSConfigs {
  *
  * How it works:
  * 1. @repository decorator binds model to datasource
- * 2. When configure() is called, getSchema() auto-discovers all bound models
- * 3. Drizzle is initialized with the auto-discovered schema
+ * 2. getSchema() auto-discovers all bound models when the driver/connector are wired
+ * 3. Naming NodePostgresDriver in @datasource is what wires the driver and Drizzle connector
  */
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
-      // Driver is read from @datasource decorator - no need to pass here!
       config: {
         host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
         port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
@@ -216,11 +215,8 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    // getSchema() auto-discovers models from @repository bindings
-    const schema = this.getSchema();
-
-    // Log discovered schema for debugging
-    const schemaKeys = Object.keys(schema);
+    // getSchema() auto-discovers models from @repository bindings; log it for debugging
+    const schemaKeys = Object.keys(this.getSchema());
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
       schemaKeys.length,
@@ -228,9 +224,9 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
     );
 
     // The client must land on this.client - a local would leave beginTransaction() with nothing
-    // to resolve a driver from, and it would throw `No driver and no client`.
+    // to resolve a driver from, and it would throw `No driver and no client`. NodePostgresDriver
+    // named in @datasource above is what wires the driver and Drizzle connector from it.
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 }
 ```
@@ -239,7 +235,7 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
 - Schema is auto-discovered from `@repository` decorators - no manual registration needed
 - Uses `getSchema()` for lazy schema resolution (resolves when all models are loaded)
 - Uses environment variables for connection config
-- Implements `configure()` for connection setup and `getConnectionString()` for URL generation
+- `configure()` only assigns `this.client` - the base class wires the driver and connector from `@datasource({ driver })`; implements `getConnectionString()` for URL generation
 
 > **Deep Dive:** See [DataSources Reference](/references/base/datasources) for advanced configuration and multiple database support.
 

package/content/guides/tutorials/ecommerce-api.md

@@ -357,7 +357,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -368,7 +368,7 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -384,18 +384,18 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
+    const schema = Object.keys(this.getSchema());
 
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      Object.keys(schema).length,
-      Object.keys(schema),
+      schema.length,
+      schema,
     );
 
     // The client must land on this.client - a local would leave beginTransaction() with nothing
-    // to resolve a driver from, and it would throw `No driver and no client`.
+    // to resolve a driver from, and it would throw `No driver and no client`. NodePostgresDriver
+    // named in @datasource above is what wires the driver and Drizzle connector from it.
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 }
 ```

package/content/guides/tutorials/realtime-chat.md

@@ -268,7 +268,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -279,7 +279,7 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -295,18 +295,18 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
+    const schema = Object.keys(this.getSchema());
 
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      Object.keys(schema).length,
-      Object.keys(schema),
+      schema.length,
+      schema,
     );
 
     // The client must land on this.client - a local would leave beginTransaction() with nothing
-    // to resolve a driver from, and it would throw `No driver and no client`.
+    // to resolve a driver from, and it would throw `No driver and no client`. NodePostgresDriver
+    // named in @datasource above is what wires the driver and Drizzle connector from it.
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 }
 ```

package/content/references/base/connectors.md

@@ -105,7 +105,7 @@ IGNIS ships both a **root barrel** (backward-compatible default) and **per-engin
 ```
 
 > [!IMPORTANT] Concrete Postgres drivers are sub-path only
-> `pg` and `postgres` are **both optional peer dependencies** (`peerDependenciesMeta.pg.optional` / `.postgres.optional`). The root barrel, `@venizia/ignis/postgres`, and the drivers barrel (`connectors/postgres/drivers/index.ts`) load **zero** `pg`/`postgres` modules - the drivers barrel exports only the neutral contract plus `resolveDatabaseDriver`. A concrete driver value-imports its own client, so reach it by its own sub-path only: `@venizia/ignis/postgres/node-postgres` or `@venizia/ignis/postgres/postgres-js`. `resolveDatabaseDriver({ client })` structurally detects which client the app built and lazily `import()`s only the matching driver. This is what keeps IGNIS from forcing a database client on a project that does not use one. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
+> `pg` and `postgres` are **both optional peer dependencies** (`peerDependenciesMeta.pg.optional` / `.postgres.optional`). The root barrel, `@venizia/ignis/postgres`, and the drivers barrel (`connectors/postgres/drivers/index.ts`) load **zero** `pg`/`postgres` modules - the drivers barrel exports only the neutral `IRelationalDriver` contract. A concrete driver value-imports its own client, so reach it by its own sub-path only: `@venizia/ignis/postgres/node-postgres` or `@venizia/ignis/postgres/postgres-js`. There is no structural client sniffing: `@datasource({ driver })` names the driver **class** directly (`NodePostgresDriver`/`PostgresJsDriver`), and the base datasource's `wireDriverFromMetadata()` instantiates that named class over `this.client` lazily, on first `getConnector()`/`beginTransaction()`. Naming a class rather than a driver-name string is what carries `pg`/`postgres` into the app's bundle - a bundler only packages a real value reference, never text, and a bare side-effect import would not survive `sideEffects: false`. This is what keeps IGNIS from forcing a database client on a project that does not use one. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
 
 > [!NOTE] `internal/` modules are not public API
 > The search connectors (`search`/`typesense`/`meilisearch`) no longer re-export their `internal/` barrels (`SearchConnectorInternal`, `TypesenseInternal`, `MeilisearchInternal`) from the connector barrel. There is no sub-path export for them either, and package `exports` blocks deep imports - so no specifier reaches them from outside the package. They are implementation detail; if you need what they do, ask for a supported API.

package/content/references/base/datasources.md

@@ -133,11 +133,11 @@ abstract class AbstractPostgresDataSource<
 | Property | Type | Visibility | Description |
 |----------|------|------------|-------------|
 | `connector` | `TRelationalConnector<Schema>` | public | Drizzle ORM instance (any Drizzle pg driver satisfies this - see the driver seam below) |
-| `driver` | `IRelationalDriver` | protected | The connection driver (`node-postgres` or `postgres-js`); built by `useDriver()` |
-| `client` | `Client` (`Pool` by default) | protected | The raw driver client `configure()` built - a `pg.Pool`, or a postgres-js `Sql`. Assigning it alone is enough: a driver is resolved from it on first use. Absent once `useDriver()` wired a driver instead |
+| `driver` | `IRelationalDriver` | protected | The connection driver (`node-postgres` or `postgres-js`); built lazily by `wireDriverFromMetadata()` from the class named in `@datasource({ driver })`, or explicitly by `useDriver()` |
+| `client` | `Client` (`Pool` by default) | protected | The raw driver client `configure()` built - a `pg.Pool`, or a postgres-js `Sql`. Assigning it alone is enough: `wireDriverFromMetadata()` instantiates the `@datasource({ driver })` class over it on first use. Absent once `useDriver()` wired a driver instead |
 
 > [!NOTE] Driver seam
-> `AbstractRelationalDataSource`/`BaseRelationalDataSource` (exported as `AbstractPostgresDataSource`/`BasePostgresDataSource`) now take a fourth generic - `<Settings, Schema, ConfigurableOptions, Client = Pool>` - so a `postgres-js` datasource can declare `Client = Sql` and keep `getClient()` honest. The protected `useDriver({ driver, schema? })` assigns `this.driver` **and** builds `this.connector` in one step. `pg` and `postgres` are both optional peer dependencies; concrete drivers live at `@venizia/ignis/postgres/node-postgres` and `@venizia/ignis/postgres/postgres-js`, and Supabase support at `@venizia/ignis/postgres/supabase`. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
+> `AbstractRelationalDataSource`/`BaseRelationalDataSource` (exported as `AbstractPostgresDataSource`/`BasePostgresDataSource`) now take a fourth generic - `<Settings, Schema, ConfigurableOptions, Client = Pool>` - so a `postgres-js` datasource can declare `Client = Sql` and keep `getClient()` honest. `@datasource({ driver })` names the driver **class** (`NodePostgresDriver` or `PostgresJsDriver`), never a string - a driver-name string cannot carry `pg`/`postgres` into the app's bundle, only a real class reference can. `configure()` only needs to assign `this.client`; the protected `wireDriverFromMetadata()` (called internally by `getConnector()`/`resolveDriver()`) instantiates the named class over it and builds `this.connector`, lazily and idempotently. The protected `useDriver({ driver, schema? })` stays available for a custom or third-party driver - it assigns `this.driver` **and** builds `this.connector` in one step, bypassing `@datasource({ driver })` entirely. `pg` and `postgres` are both optional peer dependencies; concrete drivers live at `@venizia/ignis/postgres/node-postgres` and `@venizia/ignis/postgres/postgres-js`, and Supabase support at `@venizia/ignis/postgres/supabase`. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
 
 **Additional abstract method:**
 
@@ -202,9 +202,8 @@ When you use `@repository({ model: YourModel, dataSource: YourDataSource })`, th
     -   It calls the `configure()` method on your instance
 
 3.  **Your `configure()` method runs**:
-    -   Call `this.getSchema()` to get the auto-discovered schema
-    -   Create a `Pool` instance and assign it to `this.client` (required for transaction support)
-    -   Create the Drizzle connector from that client and the schema
+    -   Create a `Pool` instance and assign it to `this.client` - that is the whole method
+    -   `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over `this.client` and build the Drizzle connector from it - your `configure()` never touches `this.connector` directly
 
 ### Example Implementations
 
@@ -215,8 +214,8 @@ Simplest approach - schema is auto-discovered from repositories:
 ```typescript
 // src/datasources/postgres.datasource.ts
 import { BasePostgresDataSource, datasource } from '@venizia/ignis';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { applicationEnvironment, int, ValueOrPromise } from '@venizia/ignis-helpers';
-import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
 interface IDataSourceConfigs {
@@ -233,10 +232,10 @@ interface IDataSourceConfigs {
  *
  * How it works:
  * 1. @repository decorator binds model to datasource
- * 2. When configure() is called, getSchema() auto-discovers all bound models
- * 3. Drizzle is initialized with the auto-discovered schema
+ * 2. getSchema() auto-discovers all bound models when the driver/connector are wired
+ * 3. Naming NodePostgresDriver in @datasource is what wires the driver and Drizzle connector
  */
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
   private readonly protocol = 'postgresql';
 
@@ -256,19 +255,15 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
   }
 
   override configure(): ValueOrPromise<void> {
-    // getSchema() auto-discovers models from @repository bindings
-    const schema = this.getSchema();
-
-    const dataSourceSchema = Object.keys(schema);
+    const schema = Object.keys(this.getSchema());
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      dataSourceSchema.length,
-      dataSourceSchema,
+      schema.length,
+      schema,
     );
 
-    // The client slot is what beginTransaction() resolves its driver from
+    // That is all - the base class wires the driver + connector from @datasource({ driver }).
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 
   override getConnectionString(): ValueOrPromise<string> {
@@ -295,12 +290,13 @@ The `PostgresDataSource.schema` will automatically include User and Configuratio
 When you need explicit control over schema (e.g., subset of models, custom ordering):
 
 ```typescript
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import {
   User, userTable, userRelations,
   Configuration, configurationTable, configurationRelations,
 } from '@/models/entities';
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
   constructor() {
     super({
@@ -323,9 +319,8 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
   }
 
   override configure(): ValueOrPromise<void> {
-    // When schema is manually provided, getSchema() returns it directly
+    // Manually-provided schema is used as-is by the connector the base class builds from this.client
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema: this.getSchema() });
   }
 
   override getConnectionString(): ValueOrPromise<string> {
@@ -335,7 +330,7 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
 ```
 
 > [!IMPORTANT]
-> Your `configure()` must leave the datasource with a way to reach the database: either assign the raw client to `this.client`, or wire a driver with `this.useDriver({ driver })`. `beginTransaction()` resolves a driver lazily from whichever you provided. With neither, it throws `No driver and no client`.
+> Your `configure()` must leave the datasource with a way to reach the database: either assign the raw client to `this.client` (paired with naming the driver class in `@datasource({ driver })`), or wire a driver directly with `this.useDriver({ driver })` for a custom or third-party driver. `getConnector()`/`beginTransaction()` resolve the driver lazily from whichever you provided. With neither, it throws `No driver and no client`.
 
 ### `@datasource` Decorator
 
@@ -343,14 +338,14 @@ The `@datasource` decorator registers datasource metadata:
 
 ```typescript
 @datasource({
-  driver: 'node-postgres',       // Required - database driver
+  driver: NodePostgresDriver,    // Required - driver CLASS (or a search engine's driver-name string)
   autoDiscovery?: true           // Optional - defaults to true
 })
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `driver` | `TDataSourceDriver` | - | Driver name - `DataSourceDrivers` defines four constants: `'node-postgres'` and `'postgres-js'` (relational), `'typesense'` and `'meilisearch'` (search); any other engine-driver string is also accepted |
+| `driver` | `TDataSourceDriverClass` | - | The driver **class** - `NodePostgresDriver` or `PostgresJsDriver` (imported from `@venizia/ignis/postgres/node-postgres` / `.../postgres-js`), never a driver-name string. A class reference is the only thing that carries `pg`/`postgres` into the app's bundle. **Omit it for a search datasource**: `extends TypesenseDataSource` already names the engine, and is what carries `typesense` into the bundle |
 | `autoDiscovery` | `boolean` | `true` | Enable/disable schema auto-discovery |
 
 ### Abstract Methods
@@ -359,7 +354,7 @@ When extending `BasePostgresDataSource`, these methods must be implemented:
 
 | Method | Return Type | Description |
 |--------|-------------|-------------|
-| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the client and Drizzle connector. Must set `this.client` (or call `this.useDriver()`) and `this.connector`. |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the client. Must set `this.client` (the base class wires the driver and Drizzle connector from `@datasource({ driver })`), or call `this.useDriver()` directly for a custom driver. |
 | `getConnectionString()` | `ValueOrPromise<string>` | Return the database connection string. |
 
 ### Helper Methods
@@ -401,6 +396,9 @@ DataSourceDrivers.MEILISEARCH    // 'meilisearch'
 DataSourceDrivers.isValid('node-postgres')  // true
 ```
 
+> [!NOTE]
+> `NODE_POSTGRES`/`POSTGRES_JS` remain valid `TDataSourceDriver` string values, but `@datasource({ driver })` on a **relational** datasource no longer accepts them - it takes the `NodePostgresDriver`/`PostgresJsDriver` class instead (see [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers)). Search connectors (`TYPESENSE`, `MEILISEARCH`) still take the driver-name string form.
+
 ## Transaction Support
 
 Only engines that declare `getCapabilities().transactions === true` implement real transactions - currently just the PostgreSQL connector. Calling `beginTransaction()` on the typesense connector throws `NotSupported` (HTTP 501).

package/content/references/configuration/environment-variables.md

@@ -157,7 +157,9 @@ APP_ENV_POSTGRES_DATABASE=my_app_prod
 ### DataSource Configuration
 
 ```typescript
-@datasource({ driver: 'node-postgres' })
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
+
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource {
   constructor() {
     super({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Interactive documentation site and MCP (Model Context Protocol) server for the Ignis Framework. Includes a VitePress-powered documentation site with guides, API references, and best practices. Ships an MCP server (CLI: ignis-docs-mcp) with 11 tools for AI assistants to search docs, browse source code, verify dependencies, and access real-time framework knowledge. Built with Mastra MCP SDK and Fuse.js fuzzy search.",
   "keywords": [
     "ai",