uql-orm 0.24.6 → 0.25.0

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -4,9 +4,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * Works with both MySQL and MariaDB as they share the same information_schema structure.
  */
 export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT TABLE_NAME as table_name
@@ -95,12 +92,6 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ORDER BY ORDINAL_POSITION
     `;
     }
-    // ============================================================================
-    // Internal Types
-    // ============================================================================
-    mapTableNameRow(row) {
-        return row.table_name;
-    }
     async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.column_name,

package/dist/migrate/introspection/postgresIntrospector.d.ts

@@ -11,9 +11,6 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
     protected getIndexesQuery(_tableName: string): string;
     protected getForeignKeysQuery(_tableName: string): string;
     protected getPrimaryKeyQuery(_tableName: string): string;
-    protected mapTableNameRow(row: {
-        table_name: string;
-    }): string;
     protected mapColumnsResult(_read: TableRowReader, _tableName: string, results: PostgresColumnRow[]): Promise<ColumnSchema[]>;
     protected mapIndexesResult(_read: TableRowReader, _tableName: string, results: {
         index_name: string;

package/dist/migrate/introspection/postgresIntrospector.js

@@ -3,9 +3,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * PostgreSQL schema introspector
  */
 export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT table_name
@@ -128,12 +125,6 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ORDER BY kcu.ordinal_position
     `;
     }
-    // ============================================================================
-    // Internal Types
-    // ============================================================================
-    mapTableNameRow(row) {
-        return row.table_name;
-    }
     async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.column_name,
@@ -166,9 +157,6 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));
     }
-    // ============================================================================
-    // PostgreSQL-specific helpers
-    // ============================================================================
     normalizeType(dataType, udtName) {
         // Handle user-defined types and arrays
         if (dataType === 'USER-DEFINED') {

package/dist/migrate/introspection/sqliteIntrospector.d.ts

@@ -15,6 +15,7 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
     protected getIndexesParams(_tableName: string): unknown[];
     protected getForeignKeysParams(_tableName: string): unknown[];
     protected getPrimaryKeyParams(_tableName: string): unknown[];
+    /** `sqlite_master`, not `information_schema`, so the column is `name`. */
     protected mapTableNameRow(row: {
         name: string;
     }): string;

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -3,9 +3,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * SQLite schema introspector
  */
 export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT name
@@ -55,9 +52,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     getPrimaryKeyParams(_tableName) {
         return [];
     }
-    // ============================================================================
-    // Row Mapping (dialect-specific)
-    // ============================================================================
+    /** `sqlite_master`, not `information_schema`, so the column is `name`. */
     mapTableNameRow(row) {
         return row.name;
     }
@@ -128,9 +123,6 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }
         return pkColumns.map((r) => r.name);
     }
-    // ============================================================================
-    // SQLite-specific helpers
-    // ============================================================================
     async getUniqueColumns(read, tableName) {
         const indexes = await read(this.getIndexesQuery(tableName));
         const uniqueColumns = new Set();

package/dist/migrate/migrator.d.ts

@@ -53,6 +53,14 @@ export declare class Migrator {
         to?: string;
         step?: number;
     }): Promise<MigrationResult[]>;
+    /**
+     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
+     *
+     * Both directions do exactly this and differ only in the list they start from: `up` takes the
+     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
+     * makes `--to` and `--step` mean the same thing whichever way you are going.
+     */
+    private runInOrder;
     /**
      * Run a single migration within a transaction
      */
@@ -96,6 +104,15 @@ export declare class Migrator {
         safe?: boolean;
         drop?: boolean;
     }): Promise<string[]>;
+    /**
+     * New tables are emitted together, never one at a time: a single-entity AST has no other table for a
+     * relation to resolve against, so every cross-entity foreign key was dropped and generated schemas
+     * carried none. Spanning the graph is also what lets a cyclic relation (any `createdBy`
+     * back-reference) be created at all.
+     *
+     * Empty in, empty out, so a diff with no new tables does not build an AST for the whole graph.
+     */
+    private createSchema;
     /**
      * Each pending diff with the entity it came from, since resolving that is async and every caller
      * needs it. What to emit stays with the caller: a sync narrows the forward direction to what the

package/dist/migrate/migrator.js

@@ -130,27 +130,7 @@ export class Migrator {
      * Run all pending migrations
      */
     async up(options = {}) {
-        const pendingMigrations = await this.pending();
-        const results = [];
-        let migrationsToRun = pendingMigrations;
-        if (options.to) {
-            const toIndex = migrationsToRun.findIndex((m) => m.name === options.to);
-            if (toIndex === -1) {
-                throw new Error(`Migration '${options.to}' not found`);
-            }
-            migrationsToRun = migrationsToRun.slice(0, toIndex + 1);
-        }
-        if (options.step !== undefined) {
-            migrationsToRun = migrationsToRun.slice(0, options.step);
-        }
-        for (const migration of migrationsToRun) {
-            const result = await this.runMigration(migration, 'up');
-            results.push(result);
-            if (!result.success) {
-                break; // Stop on first failure
-            }
-        }
-        return results;
+        return this.runInOrder(await this.pending(), 'up', options);
     }
     /**
      * Rollback migrations
@@ -159,23 +139,33 @@ export class Migrator {
         const [migrations, executed] = await Promise.all([this.getMigrations(), this.storage.executed()]);
         const executedSet = new Set(executed);
         const executedMigrations = migrations.filter((m) => executedSet.has(m.name)).reverse(); // Rollback in reverse order
-        const results = [];
-        let migrationsToRun = executedMigrations;
+        return this.runInOrder(executedMigrations, 'down', options);
+    }
+    /**
+     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
+     *
+     * Both directions do exactly this and differ only in the list they start from: `up` takes the
+     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
+     * makes `--to` and `--step` mean the same thing whichever way you are going.
+     */
+    async runInOrder(migrations, direction, options) {
+        let selected = migrations;
         if (options.to) {
-            const toIndex = migrationsToRun.findIndex((m) => m.name === options.to);
+            const toIndex = selected.findIndex((m) => m.name === options.to);
             if (toIndex === -1) {
                 throw new Error(`Migration '${options.to}' not found`);
             }
-            migrationsToRun = migrationsToRun.slice(0, toIndex + 1);
+            selected = selected.slice(0, toIndex + 1);
         }
         if (options.step !== undefined) {
-            migrationsToRun = migrationsToRun.slice(0, options.step);
+            selected = selected.slice(0, options.step);
         }
-        for (const migration of migrationsToRun) {
-            const result = await this.runMigration(migration, 'down');
+        const results = [];
+        for (const migration of selected) {
+            const result = await this.runMigration(migration, direction);
             results.push(result);
             if (!result.success) {
-                break; // Stop on first failure
+                break;
             }
         }
         return results;
@@ -244,20 +234,22 @@ export class Migrator {
      * Generate a migration based on entity schema differences
      */
     async generateFromEntities(name) {
-        const upStatements = [];
+        const creating = [];
+        const altering = [];
         const downStatements = [];
         for (const { diff, entity } of await this.pendingDiffs()) {
             if (diff.type === 'create') {
                 if (entity) {
-                    upStatements.push(...this.generator.generateCreateTable(entity));
+                    creating.push(diff.tableName);
                     downStatements.push(this.generator.generateDropTable(diff.tableName, { ifExists: true }));
                 }
             }
             else if (diff.type === 'alter') {
-                upStatements.push(...this.generator.generateAlterTable(diff));
+                altering.push(...this.generator.generateAlterTable(diff));
                 downStatements.push(...this.generator.generateAlterTableDown(diff));
             }
         }
+        const upStatements = [...this.createSchema(creating), ...altering];
         if (upStatements.length === 0) {
             this.logger.logInfo('No schema changes detected.');
             return '';
@@ -327,21 +319,18 @@ export class Migrator {
      */
     async syncForce() {
         await this.ensureSchemaGenerator();
+        // Both directions span the whole entity set rather than looping an entity at a time. A per-entity
+        // AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
+        // with no referential integrity; and the old drop loop went in reverse *declaration* order, which
+        // says nothing about the relation graph and is rejected as soon as the constraints are really there.
+        const statements = [
+            ...this.generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
+            ...this.generator.generateCreateSchema(this.entities),
+        ];
         await withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => querier.transaction(async () => {
-            // Drop all tables first (in reverse order for foreign keys)
-            for (const entity of [...this.entities].reverse()) {
-                const tableName = this.generator.resolveTableName(entity, getMeta(entity));
-                const dropSql = this.generator.generateDropTable(tableName, { ifExists: true });
-                this.logger.logSchema(`Executing: ${dropSql}`);
-                await querier.run(dropSql);
-            }
-            // Create all tables
-            for (const entity of this.entities) {
-                const createStmts = this.generator.generateCreateTable(entity);
-                for (const createSql of createStmts) {
-                    this.logger.logSchema(`Executing: ${createSql}`);
-                    await querier.run(createSql);
-                }
+            for (const sql of statements) {
+                this.logger.logSchema(`Executing: ${sql}`);
+                await querier.run(sql);
             }
         }));
         this.logger.logSchema('Schema sync (force) completed');
@@ -363,17 +352,29 @@ export class Migrator {
      * statements rather than a summary of a second, differently-computed diff.
      */
     async planSync(options = {}) {
-        const statements = [];
+        const creating = [];
+        const altering = [];
         for (const { diff, entity } of await this.pendingDiffs()) {
             if (diff.type === 'create') {
                 if (entity)
-                    statements.push(...this.generator.generateCreateTable(entity));
+                    creating.push(diff.tableName);
             }
             else if (diff.type === 'alter') {
-                statements.push(...this.generator.generateAlterTable(this.filterDiff(diff, options)));
+                altering.push(...this.generator.generateAlterTable(this.filterDiff(diff, options)));
             }
         }
-        return statements;
+        return [...this.createSchema(creating), ...altering];
+    }
+    /**
+     * New tables are emitted together, never one at a time: a single-entity AST has no other table for a
+     * relation to resolve against, so every cross-entity foreign key was dropped and generated schemas
+     * carried none. Spanning the graph is also what lets a cyclic relation (any `createdBy`
+     * back-reference) be created at all.
+     *
+     * Empty in, empty out, so a diff with no new tables does not build an AST for the whole graph.
+     */
+    createSchema(tableNames) {
+        return tableNames.length ? this.generator.generateCreateSchema(this.entities, { only: tableNames }) : [];
     }
     /**
      * Each pending diff with the entity it came from, since resolving that is async and every caller

package/dist/migrate/schemaGenerator.d.ts

@@ -1,6 +1,6 @@
 import { type AbstractDialect, AbstractSqlDialect } from '../dialect/index.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, DialectFeatures, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SqlDdlGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from './builder/types.js';
 /**
  * Unified SQL schema generator.
@@ -27,13 +27,24 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      */
     protected getCanonicalType(field: FieldOptions, fieldType?: unknown): CanonicalType;
     protected canonicalTypeToSql(type: CanonicalType): string;
-    generateCreateTable<E>(entity: Type<E>, options?: {
-        ifNotExists?: boolean;
-    }): string[];
-    generateDropTable(tableName: string, options?: {
-        ifExists?: boolean;
-        cascade?: boolean;
-    }): string;
+    /**
+     * Every `CREATE TABLE` for `entities`, then their foreign keys.
+     *
+     * Two phases rather than inline constraints, because a relation graph is routinely cyclic: any
+     * `createdBy`-style back-reference makes `A` reference `B` while `B` references `A`, and no create
+     * order satisfies that. TypeORM's schema builder splits for the same reason (`createNewTables()`
+     * then `createForeignKeys()`). SQLite is the exception and keeps them inline: it cannot `ALTER` a
+     * foreign key in, but it resolves targets lazily, so a forward reference is fine there.
+     */
+    generateCreateSchema(entities: readonly Type<unknown>[], options?: CreateSchemaOptions): string[];
+    generateDropSchema(entities: readonly Type<unknown>[], options?: DropSchemaOptions): string[];
+    /**
+     * The tables of `entities` in dependency order, optionally narrowed to `only`. The AST always spans
+     * every entity even when narrowed, so a relation pointing at a table outside the subset still
+     * resolves instead of being silently dropped.
+     */
+    private orderedTables;
+    generateDropTable(tableName: string, options?: DropSchemaOptions): string;
     generateAlterTable(diff: SchemaDiff): string[];
     generateAlterTableDown(diff: SchemaDiff): string[];
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {

package/dist/migrate/schemaGenerator.js

@@ -40,9 +40,6 @@ export class SqlSchemaGenerator {
     get serialPrimaryKeyType() {
         return this.dialect.serialPrimaryKey;
     }
-    // ============================================================================
-    // CanonicalType Integration (Unified Type System)
-    // ============================================================================
     /**
      * Convert FieldOptions to CanonicalType using the unified type system.
      */
@@ -52,14 +49,54 @@ export class SqlSchemaGenerator {
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
     }
-    // ============================================================================
-    // SchemaGenerator Implementation
-    // ============================================================================
-    generateCreateTable(entity, options = {}) {
-        const builder = new SchemaASTBuilder(this.dialect.namingStrategy);
-        const ast = builder.fromEntities([entity]);
-        const tableNode = ast.getTables()[0];
-        return this.generateCreateTableFromNode(tableNode, options);
+    /**
+     * Every `CREATE TABLE` for `entities`, then their foreign keys.
+     *
+     * Two phases rather than inline constraints, because a relation graph is routinely cyclic: any
+     * `createdBy`-style back-reference makes `A` reference `B` while `B` references `A`, and no create
+     * order satisfies that. TypeORM's schema builder splits for the same reason (`createNewTables()`
+     * then `createForeignKeys()`). SQLite is the exception and keeps them inline: it cannot `ALTER` a
+     * foreign key in, but it resolves targets lazily, so a forward reference is fine there.
+     */
+    generateCreateSchema(entities, options = {}) {
+        const tables = this.orderedTables(entities, 'create', options.only);
+        const withForeignKeys = options.foreignKeys ?? true;
+        // Inline only where a constraint cannot be added afterwards, which is what makes the cyclic case
+        // work everywhere else.
+        const inline = withForeignKeys && !this.features.foreignKeyAlter;
+        const statements = tables.flatMap((table) => this.generateCreateTableFromNode(inline ? table : { ...table, outgoingRelations: [] }, options));
+        if (withForeignKeys && !inline) {
+            for (const table of tables) {
+                for (const rel of table.outgoingRelations) {
+                    statements.push(this.generateAddForeignKeySql(table.name, {
+                        name: rel.name,
+                        columns: rel.from.columns.map((c) => c.name),
+                        referencesTable: rel.to.table.name,
+                        referencesColumns: rel.to.columns.map((c) => c.name),
+                        onDelete: rel.onDelete ?? this.defaultForeignKeyAction,
+                        onUpdate: rel.onUpdate ?? this.defaultForeignKeyAction,
+                    }));
+                }
+            }
+        }
+        return statements;
+    }
+    generateDropSchema(entities, options = {}) {
+        return this.orderedTables(entities, 'drop').map((table) => this.generateDropTable(table.name, options));
+    }
+    /**
+     * The tables of `entities` in dependency order, optionally narrowed to `only`. The AST always spans
+     * every entity even when narrowed, so a relation pointing at a table outside the subset still
+     * resolves instead of being silently dropped.
+     */
+    orderedTables(entities, direction, only) {
+        const ast = new SchemaASTBuilder(this.dialect.namingStrategy).fromEntities(entities);
+        const tables = direction === 'create' ? ast.getCreateOrder() : ast.getDropOrder();
+        if (!only) {
+            return tables;
+        }
+        const wanted = new Set(only);
+        return tables.filter((table) => wanted.has(table.name));
     }
     generateDropTable(tableName, options = {}) {
         const ifExists = options.ifExists ? 'IF EXISTS ' : '';
@@ -390,9 +427,6 @@ export class SqlSchemaGenerator {
         };
         return normalize(current) === normalize(desired);
     }
-    // ============================================================================
-    // SchemaAST Support Methods
-    // ============================================================================
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
@@ -468,9 +502,6 @@ export class SqlSchemaGenerator {
     generateCreateIndexFromNode(index, options = { ifNotExists: false }) {
         return this.generateCreateIndex(index.table.name, indexNodeToSchema(index), options);
     }
-    // ============================================================================
-    // Phase 3: Builder Operation Methods (Moved forward for unification)
-    // ============================================================================
     generateCreateTableFromDefinition(table, options = {}) {
         const tableNode = this.tableDefinitionToNode(table);
         return this.generateCreateTableFromNode(tableNode, options);

package/dist/neon/neonQuerierPool.d.ts

@@ -6,5 +6,5 @@ import { NeonQuerier } from './neonQuerier.js';
 export declare class NeonQuerierPool extends AbstractPgQuerierPool<PoolClient, NeonQuerier, NeonDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    getQuerier(): Promise<NeonQuerier>;
+    protected buildQuerier(connect: () => Promise<PoolClient>): NeonQuerier;
 }

package/dist/neon/neonQuerierPool.js

@@ -1,12 +1,14 @@
-import { Pool } from '@neondatabase/serverless';
+import { Pool, types } from '@neondatabase/serverless';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
+import { numericTypes } from '../postgres/pgNumericTypes.js';
 import { NeonDialect } from './neonDialect.js';
 import { NeonQuerier } from './neonQuerier.js';
 export class NeonQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
-        super(new NeonDialect({ namingStrategy: extra?.namingStrategy }), new Pool(opts), extra);
+        // Neon's own `types`, not `pg`'s: this entry has to load on an edge runtime where `pg` is absent.
+        super(new NeonDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ types: numericTypes(types), ...opts }), extra);
     }
-    async getQuerier() {
-        return new NeonQuerier(() => this.pool.connect(), this.dialect, this.extra);
+    buildQuerier(connect) {
+        return new NeonQuerier(connect, this.dialect, this.extra);
     }
 }

package/dist/postgres/abstractPgQuerierPool.d.ts

@@ -17,5 +17,11 @@ export interface PgAnyPool<C extends PgAnyClient> extends ErrorEmittingPool {
 export declare abstract class AbstractPgQuerierPool<C extends PgAnyClient, Q extends AbstractPgQuerier<C, D>, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<Q, D> {
     readonly pool: PgAnyPool<C>;
     constructor(dialect: D, pool: PgAnyPool<C>, extra?: ExtraOptions);
+    /**
+     * Every pg-compatible pool acquires a client the same way, so only the querier class varies.
+     * Subclasses name that instead of restating the lazy `connect` the querier expects.
+     */
+    protected abstract buildQuerier(connect: () => Promise<C>): Q;
+    getQuerier(): Promise<Q>;
     end(): Promise<void>;
 }

package/dist/postgres/abstractPgQuerierPool.js

@@ -14,6 +14,9 @@ export class AbstractPgQuerierPool extends AbstractSqlQuerierPool {
         this.pool = pool;
         attachPoolErrorHandler(pool, 'Idle Postgres pool client encountered an error');
     }
+    async getQuerier() {
+        return this.buildQuerier(() => this.pool.connect());
+    }
     async end() {
         await this.pool.end();
     }

package/dist/postgres/pgNumericTypes.d.ts

@@ -0,0 +1,41 @@
+import type { CustomTypesConfig } from 'pg';
+/**
+ * The shape every pg-family driver exposes as `types`: `pg`'s own, and `@neondatabase/serverless`'s
+ * reimplementation of it. Taken as a parameter rather than imported, because `uql-orm/neon` must not
+ * pull `pg` into an edge bundle that has no such peer installed - the same reason
+ * `abstractPgQuerierPool.ts` keeps its `pg` imports type-only.
+ */
+type PgTypes = {
+    readonly builtins: Readonly<Record<string, number>>;
+    getTypeParser(oid: number, format?: 'text' | 'binary'): (value: string) => unknown;
+};
+/**
+ * Decode `INT8` and `FLOAT8` as JS numbers, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
+ * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
+ * JS number is, so decoding it loses nothing at all.
+ *
+ * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
+ * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
+ * types belong here and which need the entity's declaration is settled in `hydratableFields`.
+ *
+ * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
+ * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
+ * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
+ *
+ * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
+ * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
+ * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
+ * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
+ * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
+ * behaviour the library never shipped. Do not reintroduce one.
+ *
+ * Exact to 2^53, which covers any auto-increment id. A caller who needs more passes their own
+ * `types` in the pool options: it is spread after this one and therefore wins. For a decimal, the
+ * lighter escape hatch is the declaration itself: `@Field({ type: String, columnType: 'decimal' })`
+ * keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ */
+export declare function numericTypes(types: PgTypes): CustomTypesConfig;
+export {};

package/dist/postgres/pgNumericTypes.js

@@ -0,0 +1,35 @@
+/**
+ * Decode `INT8` and `FLOAT8` as JS numbers, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
+ * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
+ * JS number is, so decoding it loses nothing at all.
+ *
+ * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
+ * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
+ * types belong here and which need the entity's declaration is settled in `hydratableFields`.
+ *
+ * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
+ * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
+ * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
+ *
+ * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
+ * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
+ * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
+ * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
+ * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
+ * behaviour the library never shipped. Do not reintroduce one.
+ *
+ * Exact to 2^53, which covers any auto-increment id. A caller who needs more passes their own
+ * `types` in the pool options: it is spread after this one and therefore wins. For a decimal, the
+ * lighter escape hatch is the declaration itself: `@Field({ type: String, columnType: 'decimal' })`
+ * keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ */
+export function numericTypes(types) {
+    // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
+    const textNumeric = new Set([types.builtins['INT8'], types.builtins['FLOAT8']]);
+    return {
+        getTypeParser: (oid, format) => format === 'text' && textNumeric.has(oid) ? Number : types.getTypeParser(oid, format),
+    };
+}

package/dist/postgres/pgQuerierPool.d.ts

@@ -6,5 +6,5 @@ import { PgQuerier } from './pgQuerier.js';
 export declare class PgQuerierPool extends AbstractPgQuerierPool<PoolClient, PgQuerier, PgDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    getQuerier(): Promise<PgQuerier>;
+    protected buildQuerier(connect: () => Promise<PoolClient>): PgQuerier;
 }

package/dist/postgres/pgQuerierPool.js

@@ -1,14 +1,15 @@
-import { Pool } from 'pg';
+import { Pool, types } from 'pg';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
 import { PgDialect } from './pgDialect.js';
+import { numericTypes } from './pgNumericTypes.js';
 import { PgQuerier } from './pgQuerier.js';
 export class PgQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // keepAlive reduces (but can't eliminate) idle connections being silently
         // dropped by NATs/firewalls on long-lived remote connections.
-        super(new PgDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, ...opts }), extra);
+        super(new PgDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
     }
-    async getQuerier() {
-        return new PgQuerier(() => this.pool.connect(), this.dialect, this.extra);
+    buildQuerier(connect) {
+        return new PgQuerier(connect, this.dialect, this.extra);
     }
 }

package/dist/querier/abstractSqlQuerier.d.ts

@@ -41,8 +41,15 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * Drivers with native cursor/streaming APIs (SQLite, Pg) should override this.
      */
     protected internalStream<T>(query: string, values?: unknown[]): AsyncIterable<T>;
-    private hydrateJsonFields;
-    private hydrateJsonFieldsRecursive;
+    /**
+     * Turn what a driver returned back into the types the entity declares, for the row and everything
+     * populated under it. Which columns, and as what, is `hydratableFields`; the per-cell decode is
+     * `decodeColumn`. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
+     *
+     * `visited` guards a populated graph that points back at itself; it defaults rather than living in
+     * a separate entry-point wrapper, because the wrapper's whole body was seeding it.
+     */
+    private hydrateFields;
     protected internalCount<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     internalInsertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;