uql-orm 0.69.0 → 0.71.0

package/dist/querier/abstractQuerier.js

@@ -1,5 +1,5 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
-import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, isPagedQuery, hasKeys, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
 import { enrichError } from './queryError.js';
 /**
  * Refuses a nullish id, which would reduce to no filter at all, and a composite id missing a column,
@@ -27,6 +27,17 @@ function assertIdValue(entity, id) {
 function soleParentColumn(relOpts) {
     return parentJoins(relOpts, 1)[0].joined;
 }
+/**
+ * A bulk write names the rows it changes: a `$where`, or a `$limit` capping how many it reaches. The
+ * caller's own clauses are what count - a filter the entity adds, soft delete's, would otherwise make
+ * every table look narrowed, which is the case this exists to catch.
+ */
+function assertNamesRows(entity, method, q, opts) {
+    if (opts?.unfiltered || hasKeys(q?.$where) || q?.$limit !== undefined) {
+        return;
+    }
+    throw new TypeError(`'${method}' over '${entity.name}' names no rows, so it would address every one: pass '{ unfiltered: true }' to mean it`);
+}
 /**
  * The id each written row is named by, in payload order. Read off the rows as written, so a key the
  * database generated or the ORM filled is there, and a composite is named by every column of it.
@@ -183,6 +194,7 @@ export class AbstractQuerier {
     }
     /** Settles the rows first where the update cascades, so a payload changing what `$where` reads still names them. */
     async updateMany(entity, q, payload, opts) {
+        assertNamesRows(entity, 'updateMany', q, opts);
         const meta = getMeta(entity);
         return this.hooked(entity, 'Update', [payload], async ([row]) => {
             fillOnFields(meta, [row], 'onUpdate');
@@ -206,9 +218,13 @@ export class AbstractQuerier {
         const writes = filterFieldKeys(getMeta(entity), row, 'onUpdate').length > 0;
         return writes ? this.internalUpdateMany(entity, q, row, opts) : unwritten;
     }
-    /** Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or delete. */
-    settlesWrite(_entity, q) {
-        return isPagedQuery(q);
+    /**
+     * Whether a write has to name the rows `q` matches by their ids: no engine pages or orders an update or
+     * delete, and one without {@link DialectFeatures.correlatedWrites} cannot read a relation in its filter.
+     */
+    settlesWrite(entity, q) {
+        const { dialect } = this;
+        return isPagedQuery(q) || (!dialect.features.correlatedWrites && dialect.constrainsRelations(entity, q.$where));
     }
     /** The ids `q` matches, in its own order and page. */
     async settleIds(entity, q, opts) {
@@ -254,6 +270,7 @@ export class AbstractQuerier {
     }
     async deleteMany(entityOrQuery, qOrOpts, maybeOpts) {
         const [entity, q, opts] = this.resolveEntityQuery(entityOrQuery, qOrOpts, maybeOpts);
+        assertNamesRows(entity, 'deleteMany', q, opts);
         const meta = getMeta(entity);
         const cascades = cascadesOnDelete(meta);
         const watched = this.hasHook(entity, 'beforeDelete') || this.hasHook(entity, 'afterDelete');
@@ -350,8 +367,7 @@ export class AbstractQuerier {
             const relOpts = relationOf(meta, relKey);
             const relEntity = relOpts.entity();
             const target = relOpts.through ? relOpts.through() : relEntity;
-            const where = childrenOf(parentJoins(relOpts, meta.ids.length), ids);
-            await this.deleteMany(target, { $where: where }, opts);
+            await this.deleteMany(target, { $where: childrenOf(parentJoins(relOpts, meta.ids.length), ids) }, opts);
         }
     }
     /**
@@ -480,8 +496,12 @@ export class AbstractQuerier {
      * the write filled in - a generated key, an `onInsert` value - without it landing on the caller's.
      */
     async hooked(entity, event, payloads, write) {
-        await this.emitHook(entity, `before${event}`, payloads);
-        const rows = clone(payloads);
+        // The one place a caller's write becomes the row the rest of the library handles. They are the
+        // same object: a write is the entity's data without the keys the database fills, which
+        // TypeScript cannot relate across an entity it has not resolved.
+        const asRows = payloads;
+        await this.emitHook(entity, `before${event}`, asRows);
+        const rows = clone(asRows);
         const result = await write(rows);
         await this.emitHook(entity, `after${event}`, rows);
         return result;

package/dist/querier/abstractQuerierPool.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractDialect } from '../dialect/index.js';
-import type { EntityData, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdatePayload, WrittenId } from '../type/index.js';
+import type { EntityWrite, EntityId, ExtraOptions, FieldKey, PoolRunOptions, Querier, QuerierPool, QueryAggMap, QueryAggregate, QueryAggregateResult, QueryConflictPaths, QueryFilter, QueryFindResult, QueryGroupMap, QueryOneProjected, QueryOptions, QueryPage, QueryProjected, QuerySearch, QueryUpsertOneResult, QueryUpsertManyResult, RelationKey, TransactionOptions, Type, UpdateWrite, WrittenId } from '../type/index.js';
 /**
  * Base pool: dialect id and behavior come only from the `dialect` instance (see {@link QuerierPool}).
  */
@@ -37,14 +37,14 @@ export declare abstract class AbstractQuerierPool<Q extends Querier, D extends A
     exists<E extends object>(entity: Type<E>, q?: QueryFilter<E>, opts?: QueryOptions): Promise<boolean>;
     aggregate<E extends object, const G extends QueryGroupMap<E>, const A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     estimatedCount<E extends object>(entity: Type<E>): Promise<number>;
-    insertOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
-    insertMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
-    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): Promise<number>;
-    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpsertOneResult<E>>;
-    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpsertManyResult<E>>;
-    saveOne<E extends object>(entity: Type<E>, payload: EntityData<E>): Promise<WrittenId<E> | undefined>;
-    saveMany<E extends object>(entity: Type<E>, payload: EntityData<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    insertOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
+    insertMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
+    updateMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
+    upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
+    upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
+    saveOne<E extends object>(entity: Type<E>, payload: EntityWrite<E>): Promise<WrittenId<E> | undefined>;
+    saveMany<E extends object>(entity: Type<E>, payload: EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
     deleteMany<E extends object>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     restoreOneById<E extends object>(entity: Type<E>, id: EntityId<E>): Promise<number>;

package/dist/querier/abstractSqlQuerier.d.ts

@@ -80,7 +80,7 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      */
     private hydrateFields;
     /**
-     * Runs a statement whose one row carries a {@link COUNT_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
+     * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
      * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
      * a catalog that does not know the table answers with no row, which is nothing counted.
      */

package/dist/querier/abstractSqlQuerier.js

@@ -1,4 +1,4 @@
-import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
+import { AGGREGATE_VALUE_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta, namesKey } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
@@ -290,13 +290,13 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
     }
     /**
-     * Runs a statement whose one row carries a {@link COUNT_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
+     * Runs a statement whose one row carries a {@link AGGREGATE_VALUE_ALIAS} column. `Number` because `COUNT(*)` is BIGINT and
      * a caller supplying their own `types` replaces the decoding the pools do at the wire; `?? 0` because
      * a catalog that does not know the table answers with no row, which is nothing counted.
      */
     async runCount(build) {
         const [row] = await this.query(build);
-        return Number(row?.[COUNT_ALIAS] ?? 0);
+        return Number(row?.[AGGREGATE_VALUE_ALIAS] ?? 0);
     }
     async internalCount(entity, q, opts) {
         return this.runCount((ctx) => this.dialect.count(ctx, entity, q, opts));

package/dist/schema/canonicalType.js

@@ -80,6 +80,7 @@ const SQL_TO_CANONICAL = {
     image: { category: 'blob', size: 'big' },
     // === Vector (for AI/embeddings) ===
     vector: { category: 'vector' },
+    f32_blob: { category: 'vector' },
     halfvec: { category: 'halfvec' },
     sparsevec: { category: 'sparsevec' },
 };
@@ -204,8 +205,8 @@ const ENGINE_TYPES = {
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
     },
-    // SQLite uses affinity, so no size variants.
-    sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'TEXT') },
+    // SQLite uses affinity, so no size variants. `F32_BLOB` is libSQL's vector type; elsewhere just a name of BLOB affinity.
+    sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'F32_BLOB') },
     // 2025 and up; below that the server refuses the type rather than storing it as text.
     mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES },
     mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
@@ -238,7 +239,7 @@ export function sqlToCanonical(sqlType) {
     const unsigned = normalized.includes('unsigned');
     const withoutUnsigned = normalized.replace(/\s*unsigned\s*/i, ' ').trim();
     // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"]
-    const match = withoutUnsigned.match(/^([a-z][a-z0-9 ]*?)(?:\(([^)]+)\))?$/);
+    const match = withoutUnsigned.match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
     const base = match ? SQL_TO_CANONICAL[match[1]] : undefined;
     if (!match || !base) {
         return { category: 'string', raw: sqlType };
@@ -332,8 +333,13 @@ export function canonicalToTypeScript(type) {
  * the engine settles an unstated bound. Migrations and drift both compare through it.
  */
 export function engineType(dialect) {
-    return (type) => sqlToCanonical(canonicalToSql(type, dialect));
+    return (type) => {
+        const stored = sqlToCanonical(canonicalToSql(type, dialect));
+        // SQLite keeps a vector in any column, so one created as `TEXT` before vectors were blobs stays as it is.
+        return dialect.dialectName === 'sqlite' && isVectorCategory(stored.category) ? SQLITE_TEXT : stored;
+    };
 }
+const SQLITE_TEXT = { category: 'string', size: 'small' };
 /**
  * Convert UQL FieldOptions to a canonical type.
  */

package/dist/schema/indexDifferences.d.ts

@@ -1,6 +1,9 @@
 import type { IndexNode } from './types.js';
-/** What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits. */
-export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include';
+/**
+ * What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits.
+ * `vector` is whether it is a vector index at all, for an engine with one vector index whatever type declared it.
+ */
+export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include' | 'vector';
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.

package/dist/schema/indexDifferences.js

@@ -1,3 +1,4 @@
+import { isVectorIndexType } from '../type/vector.js';
 /**
  * Whether the table has this index already, by shape rather than name, uniqueness included. An index
  * over an expression, whose text the engine reprints, falls back to its name.
@@ -45,6 +46,10 @@ export function describeIndexDifferences(source, target, facets) {
     if (facets.has('accessMethod') && (source.type ?? 'btree') !== (target.type ?? 'btree')) {
         differences.push(`type: ${target.type ?? 'btree'} -> ${source.type ?? 'btree'}`);
     }
+    if (facets.has('vector') && isVectorIndexType(source.type) !== isVectorIndexType(target.type)) {
+        const [expected, actual] = [source, target].map((index) => (isVectorIndexType(index.type) ? 'yes' : 'no'));
+        differences.push(`vector index: ${actual} -> ${expected}`);
+    }
     if (facets.has('include')) {
         // Order carries no meaning in an `INCLUDE` list, so it is compared as a set.
         const [sourceInclude, targetInclude] = [source.include ?? [], target.include ?? []].map((columns) => [...columns].sort().join(', '));

package/dist/schema/schemaASTBuilder.js

@@ -1,5 +1,5 @@
 import { fieldOf, foreignKeysOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
-import { declaredIndexes, indexNameParts, renderIndexColumn } from '../util/ddlExpression.util.js';
+import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../util/ddlExpression.util.js';
 import { isInlinedExpression } from '../util/field.util.js';
 import { isSoleIdField } from '../util/field.util.js';
 import { isAutoIncrement } from '../util/field.util.js';
@@ -198,7 +198,7 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
     });
     if (!resolved.length)
         return;
-    const name = idxMeta.name ?? derivedIndexName(table.name, indexNameParts(resolved));
+    const name = declaredIndexName(idxMeta.name, table.name, resolved);
     ctx.ast.addIndex({
         name,
         table,
@@ -211,5 +211,6 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
         m: idxMeta.m,
         efConstruction: idxMeta.efConstruction,
         lists: idxMeta.lists,
+        config: idxMeta.config,
     });
 }

package/dist/sqlite/localSqliteQuerierPool.d.ts

@@ -1,7 +1,6 @@
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import type { ExtraOptions } from '../type/index.js';
-import { SqliteDialect } from './sqliteDialect.js';
-import { type SqlitePreparedStatement, SqliteQuerier } from './sqliteQuerier.js';
+import type { SqliteDialect } from './sqliteDialect.js';
+import { type SqliteDatabase, type SqlitePreparedStatement, SqliteQuerier } from './sqliteQuerier.js';
 /** What every local SQLite pool accepts on top of its driver's own options. */
 export type LocalSqlitePoolOptions = {
     /**
@@ -27,12 +26,12 @@ export type LocalSqliteDatabase = {
 export declare function adaptSqlite<S extends Omit<SqlitePreparedStatement, 'reader'>>(db: Omit<LocalSqliteDatabase, 'prepare'> & {
     prepare(sql: string): S;
 }, reads: (stmt: S) => boolean): LocalSqliteDatabase;
-/** A pool for a SQLite file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
-export declare abstract class AbstractLocalSqliteQuerierPool<O extends LocalSqlitePoolOptions> extends AbstractSharedHandleQuerierPool<LocalSqliteDatabase, SqliteQuerier, SqliteDialect> {
-    readonly opts?: O | undefined;
-    constructor(opts?: O | undefined, extra?: ExtraOptions);
-    /** Opens the driver's database, and nothing more: the caller configures it. */
-    protected abstract createDb(): Promise<LocalSqliteDatabase>;
-    protected openDb(): Promise<LocalSqliteDatabase>;
-    protected buildQuerier(db: LocalSqliteDatabase): SqliteQuerier;
+/** `db` with each loadable extension installed, which `node:sqlite` refuses unless opened to allow them. */
+export declare function loadExtensions(db: LocalSqliteDatabase, extensions?: readonly string[]): LocalSqliteDatabase;
+/** A pool for a database file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
+export declare abstract class AbstractLocalSqliteQuerierPool<DB extends SqliteDatabase, D extends SqliteDialect> extends AbstractSharedHandleQuerierPool<DB, SqliteQuerier, D> {
+    /** Opens the driver's database, reading integers as `bigint`, which the querier decodes exactly past 2^53. */
+    protected abstract createDb(): Promise<DB>;
+    protected openDb(): Promise<DB>;
+    protected buildQuerier(db: DB): SqliteQuerier;
 }

package/dist/sqlite/localSqliteQuerierPool.js

@@ -1,6 +1,4 @@
-import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import { SqliteDialect } from './sqliteDialect.js';
 import { applySqlitePragmas } from './sqlitePragmas.js';
 import { SqliteQuerier } from './sqliteQuerier.js';
 /**
@@ -22,19 +20,18 @@ export function adaptSqlite(db, reads) {
         close: () => db.close(),
     };
 }
-/** A pool for a SQLite file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
-export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {
-    opts;
-    constructor(opts, extra) {
-        super(new SqliteDialect(dialectOptionsFrom(extra)), extra);
-        this.opts = opts;
+/** `db` with each loadable extension installed, which `node:sqlite` refuses unless opened to allow them. */
+export function loadExtensions(db, extensions = []) {
+    for (const extension of extensions) {
+        db.loadExtension(extension);
     }
+    return db;
+}
+/** A pool for a database file opened in this process, configured the same way whichever driver's {@link createDb} opens it. */
+export class AbstractLocalSqliteQuerierPool extends AbstractSharedHandleQuerierPool {
     async openDb() {
         const db = await this.createDb();
         await applySqlitePragmas(db);
-        for (const extension of this.opts?.extensions ?? []) {
-            db.loadExtension(extension);
-        }
         return db;
     }
     buildQuerier(db) {

package/dist/sqlite/nodeSqliteQuerierPool.d.ts

@@ -1,5 +1,6 @@
 import type { ExtraOptions } from '../type/index.js';
 import { AbstractLocalSqliteQuerierPool, type LocalSqliteDatabase, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /**
  * The `DatabaseSync` options worth surfacing, plus the loadable extensions to install. Declared here
  * rather than imported from `node:sqlite` so this module needs no ambient Node types; unknown keys
@@ -15,8 +16,9 @@ export type NodeSqlitePoolOptions = LocalSqlitePoolOptions & {
  * A pool over Node's built-in `node:sqlite`, needing no dependency at all. {@link Sqlite3QuerierPool} is the
  * faster choice for read-heavy work, and the one on Bun.
  */
-export declare class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool<NodeSqlitePoolOptions> {
+export declare class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool<LocalSqliteDatabase, SqliteDialect> {
     readonly filename: string;
-    constructor(filename?: string, opts?: NodeSqlitePoolOptions, extra?: ExtraOptions);
+    readonly opts?: NodeSqlitePoolOptions | undefined;
+    constructor(filename?: string, opts?: NodeSqlitePoolOptions | undefined, extra?: ExtraOptions);
     protected createDb(): Promise<LocalSqliteDatabase>;
 }

package/dist/sqlite/nodeSqliteQuerierPool.js

@@ -1,24 +1,27 @@
-import { AbstractLocalSqliteQuerierPool, adaptSqlite, } from './localSqliteQuerierPool.js';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
+import { AbstractLocalSqliteQuerierPool, adaptSqlite, loadExtensions, } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /**
  * A pool over Node's built-in `node:sqlite`, needing no dependency at all. {@link Sqlite3QuerierPool} is the
  * faster choice for read-heavy work, and the one on Bun.
  */
 export class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool {
     filename;
+    opts;
     constructor(filename = ':memory:', opts, extra) {
-        super(opts, extra);
+        super(new SqliteDialect(dialectOptionsFrom(extra)), extra);
         this.filename = filename;
+        this.opts = opts;
     }
     async createDb() {
         const { DatabaseSync } = await import('node:sqlite');
         const { extensions, ...driverOpts } = this.opts ?? {};
         const nodeDb = new DatabaseSync(this.filename, {
             ...driverOpts,
-            // Integers as `bigint`, which the querier decodes exactly past 2^53.
             readBigInts: true,
             // `node:sqlite` refuses `loadExtension` unless the database was opened with this on.
             ...(extensions?.length ? { allowExtension: true } : undefined),
         });
-        return adaptSqlite(nodeDb, (stmt) => stmt.columns().length > 0);
+        return loadExtensions(adaptSqlite(nodeDb, (stmt) => stmt.columns().length > 0), extensions);
     }
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,6 +1,6 @@
 import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
-import type { EntityMeta, FieldOptions, QueryContext, QueryPager, QueryTextSearchOptions, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryPager, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type Type, type VectorDistance, type VectorMetric } from '../type/index.js';
 /** What SQLite and the engines derived from it have. */
 export declare const SQLITE_FEATURES: SqlDialectFeatures;
 export declare class SqliteDialect extends AbstractSqlDialect {
@@ -24,6 +24,12 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      * their own vector functions instead, so `LibsqlDialect` overrides this.
      */
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /**
+     * A read ranked by the metric its field's vector index measures, and paged, narrowed to the rowids of
+     * that index's nearest rows, which libSQL's `vector_top_k` answers: `$candidates` of them, else as many
+     * as the page reaches. Their exact distance still orders them. Unchanged on an engine with no such index.
+     */
+    protected rankedWhere<E>(meta: EntityMeta<E>, q: Query<E>, prefix: string | undefined): QueryWhere<E> | undefined;
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default
      * when declared, else `NULL` (which is also how SQLite auto-generates INTEGER PRIMARY KEYs).
@@ -51,7 +57,9 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected readonly carriedFields: {
         numeric: (expr: string, field: FieldOptions) => string;
         blob: (expr: string) => string;
+        vector: (expr: string) => string;
     };
+    private bytesAsText;
     /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
     protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     /**

package/dist/sqlite/sqliteDialect.js

@@ -1,7 +1,10 @@
 import { AbstractSqlDialect, } from '../dialect/abstractSqlDialect.js';
 import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
-import { textSearchFields } from '../util/dialect.util.js';
+import { QueryRaw, } from '../type/index.js';
+import { indexDistance, isVectorIndexType } from '../type/vector.js';
+import { declaredIndexName } from '../util/ddlExpression.util.js';
+import { findVectorIndex, findVectorSort, textSearchFields, vectorCandidates } from '../util/dialect.util.js';
 import { columnFamily, isIntegerColumn } from '../util/field.util.js';
 /** What SQLite and the engines derived from it have. */
 export const SQLITE_FEATURES = {
@@ -14,11 +17,13 @@ export const SQLITE_FEATURES = {
     generatedColumnAdd: false, // accepted in a CREATE TABLE, rejected in an ALTER
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
-    vectorSupportsLength: false,
+    vectorSupportsLength: true,
+    vectorBytes: true,
     supportsTimestamptz: false,
     stringSizing: 'text',
     supportsUnsigned: false,
     serverSideCursors: false,
+    correlatedWrites: true,
     rowLocks: false,
     rowLockWithWindow: true,
     rowLockOf: true,
@@ -54,6 +59,37 @@ export class SqliteDialect extends AbstractSqlDialect {
         ['l2', { fn: 'vec_distance_L2' }],
         ['l1', { fn: 'vec_distance_L1' }],
     ]);
+    /**
+     * A read ranked by the metric its field's vector index measures, and paged, narrowed to the rowids of
+     * that index's nearest rows, which libSQL's `vector_top_k` answers: `$candidates` of them, else as many
+     * as the page reaches. Their exact distance still orders them. Unchanged on an engine with no such index.
+     */
+    rankedWhere(meta, q, prefix) {
+        const ranked = findVectorSort(q.$sort);
+        const k = vectorCandidates(q) ?? (q.$limit === undefined ? undefined : (q.$skip ?? 0) + q.$limit);
+        const index = ranked && findVectorIndex(meta, ranked.key);
+        if (!ranked || !index || !isVectorIndexType(index.type) || k === undefined) {
+            return q.$where;
+        }
+        const { colName, distance, field } = this.resolveVectorDistance(meta, ranked.key, ranked.search);
+        if (indexDistance(index) !== distance || !this.vectorMetrics.get(distance)?.index) {
+            return q.$where;
+        }
+        const name = declaredIndexName(index.name, this.resolveTableName(meta), [{ column: colName }]);
+        const table = this.escapeId(prefix ?? this.resolveTableAlias(meta), true, true);
+        const nearest = new QueryRaw(({ ctx }) => {
+            ctx.append(`${table}rowid IN (SELECT id FROM vector_top_k(`);
+            ctx.addValue(name);
+            ctx.append(', ');
+            this.appendVectorValue(ctx, ranked.search.$vector, field);
+            ctx.append(', ');
+            ctx.addValue(k);
+            ctx.append('))');
+        });
+        const where = {};
+        where.$and = q.$where ? [q.$where, nearest] : [nearest];
+        return where;
+    }
     /**
      * SQLite does not support the `DEFAULT` keyword inside `VALUES`. Inline the metadata default
      * when declared, else `NULL` (which is also how SQLite auto-generates INTEGER PRIMARY KEYs).
@@ -108,8 +144,12 @@ export class SqliteDialect extends AbstractSqlDialect {
      */
     carriedFields = {
         numeric: (expr, field) => (isIntegerColumn(field) ? `CAST(${expr} AS TEXT)` : expr),
-        blob: (expr) => `${this.escape(BYTES_PREFIX)} || hex(${expr})`,
+        blob: (expr) => this.bytesAsText(expr),
+        vector: (expr) => `CASE WHEN typeof(${expr}) = 'blob' THEN ${this.bytesAsText(expr)} ELSE ${expr} END`,
     };
+    bytesAsText(expr) {
+        return `${this.escape(BYTES_PREFIX)} || hex(${expr})`;
+    }
     /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
     hydrateKind(field) {
         return columnFamily(field?.type) === 'date' ? undefined : super.hydrateKind(field);

package/dist/sqlite/sqliteQuerierPool.d.ts

@@ -1,19 +1,20 @@
 import type { Options } from 'better-sqlite3';
 import type { ExtraOptions } from '../type/index.js';
 import { AbstractLocalSqliteQuerierPool, type LocalSqliteDatabase, type LocalSqlitePoolOptions } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /** Driver options, plus the loadable extensions to install on the connection. */
 export type Sqlite3PoolOptions = Options & LocalSqlitePoolOptions;
 /**
  * Pool for `better-sqlite3`, or `bun:sqlite` when running under Bun - the same file, through whichever
  * driver the runtime provides.
  */
-export declare class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool<Sqlite3PoolOptions> {
+export declare class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool<LocalSqliteDatabase, SqliteDialect> {
     readonly filename: string | Buffer;
-    constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions, extra?: ExtraOptions);
+    readonly opts?: Sqlite3PoolOptions | undefined;
+    constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions | undefined, extra?: ExtraOptions);
     /**
-     * Both drivers read integers as `bigint`, which the querier decodes exactly past 2^53. `bun:sqlite`
-     * rejects option keys it does not know, so `extensions` is stripped out, and opens only a path, so a
-     * serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
+     * `bun:sqlite` rejects option keys it does not know, so `extensions` is stripped out, and opens only a
+     * path, so a serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
      */
     protected createDb(): Promise<LocalSqliteDatabase>;
 }

package/dist/sqlite/sqliteQuerierPool.js

@@ -1,18 +1,21 @@
-import { AbstractLocalSqliteQuerierPool, adaptSqlite, } from './localSqliteQuerierPool.js';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
+import { AbstractLocalSqliteQuerierPool, adaptSqlite, loadExtensions, } from './localSqliteQuerierPool.js';
+import { SqliteDialect } from './sqliteDialect.js';
 /**
  * Pool for `better-sqlite3`, or `bun:sqlite` when running under Bun - the same file, through whichever
  * driver the runtime provides.
  */
 export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
     filename;
+    opts;
     constructor(filename = ':memory:', opts, extra) {
-        super(opts, extra);
+        super(new SqliteDialect(dialectOptionsFrom(extra)), extra);
         this.filename = filename;
+        this.opts = opts;
     }
     /**
-     * Both drivers read integers as `bigint`, which the querier decodes exactly past 2^53. `bun:sqlite`
-     * rejects option keys it does not know, so `extensions` is stripped out, and opens only a path, so a
-     * serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
+     * `bun:sqlite` rejects option keys it does not know, so `extensions` is stripped out, and opens only a
+     * path, so a serialized database - which better-sqlite3 takes as its filename - is deserialized there instead.
      */
     async createDb() {
         const { extensions, ...driverOpts } = this.opts ?? {};
@@ -22,9 +25,9 @@ export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
             const bunDb = typeof this.filename === 'string'
                 ? new Database(this.filename, bunOpts)
                 : Database.deserialize(this.filename, bunOpts);
-            return adaptSqlite(bunDb, (stmt) => stmt.columnNames.length > 0);
+            return loadExtensions(adaptSqlite(bunDb, (stmt) => stmt.columnNames.length > 0), extensions);
         }
         const { default: BetterSqlite3 } = await import('better-sqlite3');
-        return new BetterSqlite3(this.filename, driverOpts).defaultSafeIntegers(true);
+        return loadExtensions(new BetterSqlite3(this.filename, driverOpts).defaultSafeIntegers(true), extensions);
     }
 }

package/dist/turso/tursoDialect.d.ts

@@ -5,6 +5,6 @@ import type { SqlDialectFeatures } from '../type/index.js';
  * `ORDER BY` inside an aggregate, which its Rust engine lacks. Imports no driver.
  */
 export declare class TursoDialect extends LibsqlDialect {
-    /** The Rust engine takes no `ORDER BY` inside an aggregate. */
+    /** The Rust engine takes no `ORDER BY` inside an aggregate, nor a subquery reading the table a write changes. */
     readonly features: SqlDialectFeatures;
 }

package/dist/turso/tursoDialect.js

@@ -5,6 +5,10 @@ import { SQLITE_FEATURES } from '../sqlite/sqliteDialect.js';
  * `ORDER BY` inside an aggregate, which its Rust engine lacks. Imports no driver.
  */
 export class TursoDialect extends LibsqlDialect {
-    /** The Rust engine takes no `ORDER BY` inside an aggregate. */
-    features = { ...SQLITE_FEATURES, orderedJsonAggregates: false };
+    /** The Rust engine takes no `ORDER BY` inside an aggregate, nor a subquery reading the table a write changes. */
+    features = {
+        ...SQLITE_FEATURES,
+        orderedJsonAggregates: false,
+        correlatedWrites: false,
+    };
 }

package/dist/turso/tursoLocalDialect.d.ts

@@ -2,7 +2,7 @@ import type { VectorDistance, VectorMetric } from '../type/index.js';
 import { TursoDialect } from './tursoDialect.js';
 /**
  * SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
- * dot-product distance to libSQL's cosine and L2, and caps no function call.
+ * dot-product distance to libSQL's cosine and L2, caps no function call, and has no vector index.
  */
 export declare class TursoLocalDialect extends TursoDialect {
     readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;

package/dist/turso/tursoLocalDialect.js

@@ -1,7 +1,7 @@
 import { TursoDialect } from './tursoDialect.js';
 /**
  * SQLite Dialect specialization for the embedded Turso engine, the Rust engine alone: it adds a
- * dot-product distance to libSQL's cosine and L2, and caps no function call.
+ * dot-product distance to libSQL's cosine and L2, caps no function call, and has no vector index.
  */
 export class TursoLocalDialect extends TursoDialect {
     vectorMetrics = new Map([

package/dist/turso/tursoLocalQuerierPool.d.ts

@@ -1,15 +1,14 @@
 import type { connect } from '@tursodatabase/database';
-import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
-import { type SqliteDatabase, SqliteQuerier } from '../sqlite/sqliteQuerier.js';
+import { AbstractLocalSqliteQuerierPool } from '../sqlite/localSqliteQuerierPool.js';
+import type { SqliteDatabase } from '../sqlite/sqliteQuerier.js';
 import type { ExtraOptions } from '../type/index.js';
 import { TursoLocalDialect } from './tursoLocalDialect.js';
 /** The engine's own options: `readonly`, `timeout`, `encryption`, `experimental` and the rest. */
 export type TursoLocalOptions = NonNullable<Parameters<typeof connect>[1]>;
 /** A pool for the embedded Turso engine, on `uql-orm/turso/local` so its native binaries stay out of edge bundles. */
-export declare class TursoLocalQuerierPool extends AbstractSharedHandleQuerierPool<SqliteDatabase, SqliteQuerier, TursoLocalDialect> {
+export declare class TursoLocalQuerierPool extends AbstractLocalSqliteQuerierPool<SqliteDatabase, TursoLocalDialect> {
     readonly filename: string;
     readonly opts?: TursoLocalOptions | undefined;
     constructor(filename?: string, opts?: TursoLocalOptions | undefined, extra?: ExtraOptions);
-    protected openDb(): Promise<SqliteDatabase>;
-    protected buildQuerier(db: SqliteDatabase): SqliteQuerier;
+    protected createDb(): Promise<SqliteDatabase>;
 }