uql-orm 0.33.0 → 0.34.1

package/dist/bunSql/bunSqlQuerierPool.js

@@ -1,4 +1,5 @@
 import { SQL } from 'bun';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { MariaDialect } from '../maria/mariaDialect.js';
 import { MySqlDialect } from '../mysql/mysqlDialect.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
@@ -20,7 +21,7 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     sqlDialectName;
     constructor(config, extra) {
         const dialectName = inferDialectName(config);
-        super(new DialectMap[dialectName]({ namingStrategy: extra?.namingStrategy }), extra);
+        super(new DialectMap[dialectName](dialectOptionsFrom(extra)), extra);
         this.config = config;
         this.sqlDialectName = dialectName;
         const opts = normalizeBunOpts(config, dialectName);

package/dist/cockroachdb/crdbQuerierPool.js

@@ -1,4 +1,5 @@
 import { Pool, types } from 'pg';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
 import { numericTypes } from '../postgres/pgNumericTypes.js';
 import { CockroachDialect } from './cockroachDialect.js';
@@ -8,7 +9,7 @@ import { CrdbQuerier } from './crdbQuerier.js';
  */
 export class CrdbQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
-        super(new CockroachDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
+        super(new CockroachDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
     }
     buildQuerier(connect) {
         return new CrdbQuerier(connect, this.dialect, this.extra);

package/dist/d1/d1QuerierPool.js

@@ -1,10 +1,11 @@
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
 import { D1Querier } from './d1Querier.js';
 import { D1SqliteDialect } from './d1SqliteDialect.js';
 export class D1QuerierPool extends AbstractSqlQuerierPool {
     db;
     constructor(db, extra) {
-        super(new D1SqliteDialect({ namingStrategy: extra?.namingStrategy }), extra);
+        super(new D1SqliteDialect(dialectOptionsFrom(extra)), extra);
         this.db = db;
     }
     async getQuerier() {

package/dist/dialect/abstractDialect.d.ts

@@ -1,11 +1,19 @@
-import type { DialectFeatures, DialectName, EntityMeta, FieldOptions, InsertIdSource, NamingStrategy, QueryOptions, QueryWhere, QueryWhereMap, Type } from '../type/index.js';
+import type { DialectFeatures, DialectName, EntityMeta, ExtraOptions, FieldOptions, InsertIdSource, NamingStrategy, QueryOptions, QueryWhere, QueryWhereMap } from '../type/index.js';
 /**
  * Options for initializing a dialect.
  */
 export interface DialectOptions {
     readonly namingStrategy?: NamingStrategy;
+    /** Default schema for entities naming none; unset leaves them unqualified. See {@link AbstractDialect.resolveSchema}. */
+    readonly schema?: string;
     readonly driverCapabilities?: Partial<DialectFeatures>;
 }
+/**
+ * The dialect's share of a pool's {@link ExtraOptions}: what changes the SQL rather than the
+ * connection. Every pool builds its dialect through this, so a new option lands here instead of in
+ * each of the thirteen constructors.
+ */
+export declare function dialectOptionsFrom(extra: ExtraOptions | undefined): DialectOptions;
 /**
  * Base abstract class for all database dialects (SQL and NoSQL).
  */
@@ -34,9 +42,25 @@ export declare abstract class AbstractDialect {
      */
     get features(): DialectFeatures;
     /**
-     * Resolve the table name for an entity, applying naming strategy if necessary.
+     * The table's own name, unqualified, applying naming strategy if necessary. Also the alias the
+     * root table gets once {@link resolveTableName} qualifies it, so it has to stay a single
+     * identifier: columns are prefixed with it, and a dotted prefix escapes as one identifier that
+     * nothing declared.
+     */
+    resolveTableAlias<E>(meta: EntityMeta<E>): string;
+    /**
+     * Where the table lives: {@link resolveTableAlias} behind its schema, when one applies. The schema
+     * skips the naming strategy - it names an object the author wrote out, and snake_casing `myCrm`
+     * would point at one that does not exist.
+     */
+    resolveTableName<E>(meta: EntityMeta<E>): string;
+    /**
+     * Which schema an entity is read from: its own wins over the pool's default, the way its `name`
+     * wins over the naming strategy. `undefined` is an answer, not a gap - the table stays unqualified
+     * and resolves through the connection's `search_path`, which is what every deployment predating
+     * this option relies on.
      */
-    resolveTableName<E>(entity: Type<E>, meta: EntityMeta<E>): string;
+    resolveSchema<E>(meta: EntityMeta<E>): string | undefined;
     /**
      * Resolve the column/field name for a property, applying naming strategy if necessary.
      */

package/dist/dialect/abstractDialect.js

@@ -1,4 +1,13 @@
 import { applyFilters, buildQueryWhereAsMap } from '../util/dialect.util.js';
+import { qualifyName } from '../util/sql.util.js';
+/**
+ * The dialect's share of a pool's {@link ExtraOptions}: what changes the SQL rather than the
+ * connection. Every pool builds its dialect through this, so a new option lands here instead of in
+ * each of the thirteen constructors.
+ */
+export function dialectOptionsFrom(extra) {
+    return { namingStrategy: extra?.namingStrategy, schema: extra?.schema };
+}
 /**
  * Base abstract class for all database dialects (SQL and NoSQL).
  */
@@ -25,15 +34,36 @@ export class AbstractDialect {
         return this.#features;
     }
     /**
-     * Resolve the table name for an entity, applying naming strategy if necessary.
+     * The table's own name, unqualified, applying naming strategy if necessary. Also the alias the
+     * root table gets once {@link resolveTableName} qualifies it, so it has to stay a single
+     * identifier: columns are prefixed with it, and a dotted prefix escapes as one identifier that
+     * nothing declared.
      */
-    resolveTableName(entity, meta) {
-        const name = meta.name ?? entity.name;
-        if (name !== entity.name || !this.namingStrategy) {
+    resolveTableAlias(meta) {
+        const className = meta.entity.name;
+        const name = meta.name ?? className;
+        if (name !== className || !this.namingStrategy) {
             return name;
         }
         return this.namingStrategy.tableName(name);
     }
+    /**
+     * Where the table lives: {@link resolveTableAlias} behind its schema, when one applies. The schema
+     * skips the naming strategy - it names an object the author wrote out, and snake_casing `myCrm`
+     * would point at one that does not exist.
+     */
+    resolveTableName(meta) {
+        return qualifyName(this.resolveTableAlias(meta), this.resolveSchema(meta));
+    }
+    /**
+     * Which schema an entity is read from: its own wins over the pool's default, the way its `name`
+     * wins over the naming strategy. `undefined` is an answer, not a gap - the table stays unqualified
+     * and resolves through the connection's `search_path`, which is what every deployment predating
+     * this option relies on.
+     */
+    resolveSchema(meta) {
+        return this.features.schemas ? (meta.schema ?? this.options.schema) : undefined;
+    }
     /**
      * Resolve the column/field name for a property, applying naming strategy if necessary.
      */

package/dist/dialect/abstractSqlDialect.d.ts

@@ -15,6 +15,12 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     abstract readonly beginTransactionCommand: string;
     abstract readonly commitTransactionCommand: string;
     abstract readonly rollbackTransactionCommand: string;
+    /**
+     * How this engine declares a namespace, so a generated migration creates the schemas its tables
+     * need before creating them. Only reached where {@link DialectFeatures.schemas} is on. MySQL and
+     * MariaDB accept the same statement, where it means a database.
+     */
+    createSchemaSql(schema: string): string;
     readonly isolationLevelStrategy: 'inline' | 'set-before' | 'none';
     readonly alterColumnStrategy: 'separate-clauses' | 'single-statement';
     readonly alterColumnSyntax: 'ALTER COLUMN' | 'MODIFY COLUMN' | 'none';
@@ -68,10 +74,24 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      */
     protected appendTextSearch<E>(_ctx: QueryContext, _entity: Type<E>, _meta: EntityMeta<E>, _search: QueryTextSearchOptions<E>): void;
     select<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions, joins?: QueryJoins): void;
+    /**
+     * The table as a statement writes it, each part escaped on its own rather than as one dotted
+     * string taken apart again by {@link escapeId}.
+     */
+    protected escapedTableName<E>(meta: EntityMeta<E>): string;
+    /**
+     * A FROM or JOIN operand plus the alias to prefix its columns by, aliased only once a schema puts
+     * something in front of the name. See {@link resolveTableAlias} for why the prefix cannot be the
+     * qualified path.
+     */
+    protected tableRef<E>(meta: EntityMeta<E>): {
+        alias: string;
+        ref: string;
+    };
     /** Columns are alias-qualified once anything else is in play: a join, or a to-many being filled. */
     private resolveRelationAwarePrefix;
     protected selectRelationFields(ctx: QueryContext, joins: QueryJoins): void;
-    protected selectRelationJoins<E>(ctx: QueryContext, meta: EntityMeta<E>, tableName: string, joins: QueryJoins): void;
+    protected selectRelationJoins<E>(ctx: QueryContext, meta: EntityMeta<E>, rootAlias: string, joins: QueryJoins): void;
     where<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
     /** Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or` recursion). */
     protected renderWhere<E>(ctx: QueryContext, entity: Type<E>, where?: QueryWhere<E>, opts?: QueryWhereOptions): void;
@@ -281,6 +301,12 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
     protected getUpsertConflictPathsStr<E>(meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>): string;
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
     escapeId(val: string | undefined, forbidQualified?: boolean, addDot?: boolean): string;
+    /**
+     * A name behind its schema, each part escaped on its own rather than as one dotted string taken
+     * apart again by {@link escapeId}. Tables and their indexes both use it, since an index lives in
+     * the schema of the table it is on.
+     */
+    escapeQualifiedId(name: string, schema: string | undefined): string;
     /**
      * Bind one persisted value, classifying its column on the spot. Dialects override
      * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per

package/dist/dialect/abstractSqlDialect.js

@@ -9,6 +9,14 @@ import { SqlQueryContext } from './queryContext.js';
 import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
 import { isVectorFieldType, resolveVectorCast } from './vectorCast.js';
 export class AbstractSqlDialect extends IndexSqlDialect {
+    /**
+     * How this engine declares a namespace, so a generated migration creates the schemas its tables
+     * need before creating them. Only reached where {@link DialectFeatures.schemas} is on. MySQL and
+     * MariaDB accept the same statement, where it means a database.
+     */
+    createSchemaSql(schema) {
+        return `CREATE SCHEMA IF NOT EXISTS ${this.escapeId(schema, true)}`;
+    }
     isolationLevelStrategy = 'inline';
     alterColumnStrategy = 'single-statement';
     alterColumnSyntax = 'ALTER COLUMN';
@@ -89,8 +97,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     }
     search(ctx, entity, q = {}, opts = {}, joins = NO_JOINS) {
         const meta = getMeta(entity);
-        const tableName = this.resolveTableName(entity, meta);
-        const prefix = this.resolveRelationAwarePrefix(tableName, meta, opts, q.$populate, joins);
+        const prefix = this.resolveRelationAwarePrefix(this.resolveTableAlias(meta), meta, opts, q.$populate, joins);
         if (opts.prefix !== prefix) {
             opts = { ...opts, prefix };
         }
@@ -166,8 +173,8 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     }
     select(ctx, entity, q, opts = {}, joins = NO_JOINS) {
         const meta = getMeta(entity);
-        const tableName = this.resolveTableName(entity, meta);
-        const prefix = this.resolveRelationAwarePrefix(tableName, meta, opts, q.$populate, joins);
+        const { alias, ref } = this.tableRef(meta);
+        const prefix = this.resolveRelationAwarePrefix(alias, meta, opts, q.$populate, joins);
         ctx.append(q.$distinct ? 'SELECT DISTINCT ' : 'SELECT ');
         this.selectFields(ctx, entity, q.$select, { prefix }, q.$exclude);
         // Add related fields BEFORE FROM clause
@@ -179,9 +186,27 @@ export class AbstractSqlDialect extends IndexSqlDialect {
                 this.appendVectorProjection(ctx, meta, key, val);
             }
         }
-        ctx.append(` FROM ${this.escapeId(tableName)}`);
+        ctx.append(` FROM ${ref}`);
         // Add JOINs AFTER FROM clause
-        this.selectRelationJoins(ctx, meta, tableName, joins);
+        this.selectRelationJoins(ctx, meta, alias, joins);
+    }
+    /**
+     * The table as a statement writes it, each part escaped on its own rather than as one dotted
+     * string taken apart again by {@link escapeId}.
+     */
+    escapedTableName(meta) {
+        return this.escapeQualifiedId(this.resolveTableAlias(meta), this.resolveSchema(meta));
+    }
+    /**
+     * A FROM or JOIN operand plus the alias to prefix its columns by, aliased only once a schema puts
+     * something in front of the name. See {@link resolveTableAlias} for why the prefix cannot be the
+     * qualified path.
+     */
+    tableRef(meta) {
+        const alias = this.resolveTableAlias(meta);
+        const name = this.escapedTableName(meta);
+        const schema = this.resolveSchema(meta);
+        return { alias, ref: schema ? `${name} ${this.escapeId(alias, true)}` : name };
     }
     /** Columns are alias-qualified once anything else is in play: a join, or a to-many being filled. */
     resolveRelationAwarePrefix(tableName, meta, opts, populate, joins) {
@@ -198,11 +223,11 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             this.selectFields(ctx, join.entity, join.query.$select, { prefix: join.path, autoPrefixAlias: true }, join.query.$exclude);
         }
     }
-    selectRelationJoins(ctx, meta, tableName, joins) {
+    selectRelationJoins(ctx, meta, rootAlias, joins) {
         for (const join of joins.values()) {
             const joinAlias = this.escapeId(join.path, true);
-            const parentAlias = join.parent ? this.escapeId(join.parent.path, true) : this.escapeId(tableName);
-            ctx.append(` ${join.required ? 'INNER' : 'LEFT'} JOIN ${this.escapeId(this.resolveTableName(join.entity, join.meta))} ${joinAlias} ON `);
+            const parentAlias = join.parent ? this.escapeId(join.parent.path, true) : this.escapeId(rootAlias, true);
+            ctx.append(` ${join.required ? 'INNER' : 'LEFT'} JOIN ${this.escapedTableName(join.meta)} ${joinAlias} ON `);
             join.relation.references.forEach((reference, index) => {
                 if (index > 0)
                     ctx.append(' AND ');
@@ -264,11 +289,13 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         if (val instanceof QueryRaw) {
             if (key === '$exists' || key === '$nexists') {
                 ctx.append(key === '$exists' ? 'EXISTS (' : 'NOT EXISTS (');
-                const tableName = this.resolveTableName(entity, meta);
+                // The alias: the enclosing statement declares one, and Postgres forbids reaching past it
+                // to the qualified name it aliased.
+                const alias = this.resolveTableAlias(meta);
                 this.getRawValue(ctx, {
                     value: val,
-                    prefix: tableName,
-                    escapedPrefix: this.escapeId(tableName, false, true),
+                    prefix: alias,
+                    escapedPrefix: this.escapeId(alias, true, true),
                 });
                 ctx.append(')');
                 return;
@@ -735,7 +762,8 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         }
         this.assertLockSupported(entity, q, joins);
         const meta = getMeta(entity);
-        const target = joins.size > 0 ? ` OF ${this.escapeId(this.resolveTableName(entity, meta))}` : '';
+        // `OF` names the alias in the FROM, never the schema-qualified path it was aliased from.
+        const target = joins.size > 0 ? ` OF ${this.escapeId(this.resolveTableAlias(meta), true)}` : '';
         const suffix = wait === 'skip' ? ' SKIP LOCKED' : wait === 'nowait' ? ' NOWAIT' : '';
         ctx.append(` FOR UPDATE${target}${suffix}`);
     }
@@ -757,7 +785,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     ]);
     aggregate(ctx, entity, q, opts = {}) {
         const meta = getMeta(entity);
-        const tableName = this.resolveTableName(entity, meta);
+        const tableName = this.escapedTableName(meta);
         const groupKeys = [];
         const selectParts = [];
         // Every column the statement emits, mapped to the SQL that references it. `$having` and `$sort`
@@ -787,7 +815,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         if (!selectParts.length) {
             throw new TypeError('aggregate requires at least one $group column or $agg function');
         }
-        ctx.append(`SELECT ${selectParts.join(', ')} FROM ${this.escapeId(tableName)}`);
+        ctx.append(`SELECT ${selectParts.join(', ')} FROM ${tableName}`);
         this.where(ctx, entity, q.$where, opts);
         if (groupKeys.length) {
             ctx.append(` GROUP BY ${groupKeys.join(', ')}`);
@@ -893,8 +921,8 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             columns[i] = this.escapedColumnName(meta, key);
             kinds[i] = this.persistKind(field);
         }
-        const tableName = this.resolveTableName(entity, meta);
-        ctx.append(`INSERT INTO ${this.escapeId(tableName)} (${columns.join(', ')}) VALUES (`);
+        const tableName = this.escapedTableName(meta);
+        ctx.append(`INSERT INTO ${tableName} (${columns.join(', ')}) VALUES (`);
         for (let r = 0; r < payloads.length; r++) {
             if (r > 0) {
                 ctx.append('), (');
@@ -931,8 +959,8 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         const meta = getMeta(entity);
         const [filledPayload] = fillOnFields(meta, payload, 'onUpdate');
         const keys = filterFieldKeys(meta, filledPayload, 'onUpdate');
-        const tableName = this.resolveTableName(entity, meta);
-        ctx.append(`UPDATE ${this.escapeId(tableName)} SET `);
+        const tableName = this.escapedTableName(meta);
+        ctx.append(`UPDATE ${tableName} SET `);
         for (let i = 0; i < keys.length; i++) {
             if (i > 0) {
                 ctx.append(', ');
@@ -1014,14 +1042,14 @@ export class AbstractSqlDialect extends IndexSqlDialect {
     }
     delete(ctx, entity, q, opts = {}) {
         const meta = getMeta(entity);
-        const tableName = this.resolveTableName(entity, meta);
+        const tableName = this.escapedTableName(meta);
         // Soft-delete (stamp only live rows) unless `hardDelete` is requested or the entity has no
         // soft-delete field (e.g. a cascade onto a non-soft-deletable child).
         if (!opts.hardDelete && meta.softDelete) {
             const field = meta.fields[meta.softDelete];
             if (field) {
                 const columnName = this.resolveColumnName(meta.softDelete, field);
-                ctx.append(`UPDATE ${this.escapeId(tableName)} SET ${this.escapeId(columnName)} = `);
+                ctx.append(`UPDATE ${tableName} SET ${this.escapeId(columnName)} = `);
                 this.formatPersistableValue(ctx, field, getSoftDeleteValue(field));
                 this.search(ctx, entity, q, opts);
                 return;
@@ -1029,12 +1057,21 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         }
         // Hard delete removes matching rows regardless of soft-delete state (keeps other filters, e.g. tenant).
         // Only rewrite the filters when there is a soft-delete filter to disable.
-        ctx.append(`DELETE FROM ${this.escapeId(tableName)}`);
+        ctx.append(`DELETE FROM ${tableName}`);
         this.search(ctx, entity, q, meta.softDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts);
     }
     escapeId(val, forbidQualified, addDot) {
         return escapeSqlId(val, this.escapeIdChar, forbidQualified, addDot);
     }
+    /**
+     * A name behind its schema, each part escaped on its own rather than as one dotted string taken
+     * apart again by {@link escapeId}. Tables and their indexes both use it, since an index lives in
+     * the schema of the table it is on.
+     */
+    escapeQualifiedId(name, schema) {
+        const escaped = this.escapeId(name, true);
+        return schema ? `${this.escapeId(schema, true)}.${escaped}` : escaped;
+    }
     /**
      * Bind one persisted value, classifying its column on the spot. Dialects override
      * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per
@@ -1353,38 +1390,39 @@ export class AbstractSqlDialect extends IndexSqlDialect {
      */
     appendRelationSubquery(ctx, entity, rel, opts, projection, val) {
         const meta = getMeta(entity);
-        const parentTable = this.resolveTableName(entity, meta);
+        // Aliases, not paths, everywhere a column is prefixed; `tableRef` declares them in the FROM.
+        const parentAlias = this.resolveTableAlias(meta);
         const references = rel.references;
-        const escapedParentId = this.escapedParentColumn(parentTable, meta, opts, meta.id);
+        const escapedParentId = this.escapedParentColumn(parentAlias, meta, opts, meta.id);
         const relatedEntity = rel.entity();
         const relatedMeta = getMeta(relatedEntity);
-        const relatedTable = this.resolveTableName(relatedEntity, relatedMeta);
+        const { alias: relatedAlias, ref: relatedRef } = this.tableRef(relatedMeta);
         // Resolved before any SQL is emitted: it also decides whether the mm form reaches the target.
         const targetWhere = this.scopedWhereMap(relatedMeta, val);
         ctx.append(`(SELECT ${projection} FROM `);
         if (rel.cardinality === 'mm' && rel.through) {
             const throughEntity = rel.through();
             const throughMeta = getMeta(throughEntity);
-            const throughTable = this.resolveTableName(throughEntity, throughMeta);
-            ctx.append(this.escapeId(throughTable));
-            ctx.append(` WHERE ${this.escapedColumn(throughTable, throughMeta, references[0].local)} = ${escapedParentId}`);
+            const { alias: throughAlias, ref: throughRef } = this.tableRef(throughMeta);
+            ctx.append(throughRef);
+            ctx.append(` WHERE ${this.escapedColumn(throughAlias, throughMeta, references[0].local)} = ${escapedParentId}`);
             // The junction is a row being read too: a soft-deleted link is not a link.
-            this.where(ctx, throughEntity, {}, { prefix: throughTable, clause: 'AND' });
+            this.where(ctx, throughEntity, {}, { prefix: throughAlias, clause: 'AND' });
             if (hasKeys(targetWhere)) {
-                ctx.append(` AND ${this.escapedColumn(throughTable, throughMeta, references[1].local)} IN (`);
-                ctx.append(`SELECT ${this.escapedColumn(relatedTable, relatedMeta, relatedMeta.id)} FROM ${this.escapeId(relatedTable)}`);
-                this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: relatedTable, clause: 'WHERE' });
+                ctx.append(` AND ${this.escapedColumn(throughAlias, throughMeta, references[1].local)} IN (`);
+                ctx.append(`SELECT ${this.escapedColumn(relatedAlias, relatedMeta, relatedMeta.id)} FROM ${relatedRef}`);
+                this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: relatedAlias, clause: 'WHERE' });
                 ctx.append(')');
             }
         }
         else {
-            const joinLeft = this.escapedColumn(relatedTable, relatedMeta, references[0].foreign);
+            const joinLeft = this.escapedColumn(relatedAlias, relatedMeta, references[0].foreign);
             const joinRight = rel.cardinality === '1m'
                 ? escapedParentId
-                : this.escapedParentColumn(parentTable, meta, opts, references[0].local);
-            ctx.append(this.escapeId(relatedTable));
+                : this.escapedParentColumn(parentAlias, meta, opts, references[0].local);
+            ctx.append(relatedRef);
             ctx.append(` WHERE ${joinLeft} = ${joinRight}`);
-            this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: relatedTable, clause: 'AND' });
+            this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: relatedAlias, clause: 'AND' });
         }
         ctx.append(')');
     }

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -23,6 +23,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         supportsJsonb: false,
         ifNotExists: true,
         indexIfNotExists: false,
+        schemas: true,
         dropTableCascade: false,
         renameColumn: true,
         foreignKeyAlter: true,

package/dist/dialect/pgLikeSqlDialect.js

@@ -20,6 +20,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         supportsJsonb: true,
         ifNotExists: true,
         indexIfNotExists: true,
+        schemas: true,
         dropTableCascade: true,
         renameColumn: true,
         foreignKeyAlter: true,

package/dist/entity/metadata/definition.js

@@ -104,6 +104,14 @@ export function applyMembers(entity, specs) {
     }
 }
 export function defineEntity(entity, opts = {}) {
+    // Ahead of any registration, so a rejected definition leaves nothing half-written in the registry.
+    // A dotted name reads like a schema and is not one: it escapes as a single identifier, so the
+    // statement builds and then fails at the database. `schema` is the way to say it.
+    if (opts.name?.includes('.')) {
+        const [schema, ...rest] = opts.name.split('.');
+        throw new TypeError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
+            `{ schema: '${schema}', name: '${rest.join('.')}' }.`);
+    }
     const meta = ensureMeta(entity);
     // Covers `defineEntity(Decorated)` called on a class whose members carry decorators. `@Entity()`
     // drains `context.metadata` itself, because TypeScript only attaches `Symbol.metadata` to the class
@@ -121,6 +129,7 @@ export function defineEntity(entity, opts = {}) {
         throw TypeError(`'${entity.name}' must have fields`);
     }
     meta.name = opts.name ?? entity.name;
+    meta.schema = opts.schema;
     let proto = Object.getPrototypeOf(entity.prototype);
     while (proto.constructor !== Object) {
         const parent = proto.constructor;

package/dist/http/handler.js

@@ -2,6 +2,11 @@ import { withContext } from '../context/context.js';
 import { getEntities, getMeta } from '../entity/index.js';
 import { entityPath, matchRoute, } from './contract.js';
 import { parseQueryParams } from './query.js';
+/** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
+function tableOf(entity) {
+    const meta = getMeta(entity);
+    return `${entity.name} (${meta.schema ? `${meta.schema}.${meta.name}` : meta.name})`;
+}
 export function createRequestHandler(opts) {
     const { include, exclude, pre, preSave, preFilter, post, getContext, pool } = opts;
     let entities = include ?? getEntities();
@@ -11,8 +16,18 @@ export function createRequestHandler(opts) {
     if (!entities.length) {
         throw new TypeError('no entities for the uql middleware');
     }
+    // The route is the class name, so two entities mapping one table in different schemas collide here
+    // even though nothing else about them does. All of them at once, so fixing the first collision
+    // does not just reveal the next.
+    const byPath = Map.groupBy(entities, entityPath);
+    const collisions = [...byPath].filter(([, clashing]) => clashing.length > 1);
+    if (collisions.length) {
+        const lines = collisions.map(([path, clashing]) => `  /${path} <- ${clashing.map(tableOf).join(', ')}`);
+        throw new TypeError(`every entity below shares a route with another, so all but the first are unreachable:\n${lines.join('\n')}\n` +
+            "A route is the kebab-cased class name. Rename a class, or pass only one of them in 'include'.");
+    }
     // biome-ignore lint/suspicious/noExplicitAny: heterogeneous entity map
-    const entityByPath = new Map(entities.map((entity) => [entityPath(entity), entity]));
+    const entityByPath = new Map([...byPath].map(([path, [entity]]) => [path, entity]));
     return (req) => {
         const entity = entityByPath.get(req.entityPath);
         if (!entity) {

package/dist/libsql/libsqlQuerierPool.js

@@ -1,3 +1,4 @@
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import { LibsqlDialect } from './libsqlDialect.js';
 import { LibsqlQuerier } from './libsqlQuerier.js';
@@ -13,7 +14,7 @@ function remoteMigrationClientConfig(config) {
 export class LibsqlQuerierPool extends AbstractHranaQuerierPool {
     conf;
     constructor(conf, extra) {
-        super(new LibsqlDialect({ namingStrategy: extra?.namingStrategy }), extra);
+        super(new LibsqlDialect(dialectOptionsFrom(extra)), extra);
         this.conf = conf;
     }
     openClient() {

package/dist/maria/mariadbQuerierPool.js

@@ -1,4 +1,5 @@
 import { createPool } from 'mariadb';
+import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
 import { attachPoolErrorHandler } from '../util/index.js';
 import { MariaDialect } from './mariaDialect.js';
@@ -6,7 +7,7 @@ import { MariadbQuerier } from './mariadbQuerier.js';
 export class MariadbQuerierPool extends AbstractSqlQuerierPool {
     pool;
     constructor(opts, extra) {
-        super(new MariaDialect({ namingStrategy: extra?.namingStrategy }), extra);
+        super(new MariaDialect(dialectOptionsFrom(extra)), extra);
         // `mariadb` defaults to handing BIGINT back as a BigInt, and uql maps `type: Number` to BIGINT
         // (see `schema/canonicalType.ts`), so every auto-increment id reached a field declared `number`
         // as `9n` without this. Same trade as the pg pools: exact to 2^53, and `...opts` wins for a

package/dist/migrate/builder/migrationBuilder.js

@@ -6,6 +6,7 @@
  * - MigrationBuilder: Execute DDL operations (for integration tests/runtime)
  */
 import { normalizeIndexColumn } from '../../util/index.js';
+import { derivedIndexName } from '../../util/sql.util.js';
 import { createSchemaGenerator } from '../schemaGenerator.js';
 import { splitSqlStatements } from './splitSqlStatements.js';
 import { TableBuilder } from './tableBuilder.js';
@@ -26,7 +27,8 @@ function createIndexOperation(tableName, columns, options = {}) {
         tableName,
         index: {
             ...index,
-            name: name ?? `idx_${tableName}_${entries.map((entry) => entry.column).join('_')}`,
+            name: name ??
+                derivedIndexName(tableName, entries.map((entry) => entry.column)),
             entries,
             unique: unique ?? false,
         },

package/dist/migrate/builder/tableBuilder.js

@@ -4,6 +4,7 @@
  * Fluent API for defining tables in migrations.
  */
 import { normalizeIndexColumn } from '../../util/index.js';
+import { derivedIndexName } from '../../util/sql.util.js';
 import { ColumnBuilder } from './columnBuilder.js';
 import { t } from './expressions.js';
 /**
@@ -190,7 +191,7 @@ export class TableBuilder {
         // Collect column-level indexes
         for (const col of columns) {
             if (col.index) {
-                const indexName = typeof col.index === 'string' ? col.index : `idx_${this._name}_${col.name}`;
+                const indexName = typeof col.index === 'string' ? col.index : derivedIndexName(this._name, [col.name]);
                 // Only add if not already in table-level indexes
                 if (!this._indexes.some((idx) => idx.name === indexName)) {
                     this._indexes.push({

package/dist/migrate/generator/definitionToNode.js

@@ -1,3 +1,4 @@
+import { derivedForeignKeyName } from '../../util/sql.util.js';
 /**
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
  * `createTable` and an entity reach `generateCreateTableFromNode` in the same shape. Free functions and
@@ -11,7 +12,6 @@ export function tableDefinitionToNode(def) {
         columns,
         primaryKey: [], // placeholder
         indexes: [],
-        schema: { tables: new Map(), relationships: [], indexes: [] },
         incomingRelations: [],
         outgoingRelations: [],
         comment: def.comment,
@@ -33,7 +33,7 @@ export function tableDefinitionToNode(def) {
     }
     for (const fkDef of def.foreignKeys) {
         const relNode = {
-            name: fkDef.name ?? `fk_${def.name}_${fkDef.columns.join('_')}`,
+            name: fkDef.name ?? derivedForeignKeyName(def.name, fkDef.columns),
             type: 'ManyToOne', // Builder default
             from: {
                 table,
@@ -64,7 +64,7 @@ export function fullColumnDefinitionToNode(col, tableName) {
         referencedBy: [],
         references: col.foreignKey
             ? {
-                name: `fk_${tableName}_${col.name}`,
+                name: derivedForeignKeyName(tableName, [col.name]),
                 type: 'ManyToOne',
                 from: { table: { name: tableName }, columns: [] },
                 to: {