uql-orm 0.64.0 → 0.65.0

package/dist/migrate/migrationTarget.js

@@ -1,9 +1,9 @@
-import { isKnownMigratorDialect, isMongoQuerier, isSqlQuerier, } from '../type/index.js';
+import { isMongoQuerier, isSqlQuerier, } from '../type/index.js';
 import { withMongoQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
 import { MigrationBuilder } from './builder/migrationBuilder.js';
 import { migrationSource } from './codegen/migrationFile.js';
 import { runMongoCommand } from './generator/mongoCommand.js';
-import { createSchemaGenerator, SqlSchemaGenerator } from './schemaGenerator.js';
+import { SqlSchemaGenerator } from './schemaGenerator.js';
 import { DatabaseMigrationStorage } from './storage/databaseStorage.js';
 import { MongoMigrationStorage } from './storage/mongoStorage.js';
 const sqlSession = (querier) => ({
@@ -21,20 +21,22 @@ async function mongoSchemaGenerator(namingStrategy, defaultForeignKeyAction) {
     const { MongoSchemaGenerator } = await import('./generator/mongoSchemaGenerator.js');
     return new MongoSchemaGenerator(namingStrategy, defaultForeignKeyAction);
 }
-const sqlTarget = {
-    source: migrationSource.SqlQuerier,
-    storage: (pool, tableName) => new DatabaseMigrationStorage(pool, { tableName }),
-    generator: async (dialect, defaultForeignKeyAction) => isKnownMigratorDialect(dialect.dialectName) ? createSchemaGenerator(dialect, defaultForeignKeyAction) : undefined,
-    withSession: (pool, task) => withSqlQuerierForMigrations(pool, 'Migrator', (querier) => task(sqlSession(querier))),
-};
-const mongoTarget = {
-    source: migrationSource.MongoQuerier,
-    storage: (pool, tableName) => new MongoMigrationStorage(pool, { tableName }),
-    generator: (dialect, defaultForeignKeyAction) => mongoSchemaGenerator(dialect.namingStrategy, defaultForeignKeyAction),
-    withSession: (pool, task) => withMongoQuerierForMigrations(pool, 'Migrator', (querier) => task(mongoSession(querier))),
-};
-export function migrationTargetFor(dialect) {
-    return dialect.dialectName === 'mongodb' ? mongoTarget : sqlTarget;
+export function migrationTargetFor(pool, defaultForeignKeyAction) {
+    const { dialect } = pool;
+    if (dialect.dialectName === 'mongodb') {
+        return {
+            source: migrationSource.MongoQuerier,
+            storage: (tableName) => new MongoMigrationStorage(pool, { tableName }),
+            generator: () => mongoSchemaGenerator(dialect.namingStrategy, defaultForeignKeyAction),
+            withSession: (task) => withMongoQuerierForMigrations(pool, 'Migrator', (querier) => task(mongoSession(querier))),
+        };
+    }
+    return {
+        source: migrationSource.SqlQuerier,
+        storage: (tableName) => new DatabaseMigrationStorage(pool, { tableName }),
+        generator: async () => new SqlSchemaGenerator(dialect, defaultForeignKeyAction),
+        withSession: (task) => withSqlQuerierForMigrations(pool, 'Migrator', (querier) => task(sqlSession(querier))),
+    };
 }
 /** A builder running each operation on `querier`, as SQL or as MongoDB driver commands. */
 export async function migrationBuilderFor(querier) {

package/dist/migrate/migrator.d.ts

@@ -1,4 +1,4 @@
-import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
+import type { LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 import type { IMigrationBuilder } from './builder/types.js';
 /**
@@ -13,17 +13,13 @@ export declare class Migrator {
     set logger(value: LoggingOptions);
     private readonly _entities?;
     get entities(): Type<object>[];
-    readonly dialectName: DialectName;
     /** The generator given, or this dialect's once {@link getSchemaGenerator} has loaded it. */
     schemaGenerator?: SchemaGenerator;
-    schemaIntrospector?: SchemaIntrospector;
-    private readonly defaultForeignKeyAction?;
+    schemaIntrospector: SchemaIntrospector;
     private readonly target;
     constructor(pool: QuerierPool<Querier, MigratorDialect>, options?: MigratorOptions);
     /** The schema generator, loaded on first use: MongoDB's needs its optional peer. */
     getSchemaGenerator(): Promise<SchemaGenerator>;
-    /** `schema` reads one namespace instead of the connection's own; see {@link BaseSqlIntrospector.schema}. */
-    protected createIntrospector(schema?: string): SchemaIntrospector | undefined;
     /**
      * Get all discovered migrations from the migrations directory
      */
@@ -112,7 +108,7 @@ export declare class Migrator {
     /** The configured entities, with `entity` among them however the migrator was built. */
     private entitiesWith;
     /** The introspector for a claimed schema, which is the connection's own where none is claimed. */
-    private introspectorFor;
+    private schemaIntrospectorFor;
     /**
      * The DDL {@link sync} would run, without running it. Separate so `--dry-run` shows the real
      * statements rather than a summary of a second, differently-computed diff.

package/dist/migrate/migrator.js

@@ -25,36 +25,25 @@ export class Migrator {
     get entities() {
         return this._entities ?? getEntities();
     }
-    dialectName;
     /** The generator given, or this dialect's once {@link getSchemaGenerator} has loaded it. */
     schemaGenerator;
     schemaIntrospector;
-    defaultForeignKeyAction;
     target;
     constructor(pool, options = {}) {
         this.pool = pool;
-        this.dialectName = pool.dialect.dialectName;
-        this.target = migrationTargetFor(pool.dialect);
-        this.defaultForeignKeyAction = options.defaultForeignKeyAction;
-        this.storage = options.storage ?? this.target.storage(pool, options.tableName);
+        this.target = migrationTargetFor(pool, options.defaultForeignKeyAction);
+        this.storage = options.storage ?? this.target.storage(options.tableName);
         this.migrationsPath = options.migrationsPath ?? './migrations';
         this._logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
         this._entities = options.entities;
-        this.schemaIntrospector = this.createIntrospector();
+        this.schemaIntrospector = introspectorFor(pool);
         this.schemaGenerator = options.schemaGenerator;
     }
     /** The schema generator, loaded on first use: MongoDB's needs its optional peer. */
     async getSchemaGenerator() {
-        this.schemaGenerator ??= await this.target.generator(this.pool.dialect, this.defaultForeignKeyAction);
-        if (!this.schemaGenerator) {
-            throw new TypeError(`No schema generator for dialect '${this.dialectName}'`);
-        }
+        this.schemaGenerator ??= await this.target.generator();
         return this.schemaGenerator;
     }
-    /** `schema` reads one namespace instead of the connection's own; see {@link BaseSqlIntrospector.schema}. */
-    createIntrospector(schema) {
-        return introspectorFor(this.dialectName, this.pool, schema);
-    }
     /**
      * Get all discovered migrations from the migrations directory
      */
@@ -133,7 +122,7 @@ export class Migrator {
      */
     async runMigration(migration, direction) {
         const startTime = Date.now();
-        return this.target.withSession(this.pool, async ({ querier, transaction }) => {
+        return this.target.withSession(async ({ querier, transaction }) => {
             try {
                 this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
                 await transaction(async () => {
@@ -222,9 +211,6 @@ export class Migrator {
      */
     async getDiffs() {
         const generator = await this.getSchemaGenerator();
-        if (!this.schemaIntrospector) {
-            throw new TypeError(`No introspector for dialect '${this.dialectName}'`);
-        }
         const ast = await this.introspectClaimedSchemas();
         // Both sides built once: the database's above, the entities' here. Left to `diffSchema`, each
         // entity would rebuild the whole AST, which is quadratic in the number of entities. Absent on a
@@ -247,11 +233,7 @@ export class Migrator {
         const claimed = new Set(this.entities.map((entity) => this.pool.dialect.resolveSchema(getMeta(entity))));
         const merged = new SchemaAST();
         for (const schema of claimed) {
-            const introspector = this.introspectorFor(schema);
-            if (!introspector) {
-                continue;
-            }
-            for (const table of (await introspectSchema(introspector)).getTables()) {
+            for (const table of (await introspectSchema(this.schemaIntrospectorFor(schema))).getTables()) {
                 merged.addTable(table);
             }
         }
@@ -294,10 +276,7 @@ export class Migrator {
      */
     async planEntity(generator, entity, options) {
         const meta = getMeta(entity);
-        const introspector = this.introspectorFor(this.pool.dialect.resolveSchema(meta));
-        if (!introspector) {
-            throw new TypeError(`No introspector for '${meta.entity.name}' on '${this.dialectName}'`);
-        }
+        const introspector = this.schemaIntrospectorFor(this.pool.dialect.resolveSchema(meta));
         const tableName = generator.resolveTableName(meta);
         return (await introspector.tableExists(tableName))
             ? this.alterFromEntity(generator, entity, (await introspectSchema(introspector)).getTable(tableName), options)
@@ -319,8 +298,8 @@ export class Migrator {
         return entities.includes(entity) ? entities : [...entities, entity];
     }
     /** The introspector for a claimed schema, which is the connection's own where none is claimed. */
-    introspectorFor(schema) {
-        return schema === undefined ? this.schemaIntrospector : this.createIntrospector(schema);
+    schemaIntrospectorFor(schema) {
+        return schema === undefined ? this.schemaIntrospector : introspectorFor(this.pool, schema);
     }
     /**
      * The DDL {@link sync} would run, without running it. Separate so `--dry-run` shows the real
@@ -399,7 +378,7 @@ export class Migrator {
     }
     /** Runs the statements a generator wrote, in one transaction where the engine takes DDL in one. */
     async executeSyncStatements(statements, options) {
-        await this.target.withSession(this.pool, ({ run, transaction }) => transaction(async () => {
+        await this.target.withSession(({ run, transaction }) => transaction(async () => {
             for (const statement of statements) {
                 if (options.logging)
                     this.logger.logSchema(`Executing: ${statement}`);

package/dist/migrate/schemaGenerator.d.ts

@@ -2,7 +2,7 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, MigratorDialect, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
 import type { AnyMigrationOperation, FullColumnDefinition, IndexDefinition, TableDefinition } from './builder/types.js';
 import { type IndexDdl, type TableDdl } from './ddl/index.js';
 /**
@@ -222,5 +222,3 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
  * table of a project using a naming strategy as both missing and unexpected.
  */
 export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;
-/** The SQL schema generator for `dialect`, `undefined` on MongoDB, whose generator needs its optional peer. */
-export declare function createSchemaGenerator(dialect: MigratorDialect, defaultForeignKeyAction?: ForeignKeyAction): SqlSchemaGenerator | undefined;

package/dist/migrate/schemaGenerator.js

@@ -766,7 +766,3 @@ export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
         defaultForeignKeyAction,
     });
 }
-/** The SQL schema generator for `dialect`, `undefined` on MongoDB, whose generator needs its optional peer. */
-export function createSchemaGenerator(dialect, defaultForeignKeyAction) {
-    return dialect.dialectName === 'mongodb' ? undefined : new SqlSchemaGenerator(dialect, defaultForeignKeyAction);
-}

package/dist/mongo/mongoDialect.d.ts

@@ -15,7 +15,7 @@ type RelationLookups = {
     readonly stages: MongoAggregationPipelineEntry<Document>[];
     readonly temps: string[];
 };
-/** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
+/** Default {@link DialectFeatures} for MongoDB. */
 export declare const mongoDialectFeatures: DialectFeatures;
 export declare class MongoDialect extends AbstractDialect {
     #private;

package/dist/mongo/mongoDialect.js

@@ -6,11 +6,8 @@ import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/
 import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
 import { asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isJsonUpdateOp, isOperatorMap, isOperatorObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, parseSortByCount, someKey, targetKeyColumns, } from '../util/index.js';
-/** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
+/** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
-    explicitJsonCast: false,
-    nativeArrays: false,
-    supportsJsonb: false,
     ifNotExists: false,
     indexIfNotExists: false,
     schemas: false, // the connection picks the database, and a collection name takes no dot

package/dist/mssql/mssqlDialect.js

@@ -20,9 +20,6 @@ import { escapeSingleQuotes } from '../util/sqlLiteral.js';
  */
 export class MsSqlDialect extends MergeSqlDialect {
     featureDefaults = {
-        explicitJsonCast: false,
-        nativeArrays: false,
-        supportsJsonb: false,
         // Neither object takes an `IF NOT EXISTS`; both need a `sys` catalogue lookup around them, which
         // the generator does not emit.
         ifNotExists: false,

package/dist/pglite/pgliteQuerier.d.ts

@@ -20,10 +20,8 @@ export type PgliteDatabase = {
 /**
  * Querier for PGlite, Postgres compiled to WASM and run in this process.
  *
- * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose `internalStream`
- * hands a `pg-query-stream` object to `query()`, which PGlite's client has no equivalent of - so
- * streaming pages the rows in SQL instead. `BEGIN`/`COMMIT` are plain statements on the single
- * connection, leaving transactions to the base class.
+ * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose stream needs `pg-query-stream`,
+ * which PGlite's client cannot run. `BEGIN`/`COMMIT` are plain statements on the single connection.
  */
 export declare class PgliteQuerier extends AbstractSqlQuerier {
     readonly db: PgliteDatabase;
@@ -31,8 +29,6 @@ export declare class PgliteQuerier extends AbstractSqlQuerier {
     constructor(db: PgliteDatabase, dialect: PostgresDialect, extra?: ExtraOptions | undefined);
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
-    /** Postgres compiled to WASM is still Postgres: `DECLARE`/`FETCH` streams what the client cannot. */
-    protected internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, any>;
     /** The handle belongs to the pool, which hands out one querier per unit of work over it. */
     internalRelease(): Promise<void>;
 }

package/dist/pglite/pgliteQuerier.js

@@ -1,12 +1,9 @@
-import { streamViaCursor } from '../postgres/pgCursorStream.js';
 import { AbstractSqlQuerier } from '../querier/index.js';
 /**
  * Querier for PGlite, Postgres compiled to WASM and run in this process.
  *
- * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose `internalStream`
- * hands a `pg-query-stream` object to `query()`, which PGlite's client has no equivalent of - so
- * streaming pages the rows in SQL instead. `BEGIN`/`COMMIT` are plain statements on the single
- * connection, leaving transactions to the base class.
+ * @remarks Extends {@link AbstractSqlQuerier} rather than `PgQuerier`, whose stream needs `pg-query-stream`,
+ * which PGlite's client cannot run. `BEGIN`/`COMMIT` are plain statements on the single connection.
  */
 export class PgliteQuerier extends AbstractSqlQuerier {
     db;
@@ -26,10 +23,6 @@ export class PgliteQuerier extends AbstractSqlQuerier {
         // where the latter also counts a `SELECT`'s rows and is absent altogether from a DDL tag.
         return this.buildUpdateResult({ rows: res.rows, changes: res.affectedRows ?? 0 });
     }
-    /** Postgres compiled to WASM is still Postgres: `DECLARE`/`FETCH` streams what the client cannot. */
-    async *internalStream(query, values) {
-        yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, this.hasOpenTransaction);
-    }
     /** The handle belongs to the pool, which hands out one querier per unit of work over it. */
     async internalRelease() { }
 }

package/dist/postgres/index.d.ts

@@ -1,4 +1,3 @@
 export * from './pgQuerier.js';
 export * from './pgQuerierPool.js';
 export * from './postgresDialect.js';
-export * from './postgresWireDriverCapabilities.js';

package/dist/postgres/index.js

@@ -1,4 +1,3 @@
 export * from './pgQuerier.js';
 export * from './pgQuerierPool.js';
 export * from './postgresDialect.js';
-export * from './postgresWireDriverCapabilities.js';

package/dist/querier/abstractSharedHandleQuerierPool.d.ts

@@ -15,13 +15,10 @@ import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
  * into the transaction already open - see {@link PgliteQuerierPool}, which is why that one is worth
  * saying out loud.
  *
- * Subclasses supply only how to open the handle and how to wrap it, the way {@link AbstractPgQuerierPool}
- * takes `buildQuerier` alone. The lazy open and the close were written out once per pool before, along
- * with three partial copies of the paragraph above.
+ * Subclasses supply only how to open the handle and how to wrap it.
  *
  * @remarks Deliberately not re-exported from `querier/index.ts`, which the root entry point re-exports:
- * only the three driver entries need this, and each imports it by path, as `postgres/abstractPgQuerier.ts`
- * is imported.
+ * only the driver entries that open a single handle need this, and each imports it by path.
  */
 export declare abstract class AbstractSharedHandleQuerierPool<DB extends {
     close(): unknown;

package/dist/querier/abstractSharedHandleQuerierPool.js

@@ -13,13 +13,10 @@ import { AbstractSqlQuerierPool } from './abstractSqlQuerierPool.js';
  * into the transaction already open - see {@link PgliteQuerierPool}, which is why that one is worth
  * saying out loud.
  *
- * Subclasses supply only how to open the handle and how to wrap it, the way {@link AbstractPgQuerierPool}
- * takes `buildQuerier` alone. The lazy open and the close were written out once per pool before, along
- * with three partial copies of the paragraph above.
+ * Subclasses supply only how to open the handle and how to wrap it.
  *
  * @remarks Deliberately not re-exported from `querier/index.ts`, which the root entry point re-exports:
- * only the three driver entries need this, and each imports it by path, as `postgres/abstractPgQuerier.ts`
- * is imported.
+ * only the driver entries that open a single handle need this, and each imports it by path.
  */
 export class AbstractSharedHandleQuerierPool extends AbstractSqlQuerierPool {
     /**

package/dist/querier/abstractSqlQuerier.d.ts

@@ -80,9 +80,8 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
     private hydrateRows;
     protected internalFindManyStream<E extends object>(entity: Type<E>, q: Query<E>, opts?: QueryOptions): AsyncGenerator<Awaited<E>, void, unknown>;
     /**
-     * Internal streaming query - returns an async iterable of raw rows.
-     * Default implementation falls back to `internalAll()` then yields each row.
-     * Drivers with native cursor/streaming APIs (SQLite, Pg) should override this.
+     * A read's rows one at a time: paged through a server-side cursor where the engine has one, read whole
+     * where it has none. A driver that streams on its own overrides this.
      */
     protected internalStream<T>(query: string, values?: unknown[]): AsyncIterable<T>;
     /**

package/dist/querier/abstractSqlQuerier.js

@@ -4,6 +4,7 @@ import { getMeta, idOf, namesKey } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
 import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, idOnlyQuery, isAutoIncrement, isPagedQuery, isRecord, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
+import { streamViaCursor } from './cursorStream.js';
 import { enrichError } from './queryError.js';
 /**
  * Row indexes grouped by whether the caller supplied the key, payload order kept within each group.
@@ -240,12 +241,15 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
     }
     /**
-     * Internal streaming query - returns an async iterable of raw rows.
-     * Default implementation falls back to `internalAll()` then yields each row.
-     * Drivers with native cursor/streaming APIs (SQLite, Pg) should override this.
+     * A read's rows one at a time: paged through a server-side cursor where the engine has one, read whole
+     * where it has none. A driver that streams on its own overrides this.
      */
     async *internalStream(query, values) {
-        yield* await this.internalAll(query, values);
+        if (!this.dialect.features.serverSideCursors) {
+            yield* await this.internalAll(query, values);
+            return;
+        }
+        yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, this.hasOpenTransaction);
     }
     /**
      * Turn what a driver returned back into the types the entity declares, for every row and everything

package/dist/querier/cursorStream.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runs one statement of the cursor protocol on the querier's own connection, which holds the cursor, and
+ * not through `all()`, whose `serialize` is not re-entrant.
+ */
+type CursorExecutor<T> = (query: string, values?: unknown[]) => Promise<T[]>;
+/**
+ * Streams a Postgres-wire read through a server-side cursor. `DECLARE` needs a transaction, so one is
+ * opened on the connection itself when the caller has none, leaving the querier's state untouched.
+ * Cleanup sits in `finally`, which a consumer that stops early still reaches, and is best-effort once
+ * the read failed, so the read's error stays the one thrown.
+ */
+export declare function streamViaCursor<T>(exec: CursorExecutor<T>, query: string, values?: unknown[], inTransaction?: boolean): AsyncIterable<T>;
+export {};

package/dist/{postgres/pgCursorStream.js → querier/cursorStream.js}

@@ -4,17 +4,10 @@ const CURSOR_ALIAS = '_uql_cursor';
 const FETCH_SIZE = 100;
 let cursorSeq = 0;
 /**
- * Stream a Postgres-wire result through a server-side cursor, for a driver whose client exposes none:
- * `bun:sql` (no cursor API at all, [oven-sh/bun#17181](https://github.com/oven-sh/bun/issues/17181))
- * and PGlite. `pg` has `pg-query-stream` and keeps using it.
- *
- * `DECLARE` is only legal inside a transaction, so one is opened here when the caller has none - and
- * then committed, or rolled back if the stream failed. That `BEGIN` goes straight to the connection
- * rather than through `beginTransaction`, so the querier's own transaction state stays untouched:
- * this one is the generator's, and ends with it.
- *
- * The cleanup lives in `finally` because a consumer that stops early (`break`, a `throw` downstream)
- * ends the generator there and nowhere else, and an abandoned cursor holds its transaction open.
+ * Streams a Postgres-wire read through a server-side cursor. `DECLARE` needs a transaction, so one is
+ * opened on the connection itself when the caller has none, leaving the querier's state untouched.
+ * Cleanup sits in `finally`, which a consumer that stops early still reaches, and is best-effort once
+ * the read failed, so the read's error stays the one thrown.
  */
 export async function* streamViaCursor(exec, query, values, inTransaction = false) {
     const cursor = `${CURSOR_ALIAS}_${++cursorSeq}`;
@@ -38,8 +31,6 @@ export async function* streamViaCursor(exec, query, values, inTransaction = fals
         throw err;
     }
     finally {
-        // Best-effort once the stream has failed: an error raised here would replace the one that brought
-        // us here, which is the one worth reporting, and the rollback discards the cursor either way.
         const end = failed ? (sql) => exec(sql).catch(() => []) : exec;
         await end(`CLOSE ${cursor}`);
         if (ownsTransaction) {

package/dist/schema/canonicalType.js

@@ -338,7 +338,7 @@ export function canonicalToSql(type, dialect) {
     }
     return type.unsigned && features.supportsUnsigned ? `${sqlType} UNSIGNED` : sqlType;
 }
-/** See {@link EngineFeatures.stringSizing} for what each mode means. */
+/** See {@link DialectFeatures.stringSizing} for what each mode means. */
 function formatStringSqlType(type, base, sizing) {
     if (sizing === 'text') {
         return base;

package/dist/schema/schemaASTBuilder.js

@@ -5,7 +5,7 @@
  * - Entity metadata (decorator-based entities)
  * - Database introspection results (TableSchema[])
  */
-import { getMeta, soleIdOf } from '../entity/metadata/definition.js';
+import { foreignKeysOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { declaredIndexes, indexNameParts, renderIndexColumn } from '../util/ddlExpression.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
@@ -124,54 +124,48 @@ function tableOf(ctx, meta) {
     return ctx.ast.getTable(qualifyName(ctx.resolveTableName(meta), ctx.resolveSchema(meta)));
 }
 /**
- * Add relationships from entity relation decorators.
+ * Add a relationship for each foreign key the entity holds, whether a relation declares it or a bare
+ * `@Field({ references })` does.
  */
 function addRelationshipsFromEntity(ctx, meta) {
     const table = tableOf(ctx, meta);
     if (!table)
         return;
-    for (const [key, relation] of definedEntries(meta.relations)) {
-        const relatedMeta = getMeta(relation.entity());
+    for (const foreignKey of foreignKeysOf(meta)) {
+        const relatedMeta = getMeta(foreignKey.entity());
         const relatedTable = tableOf(ctx, relatedMeta);
         if (!relatedTable)
             continue;
-        // Only the owning side gets the FK. `mappedBy` marks the inverse side of a one-to-one, whose
-        // `references` describe how to join back (its own primary key against the owner's FK column) -
-        // reading those as a foreign key emitted a reversed constraint (`User(id) REFERENCES
-        // user_profile(creatorId)`), which SQLite rejects outright as a foreign key mismatch.
-        const ownsForeignKey = relation.cardinality === 'm1' || (relation.cardinality === '11' && !relation.mappedBy);
-        if (ownsForeignKey) {
-            // Every pair, not just the first: a composite key is one constraint over all its columns, and
-            // the engine requires the referenced columns to match a unique constraint as a whole.
-            const localColumns = [];
-            const foreignColumns = [];
-            for (const { local: localProp, foreign: foreignProp } of relation.references) {
-                const localField = meta.fields[localProp];
-                const foreignField = relatedMeta.fields[foreignProp];
-                const localColumn = localField && table.columns.get(ctx.resolveColumnName(localProp, localField));
-                const foreignColumn = foreignField && relatedTable.columns.get(ctx.resolveColumnName(foreignProp, foreignField));
-                if (!localColumn || !foreignColumn)
-                    break;
-                localColumns.push(localColumn);
-                foreignColumns.push(foreignColumn);
-            }
-            // A pair that cannot be resolved drops the whole constraint: half of one enforces a rule
-            // nobody declared, over a subset of the key.
-            if (localColumns.length !== relation.references.length)
-                continue;
-            ctx.ast.addRelationship({
-                name: derivedForeignKeyName(table.name, localColumns.map((column) => column.name)),
-                type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
-                from: { table, columns: localColumns },
-                to: { table: relatedTable, columns: foreignColumns },
-                // Falls back to the FK column's own `onDelete`, which is what makes a bare `@Field({
-                // references, onDelete })` work with no relation declared at all.
-                onDelete: relation.onDelete ?? meta.fields[relation.references[0].local]?.onDelete ?? ctx.defaultForeignKeyAction,
-                onUpdate: relation.onUpdate ?? ctx.defaultForeignKeyAction,
-                confidence: 1.0,
-                inferredFrom: 'entity_decorator',
-            });
+        // Every pair, not just the first: a composite key is one constraint over all its columns, and
+        // the engine requires the referenced columns to match a unique constraint as a whole.
+        const localColumns = [];
+        const foreignColumns = [];
+        for (const { local: localProp, foreign: foreignProp } of foreignKey.references) {
+            const localField = meta.fields[localProp];
+            const foreignField = relatedMeta.fields[foreignProp];
+            const localColumn = localField && table.columns.get(ctx.resolveColumnName(localProp, localField));
+            const foreignColumn = foreignField && relatedTable.columns.get(ctx.resolveColumnName(foreignProp, foreignField));
+            if (!localColumn || !foreignColumn)
+                break;
+            localColumns.push(localColumn);
+            foreignColumns.push(foreignColumn);
         }
+        // A pair that cannot be resolved drops the whole constraint: half of one enforces a rule
+        // nobody declared, over a subset of the key.
+        if (localColumns.length !== foreignKey.references.length)
+            continue;
+        ctx.ast.addRelationship({
+            name: derivedForeignKeyName(table.name, localColumns.map((column) => column.name)),
+            type: foreignKey.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
+            from: { table, columns: localColumns },
+            to: { table: relatedTable, columns: foreignColumns },
+            // Falls back to the FK column's own `onDelete`, which is what makes a bare `@Field({
+            // references, onDelete })` work with no relation declared at all.
+            onDelete: foreignKey.onDelete ?? meta.fields[foreignKey.references[0].local]?.onDelete ?? ctx.defaultForeignKeyAction,
+            onUpdate: foreignKey.onUpdate ?? ctx.defaultForeignKeyAction,
+            confidence: 1.0,
+            inferredFrom: 'entity_decorator',
+        });
     }
 }
 /**

package/dist/sqlite/abstractSqliteQuerier.d.ts

@@ -15,14 +15,18 @@ export type SqliteExecution = {
     readonly changes: number;
 };
 /**
- * Querier for every SQLite driver. Each supplies one hook, {@link execute}; what they share - the
- * wide-integer decode, and a RETURNING statement counted by its rows - is written once here.
+ * Querier for every SQLite driver. Each supplies {@link execute}, and {@link iterate} where it steps a
+ * statement row by row; what they share - the values bound as SQLite takes them, the wide-integer
+ * decode, and a RETURNING statement counted by its rows - is written once here.
  */
 export declare abstract class AbstractSqliteQuerier extends AbstractSqlQuerier {
     /** Runs one statement, answering its rows as the driver read them. */
-    protected abstract execute(query: string, values?: unknown[]): Promise<SqliteExecution>;
+    protected abstract execute(query: string, values: SqliteBindValue[]): Promise<SqliteExecution>;
+    /** A statement's rows as the driver answers them: read whole, unless it steps them one at a time. */
+    protected iterate(query: string, values: SqliteBindValue[]): Promise<Iterable<RawRow> | AsyncIterable<RawRow>>;
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
+    internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
     /**
      * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
      * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.

package/dist/sqlite/abstractSqliteQuerier.js

@@ -1,22 +1,36 @@
 import { AbstractSqlQuerier } from '../querier/index.js';
 import { decodeBigInts } from '../util/wideNumber.js';
 /**
- * Querier for every SQLite driver. Each supplies one hook, {@link execute}; what they share - the
- * wide-integer decode, and a RETURNING statement counted by its rows - is written once here.
+ * Querier for every SQLite driver. Each supplies {@link execute}, and {@link iterate} where it steps a
+ * statement row by row; what they share - the values bound as SQLite takes them, the wide-integer
+ * decode, and a RETURNING statement counted by its rows - is written once here.
  */
 export class AbstractSqliteQuerier extends AbstractSqlQuerier {
+    /** A statement's rows as the driver answers them: read whole, unless it steps them one at a time. */
+    async iterate(query, values) {
+        return (await this.execute(query, values)).rows;
+    }
     async internalAll(query, values) {
-        const { rows } = await this.execute(query, values);
+        const { rows } = await this.execute(query, toBindValues(values));
         return rows.map(decodeBigInts);
     }
     async internalRun(query, values) {
-        const { rows, changes } = await this.execute(query, values);
+        const { rows, changes } = await this.execute(query, toBindValues(values));
         // A driver's own count is unreliable for a RETURNING statement (Hrana answers 0), so its rows answer.
         return this.buildUpdateResult({ rows: rows.map(decodeBigInts), changes: rows.length || changes });
     }
+    async *internalStream(query, values) {
+        for await (const row of await this.iterate(query, toBindValues(values))) {
+            yield decodeBigInts(row);
+        }
+    }
     /**
      * SQLite drivers hold a single shared handle rather than a connection from a pool, so releasing
      * a querier returns nothing at all. Drivers owning a closable per-querier connection override this.
      */
     async internalRelease() { }
 }
+/** The compiler hands values over untyped, which the dialect has already normalized to what SQLite binds. */
+function toBindValues(values = []) {
+    return values;
+}

package/dist/sqlite/hranaQuerier.d.ts

@@ -44,7 +44,7 @@ export declare class HranaQuerier extends AbstractSqliteQuerier {
     private readonly closeClientOnRelease;
     constructor(client: HranaClient, dialect: SqliteDialect, extra?: ExtraOptions | undefined, connection?: HranaQuerierConnectionOptions);
     /** Runs on the open transaction's handle when there is one. */
-    protected execute(query: string, values?: unknown[]): Promise<{
+    protected execute(query: string, values: SqliteBindValue[]): Promise<{
         rows: RawRow[];
         changes: number;
     }>;