@rebasepro/server-postgres 0.23.0 → 0.24.0

package/dist/{introspect-db-logic-WMuAfxvw.js → introspect-db-logic-kCETE8TY.js}

@@ -1,317 +1,8 @@
 import { createRequire as __createRequire } from "module";
 __createRequire(import.meta.url);
-import { firstFreeKey, toWireKey } from "@rebasepro/utils";
-//#region src/schema/introspect-db-queries.ts
-/**
-* A Postgres identifier, quoted so that whatever is inside it stays inside it.
-*
-* Introspection reads table and schema names out of `pg_class` and puts them
-* straight back into SQL, and wrapping a name in double quotes is not the same
-* as escaping it: a table named `x" ; DROP TABLE users; --` closes the quote
-* and then the statement. Postgres's own escape for a quote inside a quoted
-* identifier is to double it, which is what this does.
-*
-* "The catalogue is trusted" is true of your own database, and is exactly the
-* assumption this tool cannot make. Introspection exists to be pointed at
-* databases somebody else built, and it runs with the privileges of whoever
-* ran it — which is usually a superuser, because that is who has a connection
-* string to a database they are adopting.
-*/
-function quoteIdentifier(name) {
-	return `"${name.replace(/"/g, "\"\"")}"`;
-}
-/** `"schema"."table"`, both halves quoted. */
-function quoteRelation(schema, table) {
-	return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
-}
-/**
-* Can this table's name be the name of the file describing it?
-*
-* Introspection writes `<collectionsDir>/<tableName>.ts`, and the table name
-* came from a database this tool did not create. Postgres will hold a table
-* called `../../../etc/cron.d/x`, and `path.join` resolves it — so without this
-* the generator writes a file wherever the name points, as whoever ran the
-* command.
-*
-* Deliberately narrow, and deliberately not a blocklist of `..` and `/`: the
-* question is "is this a plain file name?", and every answer that is not
-* obviously yes is a table better written by hand. NUL and the Windows
-* separator are in scope because a collections directory is checked out on
-* whatever machine the developer has.
-*/
-function isUsableFileName(name) {
-	if (name.length === 0 || name.length > 200) return false;
-	if (name === "." || name === "..") return false;
-	if (/[/\\:\u0000-\u001f]/.test(name)) return false;
-	return !name.startsWith(".") && !name.endsWith(".");
-}
-/**
-* Base tables, excluding partitions.
-*
-* `relispartition` is the reason this reads `pg_class` rather than
-* `information_schema.tables`, which reports every partition as a base table of
-* its own. Pagila partitions `payment` by month; introspected through
-* information_schema it yields `payment` plus 26 near-identical
-* `payment_p2022_*` collections, each with its own nav entry.
-*
-* `relkind = 'p'` (the partitioned parent) is included and `'r'` partitions are
-* dropped, which is the right way round: the parent is the queryable table.
-*/
-var TABLES_QUERY = `
-    SELECT c.relname AS table_name,
-           c.relkind = 'p' AS is_partitioned
-    FROM pg_class c
-    JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = $1
-      AND c.relkind IN ('r', 'p')
-      AND NOT c.relispartition
-      AND c.relname NOT LIKE 'drizzle_%'
-      AND c.relname NOT LIKE 'rebase_%'
-    ORDER BY c.relname
-`;
-/**
-* Columns, with the catalog facts that say a column is not the user's to edit.
-*
-* `is_generated`/`is_identity` are read for that reason: a generated column
-* rejects any write, so a form that offers it is offering a field that always
-* errors. `character_maximum_length` is the declared `varchar(n)` bound —
-* already enforced by the database, and free to surface as validation.
-*/
-var COLUMNS_QUERY = `
-    SELECT
-        c.table_name,
-        c.column_name,
-        c.data_type,
-        c.udt_name,
-        c.is_nullable,
-        c.column_default,
-        c.ordinal_position,
-        c.is_generated,
-        c.is_identity,
-        c.identity_generation,
-        c.character_maximum_length,
-        c.numeric_precision,
-        c.numeric_scale,
-        (SELECT a.atttypmod FROM pg_attribute a
-         JOIN pg_class pc ON a.attrelid = pc.oid
-         WHERE pc.relname = c.table_name
-           AND a.attname = c.column_name
-           AND pc.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = c.table_schema)) as atttypmod
-    FROM information_schema.columns c
-    WHERE c.table_schema = $1
-    ORDER BY c.table_name, c.ordinal_position
-`;
-var ENUMS_QUERY = `
-    SELECT t.typname AS enum_name,
-           e.enumlabel AS enum_value,
-           e.enumsortorder AS sort_order
-    FROM pg_type t
-    JOIN pg_enum e ON t.oid = e.enumtypid
-    JOIN pg_namespace n ON t.typnamespace = n.oid
-    WHERE n.nspname = $1
-    ORDER BY t.typname, e.enumsortorder
-`;
-/**
-* Primary key columns, in key order.
-*
-* `ORDER BY k.ord` matters for composite keys: the position of a column inside
-* the key is what tells a two-column PK made of two foreign keys apart from an
-* ordinary composite key, and `= ANY(i.indkey)` (the shape this replaced)
-* returns catalog order instead.
-*/
-var PRIMARY_KEYS_QUERY = `
-    SELECT t.relname AS table_name,
-           a.attname AS column_name
-    FROM pg_index i
-    JOIN pg_class t ON t.oid = i.indrelid
-    JOIN pg_namespace n ON n.oid = t.relnamespace
-    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
-    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
-    WHERE i.indisprimary AND n.nspname = $1
-    ORDER BY t.relname, k.ord
-`;
-/**
-* Foreign keys, one row per referencing column, with the delete rule.
-*
-* Read from `pg_constraint` rather than through
-* `information_schema.constraint_column_usage`, which does not preserve the
-* pairing on a composite foreign key: it reports the cross product of the
-* constraint's columns, so a two-column FK comes back as four rows, two of them
-* pairing the wrong columns. `unnest(...) WITH ORDINALITY` on both sides joined
-* on the ordinal keeps each referencing column with the column it references.
-*
-* `confdeltype` is carried because `ON DELETE CASCADE` is the schema author
-* saying, in the database, that the child cannot outlive the parent — the one
-* unambiguous declaration of ownership a schema contains.
-*
-* Constraints declared on a *partition* are attributed to the partition root,
-* because that is the table this run generates a collection for. Pagila declares
-* `payment`'s three foreign keys on each monthly partition and none on the
-* parent, so reading `pg_constraint` at face value gives the `payment`
-* collection no relations at all. `pick = 1` then keeps one row per logical key,
-* preferring the root's own constraint when it has one, so a schema that
-* declares the key on the parent *and* inherits it onto 26 partitions does not
-* yield 27 copies of the same relation.
-*/
-var FOREIGN_KEYS_QUERY = `
-    WITH fk AS (
-        SELECT con.oid,
-               con.conname,
-               con.conrelid,
-               con.confrelid,
-               con.conkey,
-               con.confkey,
-               con.confdeltype,
-               COALESCE(pg_partition_root(con.conrelid), con.conrelid) AS root_oid,
-               row_number() OVER (
-                   PARTITION BY COALESCE(pg_partition_root(con.conrelid), con.conrelid),
-                                con.confrelid, con.conkey, con.confkey
-                   ORDER BY (con.conrelid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)) DESC,
-                            con.oid
-               ) AS pick
-        FROM pg_constraint con
-        JOIN pg_namespace n ON n.oid = con.connamespace
-        WHERE con.contype = 'f' AND n.nspname = $1
-    )
-    SELECT root.relname AS table_name,
-           sa.attname AS column_name,
-           tgt.relname AS foreign_table_name,
-           ta.attname AS foreign_column_name,
-           fk.conname AS constraint_name,
-           s.ord::int AS ordinal,
-           CASE fk.confdeltype
-               WHEN 'a' THEN 'NO ACTION'
-               WHEN 'r' THEN 'RESTRICT'
-               WHEN 'c' THEN 'CASCADE'
-               WHEN 'n' THEN 'SET NULL'
-               WHEN 'd' THEN 'SET DEFAULT'
-           END AS delete_rule
-    FROM fk
-    JOIN pg_class root ON root.oid = fk.root_oid
-    JOIN pg_class tgt ON tgt.oid = fk.confrelid
-    CROSS JOIN LATERAL unnest(fk.conkey) WITH ORDINALITY AS s(attnum, ord)
-    JOIN pg_attribute sa ON sa.attrelid = fk.conrelid AND sa.attnum = s.attnum
-    CROSS JOIN LATERAL unnest(fk.confkey) WITH ORDINALITY AS f(attnum, ord)
-    JOIN pg_attribute ta ON ta.attrelid = fk.confrelid AND ta.attnum = f.attnum
-    WHERE fk.pick = 1 AND s.ord = f.ord
-    ORDER BY root.relname, fk.conname, s.ord
-`;
-/**
-* Unique constraints and unique indexes, as ordered column lists.
-*
-* Indexes rather than constraints alone, because `CREATE UNIQUE INDEX` and
-* `ADD CONSTRAINT ... UNIQUE` produce the same guarantee and schemas use both.
-* Partial indexes (`indpred IS NOT NULL`) are excluded: they promise uniqueness
-* only over the rows matching their predicate, which is not the promise a
-* `validation: { unique: true }` field makes.
-*/
-var UNIQUE_CONSTRAINTS_QUERY = `
-    SELECT t.relname AS table_name,
-           ic.relname AS constraint_name,
-           -- ::text, because the driver has no parser for an array of \`name\`
-           -- and hands back the raw \`{a,b}\` literal as a string. Every consumer
-           -- here indexes and compares it as an array, and a string of that
-           -- shape fails those silently rather than loudly.
-           array_agg(a.attname::text ORDER BY k.ord) AS column_names
-    FROM pg_index i
-    JOIN pg_class t ON t.oid = i.indrelid
-    JOIN pg_class ic ON ic.oid = i.indexrelid
-    JOIN pg_namespace n ON n.oid = t.relnamespace
-    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
-    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
-    WHERE i.indisunique
-      AND NOT i.indisprimary
-      AND i.indpred IS NULL
-      AND n.nspname = $1
-      AND NOT t.relispartition
-    GROUP BY t.relname, ic.relname
-    ORDER BY t.relname, ic.relname
-`;
-/**
-* CHECK constraints, as the source text Postgres reproduces them from.
-*
-* `pg_get_constraintdef` output is normalized by the server — the parser in
-* {@link ./introspect-db-constraints.ts} reads that normalized form, not
-* whatever the author typed.
-*/
-var CHECK_CONSTRAINTS_QUERY = `
-    SELECT DISTINCT
-           root.relname AS table_name,
-           con.conname AS constraint_name,
-           pg_get_constraintdef(con.oid) AS definition
-    FROM pg_constraint con
-    JOIN pg_namespace n ON n.oid = con.connamespace
-    JOIN pg_class root ON root.oid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)
-    WHERE con.contype = 'c'
-      AND n.nspname = $1
-    ORDER BY root.relname, con.conname
-`;
-/**
-* `COMMENT ON TABLE` / `COMMENT ON COLUMN`, which is documentation the author
-* already wrote and which nothing downstream has ever read.
-*/
-var COMMENTS_QUERY = `
-    SELECT t.relname AS table_name,
-           a.attname AS column_name,
-           d.description AS comment
-    FROM pg_description d
-    JOIN pg_class t ON t.oid = d.objoid
-    JOIN pg_namespace n ON n.oid = t.relnamespace
-    LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = d.objsubid
-    WHERE n.nspname = $1
-      AND t.relkind IN ('r', 'p')
-      AND (d.objsubid = 0 OR a.attname IS NOT NULL)
-    ORDER BY t.relname, d.objsubid
-`;
-/**
-* Counts a table's rows, stopping once the answer can only be "more than
-* `limit`".
-*
-* Introspection asks this to tell a small reference table from a table that
-* merely looks like one (see `classifyTables`). `reltuples` would answer for
-* free but lies on a table that has never been analyzed — which is every table
-* in a database restored from a dump, i.e. exactly the case introspection meets
-* — and reports -1 there rather than an error, so the lie is silent.
-*
-* The subquery's LIMIT caps the work at `limit + 1` rows however large the
-* table is, so this stays cheap on a table with a billion rows.
-*/
-async function countRowsUpTo(client, schema, table, limit) {
-	const { rows } = await client.query(`SELECT count(*)::text AS count FROM (SELECT 1 FROM ${quoteRelation(schema, table)} LIMIT ${limit + 1}) probe`);
-	return Number(rows[0]?.count ?? 0);
-}
-/**
-* Reads everything the generator needs, in one pass.
-*
-* `rowCounts` is deliberately absent here: it costs a query per table and only
-* a handful of tables can possibly need it. The caller fills it in for the
-* candidates `lookupCandidates()` names.
-*/
-async function readSchemaMetadata(client, schema) {
-	const tables = await client.query(TABLES_QUERY, [schema]);
-	const columns = await client.query(COLUMNS_QUERY, [schema]);
-	const enumValues = await client.query(ENUMS_QUERY, [schema]);
-	const pks = await client.query(PRIMARY_KEYS_QUERY, [schema]);
-	const fks = await client.query(FOREIGN_KEYS_QUERY, [schema]);
-	const uniques = await client.query(UNIQUE_CONSTRAINTS_QUERY, [schema]);
-	const checks = await client.query(CHECK_CONSTRAINTS_QUERY, [schema]);
-	const comments = await client.query(COMMENTS_QUERY, [schema]);
-	const known = new Set(tables.rows.map((t) => t.table_name));
-	const scoped = (rows) => rows.filter((r) => known.has(r.table_name));
-	return {
-		schema,
-		tables: tables.rows,
-		columns: scoped(columns.rows),
-		enumValues: enumValues.rows,
-		pks: scoped(pks.rows),
-		fks: scoped(fks.rows).filter((fk) => known.has(fk.foreign_table_name)),
-		uniques: scoped(uniques.rows),
-		checks: scoped(checks.rows),
-		comments: scoped(comments.rows),
-		rowCounts: {}
-	};
-}
-//#endregion
+import { a as buildSearchColumnSpec, u as searchColumnStamps } from "./search-column-BM-GV6vH.js";
+import { DEFAULT_SEARCH_COLUMN, DEFAULT_SEARCH_LANGUAGE } from "@rebasepro/types";
+import { firstFreeKey, toPostgresIdentifier, toWireKey } from "@rebasepro/utils";
 //#region src/schema/introspect-db-naming.ts
 /**
 * Naming helpers shared by the introspection modules. These live apart from
@@ -495,6 +186,359 @@ function mapPgType(dataType) {
 	if (dt === "uuid") return "string";
 	return "string";
 }
+//#endregion
+//#region src/schema/introspect-db-storage.ts
+var literal = (value) => JSON.stringify(value);
+/** `character varying` → `varchar`, the spellings the planner's `columnType` uses. */
+var NUMBER_COLUMN_TYPE = {
+	"integer": "integer",
+	"bigint": "bigint",
+	"real": "real",
+	"double precision": "double precision"
+};
+/** A sequence default — `nextval('orders_id_seq'::regclass)`. */
+var SEQUENCE_DEFAULT = /^nextval\('([^']+)'::regclass\)$/;
+/**
+* Whether a `nextval` default names the sequence `SERIAL` would have made for
+* this column — the only one the planner can declare, because it declares the
+* column as `SERIAL` and lets Postgres name the sequence.
+*/
+var isConventionalSequence = (col, sequence) => {
+	return sequence.replace(/^.*\./, "").replace(/^"|"$/g, "") === serialSequenceName(col.table_name, col.column_name);
+};
+/**
+* The name Postgres gives a `SERIAL` column's sequence — `ChooseRelationName`
+* with the `seq` label: `<table>_<column>_seq`, and when that is over 63 bytes
+* the longer of the two names is shortened, one character at a time, until it
+* fits.
+*/
+function serialSequenceName(table, column) {
+	const available = 58;
+	let tableChars = table.length;
+	let columnChars = column.length;
+	while (tableChars + columnChars > available) if (tableChars > columnChars) tableChars--;
+	else columnChars--;
+	return `${table.slice(0, tableChars)}_${column.slice(0, columnChars)}_seq`;
+}
+/**
+* The `isId` (and `columnType`) a single-column primary key needs.
+*
+* `isId: "increment"` is an identity column, and only an INTEGER one. A serial
+* key — an integer with a `nextval` default — is `SERIAL`/`BIGSERIAL`, declared
+* through `columnType` beside `isId: "manual"`. A uuid key is `"uuid"` only when
+* the database generates it; a key with no default is `"manual"`, which keeps
+* the planner from inventing one.
+*/
+function primaryKeyStorage(col, propType) {
+	const dataType = col.data_type.toLowerCase();
+	const fallback = col.column_default?.trim();
+	if (propType === "number") {
+		if (col.is_identity === "YES") {
+			if (dataType === "integer") return { keys: [`isId: ${literal("increment")}`] };
+			return {
+				keys: [`isId: ${literal("increment")}`],
+				note: `"${col.column_name}" is a ${dataType} identity key; \`isId: "increment"\` is always INTEGER, so a push would plan a narrowing type change (and ask before applying it).`
+			};
+		}
+		const sequence = fallback ? SEQUENCE_DEFAULT.exec(fallback) : null;
+		if (sequence) {
+			const serial = dataType === "bigint" ? "bigserial" : dataType === "integer" ? "serial" : void 0;
+			if (serial && isConventionalSequence(col, sequence[1])) return { keys: [`isId: ${literal("manual")}`, `columnType: ${literal(serial)}`] };
+			return {
+				keys: [`isId: ${literal("manual")}`, ...numberColumnType(dataType)],
+				note: `"${col.column_name}" takes its value from the sequence ${sequence[1]}, which no property can declare; a push would plan dropping that default.`
+			};
+		}
+		if (fallback) return { keys: [`isId: ${literal(`sql\`${fallback}\``)}`, ...numberColumnType(dataType)] };
+		return { keys: [`isId: ${literal("manual")}`, ...numberColumnType(dataType)] };
+	}
+	if (dataType === "uuid") {
+		if (fallback === "gen_random_uuid()") return { keys: [`isId: ${literal("uuid")}`] };
+		if (fallback) return { keys: [`isId: ${literal(`sql\`${fallback}\``)}`, `columnType: ${literal("uuid")}`] };
+		return { keys: [`isId: ${literal("manual")}`, `columnType: ${literal("uuid")}`] };
+	}
+	const strategy = fallback ? `sql\`${fallback}\`` : "manual";
+	const stored = stringStorage(col);
+	return {
+		keys: [`isId: ${literal(strategy)}`, ...stored.keys],
+		note: stored.note
+	};
+}
+/** `columnType` for a number column the planner would otherwise make NUMERIC. */
+function numberColumnType(dataType) {
+	const mapped = NUMBER_COLUMN_TYPE[dataType];
+	return mapped ? [`columnType: ${literal(mapped)}`] : [];
+}
+/** The keys a `string` column needs; the bound itself is emitted as `validation.max`. */
+function stringStorage(col) {
+	switch (col.data_type.toLowerCase()) {
+		case "text": return { keys: [] };
+		case "character varying":
+			if (typeof col.character_maximum_length === "number" && col.character_maximum_length > 0) return { keys: [`columnType: ${literal("varchar")}`] };
+			return {
+				keys: [`columnType: ${literal("varchar")}`],
+				note: `"${col.column_name}" is a varchar with no length; the planner always writes one (255 unless \`validation.max\` says otherwise), so a push would plan a narrowing type change.`
+			};
+		case "character": return { keys: [`columnType: ${literal("char")}`] };
+		case "uuid": return { keys: [`columnType: ${literal("uuid")}`] };
+		default: return {
+			keys: [],
+			note: `"${col.column_name}" is ${col.data_type === "USER-DEFINED" ? col.udt_name : col.data_type}, which no property type stores; it is read as text, and a push would plan converting the column to text.`
+		};
+	}
+}
+/**
+* The keys a non-key column needs, for the property type introspection chose.
+*
+* `enumTypeName` is the type the planner would name for this column
+* (`<table>_<column>`, cut to 63 bytes); an enum column whose type is called
+* anything else cannot be declared, and the note says how to rename it.
+*/
+function columnStorage(col, propType, context) {
+	const dataType = col.data_type.toLowerCase();
+	if (context.isEnumColumn) {
+		if (col.udt_name === context.enumTypeName) return { keys: [] };
+		return {
+			keys: [],
+			note: context.enumTypeShared ? `"${col.column_name}" uses the enum type "${col.udt_name}", which other columns share; Rebase gives each column its own type (<table>_<column>), so a push would plan "${context.enumTypeName}" and a conversion Postgres cannot cast.` : `"${col.column_name}" uses the enum type "${col.udt_name}", and Rebase names a column's enum type <table>_<column>. Rename it before pushing: ALTER TYPE "${col.udt_name}" RENAME TO "${context.enumTypeName}";`
+		};
+	}
+	switch (propType) {
+		case "number": {
+			if (dataType === "numeric") {
+				const keys = [];
+				if (typeof col.numeric_precision === "number") keys.push(`precision: ${col.numeric_precision}`);
+				if (typeof col.numeric_precision === "number" && typeof col.numeric_scale === "number") keys.push(`scale: ${col.numeric_scale}`);
+				return { keys };
+			}
+			if (dataType === "smallint") return {
+				keys: [`columnType: ${literal("integer")}`],
+				note: `"${col.column_name}" is smallint, which no \`columnType\` names; it is declared integer, so a push widens it (every value survives).`
+			};
+			const mapped = numberColumnType(dataType);
+			if (mapped.length > 0) return { keys: mapped };
+			return {
+				keys: [],
+				note: `"${col.column_name}" is ${col.data_type}, which no \`columnType\` names; it is declared numeric, and a push would plan converting it.`
+			};
+		}
+		case "string": return stringStorage(col);
+		case "date": switch (dataType) {
+			case "timestamp with time zone": return { keys: [] };
+			case "date": return { keys: [`columnType: ${literal("date")}`] };
+			case "time without time zone": return { keys: [`columnType: ${literal("time")}`] };
+			default: return {
+				keys: [],
+				note: `"${col.column_name}" is ${col.data_type}; a date property stores timestamptz, date or time, so a push would plan converting it to timestamptz (and ask before applying it).`
+			};
+		}
+		case "map": return dataType === "json" ? { keys: [`columnType: ${literal("json")}`] } : { keys: [] };
+		default: return { keys: [] };
+	}
+}
+/**
+* The `columnType` an array column needs, or a note when its element type is
+* not one the planner stores natively.
+*
+* Only `text[]`, `integer[]`, `boolean[]` and `numeric[]` are. Reading
+* `bigint[]` as `integer[]` — what this used to do — planned a narrowing.
+*/
+function arrayStorage(col) {
+	switch (col.udt_name) {
+		case "_text": return {
+			columnType: "text[]",
+			innerType: "string"
+		};
+		case "_int4": return {
+			columnType: "integer[]",
+			innerType: "number"
+		};
+		case "_bool": return {
+			columnType: "boolean[]",
+			innerType: "boolean"
+		};
+		case "_numeric": return {
+			columnType: "numeric[]",
+			innerType: "number"
+		};
+		default: {
+			const element = col.udt_name.replace(/^_/, "");
+			return {
+				innerType: "string",
+				note: `"${col.column_name}" is an array of ${element}; arrays are stored as text[], integer[], boolean[] or numeric[] (anything else as jsonb), so a push would plan converting it.`
+			};
+		}
+	}
+}
+/**
+* A column default as a `defaultValue`, when it is a literal a property can carry.
+*
+* `undefined` when there is no default to carry, or when the default is one the
+* generator expresses another way (`now()` is `autoValue`, a key's default is
+* its `isId`). `{ note }` when there is a default and no property can say it —
+* a push would plan dropping it.
+*/
+function literalDefaultOf(col, propType) {
+	const raw = col.column_default?.trim();
+	if (!raw) return void 0;
+	if (/^(now\(\)|CURRENT_TIMESTAMP)$/i.test(raw)) return void 0;
+	const quoted = /^'((?:[^']|'')*)'(?:::[\w\s."[\]]+)?$/.exec(raw);
+	const unquoted = quoted ? quoted[1].replace(/''/g, "'") : void 0;
+	switch (propType) {
+		case "string":
+			if (unquoted !== void 0) return { source: literal(unquoted) };
+			break;
+		case "number": {
+			const text = unquoted ?? raw.replace(/^\((.*)\)$/, "$1").replace(/::[\w\s]+$/, "");
+			if (/^-?\d+(\.\d+)?$/.test(text) && Number.isFinite(Number(text))) return { source: String(Number(text)) };
+			break;
+		}
+		case "boolean":
+			if (/^true$/i.test(raw)) return { source: "true" };
+			if (/^false$/i.test(raw)) return { source: "false" };
+			break;
+		case "map":
+			if (unquoted !== void 0) try {
+				const parsed = JSON.parse(unquoted);
+				if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return { source: JSON.stringify(parsed) };
+			} catch {}
+			break;
+		default: break;
+	}
+	return { note: `"${col.column_name}" defaults to ${raw}, which no \`defaultValue\` can express; a push would plan dropping that default.` };
+}
+/** `ON DELETE` as the relation's `onDelete`, when it is not the default the planner would choose. */
+function onDeleteOf(fk, required) {
+	const rule = fk.delete_rule?.toUpperCase();
+	if (!rule) return void 0;
+	if (rule === (required ? "RESTRICT" : "SET NULL")) return void 0;
+	return rule.toLowerCase();
+}
+//#endregion
+//#region src/schema/introspect-db-search.ts
+/**
+* A collection's `search` block, read back out of the column it built.
+*
+* A Rebase search column is `tsvector GENERATED ALWAYS AS (…) STORED`, stamped
+* with a fingerprint of the expression in its `COMMENT`. Introspection used to
+* emit it as an ordinary read-only string property, which the planner makes a
+* `text` column — so the first push after adopting a Rebase database planned
+* `ALTER COLUMN "search_vector" TYPE text … DROP EXPRESSION`, and search was
+* gone for whoever approved it.
+*
+* Reading the block back is a guess checked by the stamp: the deparsed
+* expression names each field's column, weight and language, which is enough
+* to write a candidate block; the candidate is then compiled by the very code
+* that built the column, and kept only if its fingerprint is the one the column
+* carries. A block that does not reproduce the stamp is not emitted at all —
+* the note says so — because a wrong one would rebuild the column differently.
+*
+* `mode` and `fuzzyThreshold` act at query time and are stored nowhere, so they
+* come back as their defaults.
+*/
+/** One `setweight(to_tsvector('<lang>'::regconfig, <text>), '<W>'::"char")`, deparsed. */
+var SEGMENT = /setweight\(to_tsvector\('((?:[^']|'')+)'::regconfig, ([\s\S]+?)\), '([A-D])'::"char"\)/g;
+/** A property with the column's shape, for the candidate block to resolve against. */
+function propertyFor(col) {
+	if (col.data_type === "text" || col.data_type === "character varying" || col.data_type === "character") return {
+		name: col.column_name,
+		type: "string",
+		columnName: col.column_name
+	};
+	if (col.udt_name === "_text") return {
+		name: col.column_name,
+		type: "array",
+		columnName: col.column_name,
+		of: {
+			name: col.column_name,
+			type: "string"
+		}
+	};
+	if (col.data_type === "jsonb") return {
+		name: col.column_name,
+		type: "map",
+		columnName: col.column_name,
+		keyValue: true
+	};
+}
+/**
+* The search block a table's stamped generated columns were built from, or a
+* note saying why it could not be read back.
+*/
+function reconstructSearchBlock(input) {
+	const stamped = input.columns.filter((col) => col.is_generated === "ALWAYS" && (input.comments.get(col.column_name) ?? "").startsWith("rebase:search:v1:"));
+	const main = stamped.find((col) => col.udt_name === "tsvector");
+	if (!main) return { columns: /* @__PURE__ */ new Set() };
+	const fuzzy = stamped.find((col) => col.column_name === `${main.column_name}_text`);
+	const columns = new Set(stamped.map((col) => col.column_name));
+	const unreadable = (why) => ({
+		columns,
+		note: `"${main.column_name}" is a Rebase search column whose \`search\` block could not be read back (${why}). Declare the block again before pushing — without it a push plans dropping the column.`
+	});
+	const expression = main.generation_expression ?? "";
+	const byColumn = new Map(input.columns.map((col) => [col.column_name, col]));
+	const fields = [];
+	let language;
+	let unaccent = false;
+	for (const [, lang, inner, weight] of expression.matchAll(SEGMENT)) {
+		language ??= lang.replace(/''/g, "'");
+		if (lang.replace(/''/g, "'") !== language) return unreadable("its fields use different languages");
+		if (inner.includes("rebase_search_unaccent")) unaccent = true;
+		const column = [...inner.matchAll(/"?([A-Za-z_][A-Za-z0-9_$]*)"?/g)].map((m) => m[1]).find((name) => byColumn.has(name) && !columns.has(name));
+		if (!column) return unreadable("a field reads no column of this table");
+		const key = input.keyByColumn.get(column);
+		if (!key) return unreadable(`the column "${column}" is not a property`);
+		const jsonPath = [...inner.matchAll(/(?:->|#>)\s*'([^']+)'/g)].flatMap((m) => m[1].replace(/^\{|\}$/g, "").split(","));
+		fields.push({
+			path: [key, ...jsonPath].join("."),
+			weight
+		});
+	}
+	if (fields.length === 0 || !language) return unreadable("its expression is not one Rebase writes");
+	const search = {
+		...main.column_name !== DEFAULT_SEARCH_COLUMN ? { column: main.column_name } : {},
+		...language !== DEFAULT_SEARCH_LANGUAGE ? { language } : {},
+		...unaccent ? { unaccent: true } : {},
+		...fuzzy ? { fuzzy: true } : {},
+		fields: fields.map((f) => ({
+			path: f.path,
+			weight: f.weight
+		}))
+	};
+	const properties = {};
+	for (const [column, key] of input.keyByColumn) {
+		const col = byColumn.get(column);
+		const prop = col ? propertyFor(col) : void 0;
+		if (prop) properties[key] = prop;
+	}
+	const candidate = {
+		slug: input.table,
+		name: input.table,
+		table: input.table,
+		...input.schema !== "public" ? { schema: input.schema } : {},
+		properties,
+		search
+	};
+	let fingerprints;
+	try {
+		const spec = buildSearchColumnSpec(candidate);
+		if (!spec) return unreadable("no block compiles from it");
+		fingerprints = new Map(searchColumnStamps(spec).map((stamp) => [stamp.column, stamp.fingerprint]));
+	} catch (err) {
+		return unreadable(err instanceof Error ? err.message : String(err));
+	}
+	for (const col of stamped) if (fingerprints.get(col.column_name) !== input.comments.get(col.column_name)) return unreadable("the block read from its expression does not reproduce the column's stamp");
+	return {
+		columns,
+		block: `\n    search: {\n        ${[
+			...search.column ? [`column: ${JSON.stringify(search.column)}`] : [],
+			...search.language ? [`language: ${JSON.stringify(search.language)}`] : [],
+			...search.unaccent ? ["unaccent: true"] : [],
+			...search.fuzzy ? ["fuzzy: true"] : [],
+			`fields: [\n${fields.map((f) => `            { path: ${JSON.stringify(f.path)}, weight: ${JSON.stringify(f.weight)} }`).join(",\n")}\n        ]`
+		].join(",\n        ")}\n    },`
+	};
+}
 /**
 * A timestamp the database maintains: a temporal column defaulting to the
 * transaction clock.
@@ -908,6 +952,34 @@ function deriveListProperties(propertiesOrder, hidden = /* @__PURE__ */ new Set(
 * no process.exit.  It is imported by introspect-db.ts (the CLI entry-point)
 * and consumed directly by tests.
 */
+/**
+* Why a table keyed on several columns is not generated as a collection, or
+* `undefined` when it is.
+*
+* Several `isId` properties are one composite key, and the planner builds that
+* table under the same `PRIMARY KEY (a, b)` — so such a table round-trips when
+* two things hold:
+*
+* - **Every key column can carry `isId`,** which exists on string and number
+*   properties only. Read from the column's SQL type, not a data sample: a
+*   `line_no` holding only 1s is not a boolean. A key with a column of another
+*   type — pagila's `payment` is keyed on a timestamp too — can be marked on
+*   some of its columns only, and those would be read as the whole key.
+* - **Nothing points at it.** A foreign key into it, or a junction, is a link
+*   into a composite key, which the planner refuses: the relation has one
+*   column to point with.
+*/
+function compositeKeySkipReason(meta, allFks) {
+	if (meta.pks.length < 2) return void 0;
+	const unmarkable = meta.pks.filter((pk) => {
+		const column = meta.columns.find((c) => c.column_name === pk);
+		const type = column ? mapPgType(column.data_type) : void 0;
+		return type !== "string" && type !== "number";
+	});
+	if (unmarkable.length > 0) return `its key column${unmarkable.length > 1 ? "s" : ""} ${unmarkable.map((c) => `"${c}"`).join(", ")} cannot carry \`isId\`, which a string or number property takes`;
+	const referencing = [...new Set(allFks.filter((fk) => fk.foreign_table_name === meta.name && fk.table_name !== meta.name).map((fk) => fk.table_name))];
+	if (referencing.length > 0) return `${referencing.map((t) => `"${t}"`).join(", ")} point${referencing.length > 1 ? "" : "s"} at it, and a link cannot point at a composite key`;
+}
 var IRREGULAR_SINGULARS = {
 	people: "person",
 	children: "child",
@@ -1265,6 +1337,8 @@ function withAdminOptions(extra, entries, emitAdmin = true) {
 	if (extra.includes("admin: {")) return extra.replace("admin: {", `admin: {\n${block},`);
 	return `${extra}\n            admin: {\n${block}\n            },`;
 }
+/** A SQL string literal. */
+var quoteSqlString = (value) => `'${value.replace(/'/g, "''")}'`;
 /** A TypeScript string literal, escaped. */
 function quote(value) {
 	return JSON.stringify(value);
@@ -1369,6 +1443,9 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 	};
 	let propsOutput = "";
 	let relationsOutput = "";
+	/** What the planner will not reproduce exactly, column by column. */
+	const fileNotes = [];
+	const skippedTables = context.skippedTables ?? /* @__PURE__ */ new Set();
 	const orderEntries = [];
 	const propertyBlocks = /* @__PURE__ */ new Map();
 	/**
@@ -1386,25 +1463,45 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 	const hiddenFromCollection = /* @__PURE__ */ new Set();
 	let columnIndex = 0;
 	const isCompositePk = meta.pks.length > 1;
+	/**
+	* The property type a column is generated as, with what the data sample
+	* adds to it. A column of a composite key keeps its SQL type's reading:
+	* it carries `isId`, which only a string or number property takes, and a
+	* key column holding only 1s and 0s is still a key, not a boolean.
+	*/
+	const propertyTypeOf = (col) => {
+		const isEnumColumn = col.data_type === "USER-DEFINED" && enumMap.get(col.udt_name) !== void 0;
+		const propType = isEnumColumn ? "string" : col.udt_name === "vector" ? "vector" : mapPgType(col.data_type);
+		if (isEnumColumn || !sampleData || sampleData.length === 0 || isCompositePk && meta.pks.includes(col.column_name)) return {
+			propType,
+			finalPropType: propType,
+			inferenceExtra: ""
+		};
+		const values = sampleData.map((r) => r[col.column_name]);
+		const inferred = inferPropertyFromData(col.column_name, col.data_type, propType, values, meta.pks.includes(col.column_name), emitAdmin);
+		return {
+			propType,
+			finalPropType: inferred.propType || propType,
+			inferenceExtra: inferred.extra || ""
+		};
+	};
+	const compositeKeyMarkable = isCompositePk && meta.pks.every((pk) => {
+		const keyColumn = meta.columns.find((c) => c.column_name === pk);
+		if (!keyColumn) return false;
+		const { finalPropType } = propertyTypeOf(keyColumn);
+		return finalPropType === "string" || finalPropType === "number";
+	});
 	for (const col of meta.columns) {
+		if (col.is_generated === "ALWAYS" && (columnComments.get(col.column_name) ?? "").startsWith("rebase:search:v1:")) continue;
 		if (meta.fks.some((fk) => fk.column_name === col.column_name) && !meta.pks.includes(col.column_name)) continue;
 		const currentIndex = columnIndex++;
 		const propertyKey = firstFreeKey([toWireKey(col.column_name), col.column_name], propertyBlocks);
 		keyByColumn.set(col.column_name, propertyKey);
 		const colEnumValues = enumMap.get(col.udt_name);
 		const isEnumColumn = col.data_type === "USER-DEFINED" && colEnumValues !== void 0;
-		const isVectorColumn = col.udt_name === "vector";
-		const propType = isEnumColumn ? "string" : isVectorColumn ? "vector" : mapPgType(col.data_type);
 		let extra = "";
 		const colNameLower = col.column_name.toLowerCase();
-		let finalPropType = propType;
-		let inferenceExtra = "";
-		if (!isEnumColumn && sampleData && sampleData.length > 0) {
-			const values = sampleData.map((r) => r[col.column_name]);
-			const inferred = inferPropertyFromData(col.column_name, col.data_type, propType, values, meta.pks.includes(col.column_name), emitAdmin);
-			if (inferred.propType) finalPropType = inferred.propType;
-			if (inferred.extra) inferenceExtra = inferred.extra;
-		}
+		const { propType, finalPropType, inferenceExtra } = propertyTypeOf(col);
 		const columnChecks = tableChecks?.get(col.column_name);
 		if (isEnumColumn && colEnumValues) {
 			const enumEntries = colEnumValues.map((v) => `{ id: ${quote(v)}, label: ${quote(humanize(v))} }`).join(", ");
@@ -1412,6 +1509,13 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 		} else if (columnChecks?.enumValues && !inferenceExtra.includes("enum:") && propType === "string") {
 			const enumEntries = columnChecks.enumValues.map((v) => `{ id: ${quote(v)}, label: ${quote(humanize(v))} }`).join(", ");
 			extra += `\n            enum: [${enumEntries}],`;
+			const enumType = toPostgresIdentifier(`${tableName}_${col.column_name}`);
+			const labels = columnChecks.enumValues.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ");
+			const check = (context.metadata?.checks ?? []).find((c) => c.table_name === tableName && c.definition.includes(col.column_name));
+			const table = `"${tableName}"`;
+			const column = `"${col.column_name}"`;
+			const restoreDefault = literalDefaultOf(col, "string");
+			fileNotes.push(`"${col.column_name}" is text with CHECK (… IN …), declared here as an \`enum\`, which Rebase stores as the enum type "${enumType}". Convert the column before pushing: CREATE TYPE "${enumType}" AS ENUM (${labels}); ALTER TABLE ${table} ${check ? `DROP CONSTRAINT "${check.constraint_name}", ` : ""}ALTER COLUMN ${column} DROP DEFAULT, ALTER COLUMN ${column} TYPE "${enumType}" USING ${column}::"${enumType}"` + (restoreDefault && "source" in restoreDefault ? `, ALTER COLUMN ${column} SET DEFAULT ${quoteSqlString(JSON.parse(restoreDefault.source))}` : "") + "; — or delete the `enum` to keep the column as it is.");
 		}
 		if (finalPropType === "date") {
 			if (colNameLower === "created_at" || colNameLower === "createdat") {
@@ -1428,16 +1532,10 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 			}
 		}
 		if (finalPropType === "array" && !inferenceExtra.includes("of: {")) {
-			let innerType = "string";
-			let colType = "";
-			if (col.udt_name.startsWith("_")) {
-				innerType = mapPgType(col.udt_name.substring(1));
-				if (innerType === "string") colType = "text[]";
-				else if (innerType === "number") colType = col.udt_name === "_numeric" ? "numeric[]" : "integer[]";
-				else if (innerType === "boolean") colType = "boolean[]";
-			}
-			if (colType) extra += `\n            columnType: ${quote(colType)},`;
-			extra += `\n            of: { name: ${quote(`${humanize(col.column_name)} Item`)}, type: ${quote(innerType)} },`;
+			const stored = arrayStorage(col);
+			if (stored.columnType) extra += `\n            columnType: ${quote(stored.columnType)},`;
+			if (stored.note) fileNotes.push(stored.note);
+			extra += `\n            of: { name: ${quote(`${humanize(col.column_name)} Item`)}, type: ${quote(stored.innerType)} },`;
 		} else if (finalPropType === "map" && !inferenceExtra.includes("keyValue: true") && !inferenceExtra.includes("properties: {")) extra += "\n            keyValue: true,";
 		if (finalPropType === "string" && !isEnumColumn && !inferenceExtra) {
 			const isUrl = colNameLower.endsWith("_url") || colNameLower.endsWith("_uri") || colNameLower.endsWith("_link");
@@ -1451,6 +1549,25 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 			extra += inferenceExtra;
 			if (!extra.endsWith(",")) extra += ",";
 		}
+		if (!meta.pks.includes(col.column_name) && !isReadOnlyColumn(col)) {
+			const enumTypeName = toPostgresIdentifier(`${tableName}_${col.column_name}`);
+			const enumTypeShared = isEnumColumn && (context.metadata?.columns ?? meta.columns).filter((other) => other.udt_name === col.udt_name && other.data_type === "USER-DEFINED").length > 1;
+			const stored = finalPropType === "array" ? { keys: [] } : columnStorage(col, finalPropType, {
+				isEnumColumn,
+				enumTypeName,
+				enumTypeShared
+			});
+			for (const key of stored.keys) {
+				const name = key.slice(0, key.indexOf(":"));
+				if (!hasGeneratedKey(extra, name) && !hasGeneratedKey(inferenceExtra, name)) extra += `\n            ${key},`;
+			}
+			if (stored.note) fileNotes.push(stored.note);
+			if (!hasGeneratedKey(extra, "autoValue") && !hasGeneratedKey(extra, "defaultValue")) {
+				const fallback = literalDefaultOf(col, finalPropType);
+				if (fallback && "source" in fallback) extra += `\n            defaultValue: ${fallback.source},`;
+				else if (fallback) fileNotes.push(fallback.note);
+			}
+		}
 		const declaredValidation = [];
 		if (finalPropType === "string" && typeof col.character_maximum_length === "number" && col.character_maximum_length > 0 && !hasGeneratedKey(extra, "max")) declaredValidation.push(`max: ${col.character_maximum_length}`);
 		if (columnChecks) {
@@ -1478,16 +1595,30 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 		const columnComment = columnComments.get(col.column_name);
 		if (columnComment) extra = `\n            description: ${quote(columnComment)},${extra}`;
 		if (meta.pks.includes(col.column_name)) {
-			if (isCompositePk) extra += `\n            // Part of composite primary key (${commentText(meta.pks.join(", "))})`;
-			else if (finalPropType === "number" && !inferenceExtra.includes("isId:")) extra += "\n            isId: \"increment\",";
-			else if (col.data_type.toLowerCase() === "uuid" && !inferenceExtra.includes("isId:")) extra += "\n            isId: \"uuid\",";
-			else if (!inferenceExtra.includes("isId:")) extra += "\n            isId: \"uuid\", // Verify if this is a UUID or CUID";
+			if (isCompositePk) {
+				extra += `\n            // Part of composite primary key (${commentText(meta.pks.join(", "))})`;
+				if (compositeKeyMarkable && !inferenceExtra.includes("isId:")) {
+					const stored = primaryKeyStorage(col, finalPropType);
+					for (const key of stored.keys) {
+						const name = key.slice(0, key.indexOf(":"));
+						if (!hasGeneratedKey(extra, name)) extra += `\n            ${key},`;
+					}
+					if (stored.note) fileNotes.push(stored.note);
+				}
+			} else if (!inferenceExtra.includes("isId:")) {
+				const stored = primaryKeyStorage(col, finalPropType);
+				for (const key of stored.keys) {
+					const name = key.slice(0, key.indexOf(":"));
+					if (!hasGeneratedKey(extra, name)) extra += `\n            ${key},`;
+				}
+				if (stored.note) fileNotes.push(stored.note);
+			}
 		}
 		if (finalPropType === "vector") {
 			const dims = col.atttypmod && col.atttypmod > 0 ? col.atttypmod : 1536;
 			extra += `\n            dimensions: ${dims},`;
 		}
-		if (col.is_nullable === "NO" && !meta.pks.includes(col.column_name) && !col.column_default && !isReadOnlyColumn(col)) if (extra.includes("validation: {")) extra = extra.replace("validation: {", "validation: {\n                required: true,");
+		if (col.is_nullable === "NO" && !meta.pks.includes(col.column_name) && !isReadOnlyColumn(col)) if (extra.includes("validation: {")) extra = extra.replace("validation: {", "validation: {\n                required: true,");
 		else extra += "\n            validation: {\n                required: true\n            },";
 		const humanName = humanize(col.column_name);
 		orderEntries.push({
@@ -1510,6 +1641,7 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 	}
 	for (const fk of meta.fks) {
 		const targetTableName = fk.foreign_table_name;
+		if (skippedTables.has(targetTableName)) continue;
 		if (!joinTables.has(targetTableName)) {
 			const stripped = toWireKey(fk.column_name.replace(/_id$/, ""));
 			const relName = firstFreeKey([
@@ -1530,27 +1662,47 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 			});
 			const targetCollectionCamel = importCollection(targetTableName);
 			const relHumanName = humanize(relName);
+			const required = meta.columns.find((c) => c.column_name === fk.column_name)?.is_nullable === "NO";
+			const onDelete = onDeleteOf(fk, required);
+			const requiredLine = required ? "\n            validation: { required: true }," : "";
+			const onDeleteLine = onDelete ? `,\n                onDelete: ${quote(onDelete)}` : "";
 			propertyBlocks.set(relName, `
         ${propKey(relName)}: {
             name: ${quote(relHumanName)},
-            type: "relation",
+            type: "relation",${requiredLine}
             // mapped from foreign key: ${commentText(fk.column_name)} -> ${commentText(targetTableName)}(${commentText(fk.foreign_column_name)})
             relation: {
                 kind: "belongsTo",
                 target: ${relationTarget(targetCollectionCamel)},
-                localKey: ${quote(fk.column_name)}
+                localKey: ${quote(fk.column_name)}${onDeleteLine}
             }
         },`);
 		}
 	}
-	const inverseFks = allFks.filter((fk) => fk.foreign_table_name === tableName && !joinTables.has(fk.table_name));
+	/**
+	* A name for an entry in the `relations` array that no property and no
+	* earlier entry has taken.
+	*
+	* Relations and properties share one namespace — a relation is found by
+	* name — so a `belongsTo` property called `series` beside a many-to-many
+	* also called `series` left one of them unreachable: the planner resolved
+	* the property's name to the many-to-many, planned no `series_id` column,
+	* and the first push dropped it.
+	*/
+	const usedRelationNames = /* @__PURE__ */ new Set();
+	const relationNameFor = (preferred, fallback) => {
+		const name = firstFreeKey([preferred, fallback], { has: (key) => propertyBlocks.has(key) || usedRelationNames.has(key) });
+		usedRelationNames.add(name);
+		return name;
+	};
+	const inverseFks = allFks.filter((fk) => fk.foreign_table_name === tableName && !joinTables.has(fk.table_name) && !skippedTables.has(fk.table_name));
 	for (const fk of inverseFks) {
 		const sourceTableName = fk.table_name;
 		const targetCollectionCamel = importCollection(sourceTableName);
 		relationsOutput += `
         {
             kind: "hasMany",
-            relationName: ${quote(sourceTableName)},
+            relationName: ${quote(relationNameFor(sourceTableName, `${sourceTableName}_by_${fk.column_name}`))},
             target: ${relationTarget(targetCollectionCamel)},
             // the ${commentText(sourceTableName)}.${commentText(fk.column_name)} FK points back here
             foreignKeyOnTarget: ${quote(fk.column_name)}
@@ -1564,7 +1716,11 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 		const jtMeta = tablesMap.get(jt);
 		if (!jtMeta) continue;
 		const joinFks = jtMeta.fks;
-		const selfRefFks = joinFks.filter((fk) => fk.foreign_table_name === tableName);
+		const keyPosition = (fk) => {
+			const position = jtMeta.pks.indexOf(fk.column_name);
+			return position === -1 ? Number.MAX_SAFE_INTEGER : position;
+		};
+		const selfRefFks = joinFks.filter((fk) => fk.foreign_table_name === tableName).sort((a, b) => keyPosition(a) - keyPosition(b));
 		if (selfRefFks.length === 2) {
 			const thisFk = selfRefFks[0];
 			const otherFk = selfRefFks[1];
@@ -1572,7 +1728,7 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 			relationsOutput += `
         {
             kind: "manyToMany",
-            relationName: ${quote(relPropName)},
+            relationName: ${quote(relationNameFor(relPropName, `${relPropName}_${jt}`))},
             target: ${relationTarget(toCollectionVarName(tableName))},
             through: {
                 table: ${quote(jt)},
@@ -1583,7 +1739,14 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 			continue;
 		}
 		const otherFk = joinFks.find((fk) => fk.foreign_table_name !== tableName);
-		if (otherFk) {
+		const leadingTable = joinFks.find((fk) => fk.column_name === jtMeta.pks[0])?.foreign_table_name;
+		const sortsFirst = otherFk ? [tableName, otherFk.foreign_table_name].sort()[0] : tableName;
+		const declareHere = !leadingTable || leadingTable === sortsFirst || leadingTable === tableName;
+		if (otherFk && !declareHere) relationsOutput += `
+        // The many-to-many with ${commentText(otherFk.foreign_table_name)} through ${commentText(jt)} is declared on
+        // ${commentText(otherFk.foreign_table_name)} only: declaring it here too would re-key ${commentText(jt)}
+        // from (${commentText(jtMeta.pks.join(", "))}) on the next push.`;
+		if (otherFk && declareHere && !skippedTables.has(otherFk.foreign_table_name)) {
 			const targetTableName = otherFk.foreign_table_name;
 			const targetCollectionCamel = importCollection(targetTableName);
 			const thisFk = joinFks.find((fk) => fk.foreign_table_name === tableName);
@@ -1591,11 +1754,20 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 			relationsOutput += `
         {
             kind: "manyToMany",
-            relationName: ${quote(targetTableName)},
+            relationName: ${quote(relationNameFor(targetTableName, `${targetTableName}_via_${jt}`))},
             target: ${relationTarget(targetCollectionCamel)},${throughCode}
         },`;
 		}
 	}
+	const search = reconstructSearchBlock({
+		schema: context.metadata?.schema ?? "public",
+		table: tableName,
+		columns: meta.columns,
+		comments: columnComments,
+		keyByColumn
+	});
+	if (search.note) fileNotes.push(search.note);
+	const searchBlock = search.block ?? "";
 	const relationsBlock = relationsOutput ? `\n    relations: [${relationsOutput}\n    ],` : "";
 	const sortedPropertiesOrder = sortPropertiesOrder(orderEntries);
 	for (const key of sortedPropertiesOrder) propsOutput += propertyBlocks.get(key) || "";
@@ -1622,16 +1794,18 @@ function generateCollectionFile(tableName, meta, allFks, joinTables, tablesMap,
 	const pgSchema = context.metadata?.schema;
 	const schemaBlock = pgSchema && pgSchema !== "public" ? `\n    schema: ${quote(pgSchema)},` : "";
 	const classificationNote = classification && classification.role !== "entity" ? `\n// Introspected as a ${commentText(classification.role)}: ${commentText(classification.reason)}.\n` : "";
+	for (const note of fileNotes) context.notes?.push(`${tableName}: ${note}`);
+	const storageNote = fileNotes.length > 0 ? `\n// ⚠ Not reproduced exactly by \`rebase db push\` — read before pushing:\n${fileNotes.map((n) => `//   - ${commentText(n)}`).join("\n")}\n` : "";
 	const collectionVarName = toCollectionVarName(tableName);
 	const [open, close] = builder === "annotation" ? [`const ${collectionVarName}: PostgresCollectionConfig = {`, "};"] : [`const ${collectionVarName} = defineCollection({`, "});"];
 	const importLines = Array.from(imports);
 	return `${[...importLines.filter((line) => !line.includes("from \"./")), ...importLines.filter((line) => line.includes("from \"./"))].join("\n")}
-${classificationNote}
+${classificationNote}${storageNote}
 ${open}
     name: ${quote(collectionName)},
     singularName: ${quote(singular)},
     slug: ${quote(tableName)},
-    table: ${quote(tableName)},${schemaBlock}${descriptionBlock}
+    table: ${quote(tableName)},${schemaBlock}${descriptionBlock}${searchBlock}
     properties: {${propsOutput}
     },${relationsBlock}${adminBlock}
 ${close}
@@ -1692,6 +1866,6 @@ function safeHostFromUrl(url) {
 	return url.includes("@") ? url.split("@")[1] : "(local connection)";
 }
 //#endregion
-export { isUsableFileName as _, generateCollectionFile as a, identifyJoinTables as c, singularize as d, classifyTables as f, countRowsUpTo as g, humanize as h, buildTablesMap as i, mergeIndexContent as l, mapPgType as m, COMMON_PACKAGE as n, generateIndexContent as o, lookupCandidates as p, buildEnumMap as r, getIconForTable as s, ADMIN_TYPES_PACKAGE as t, safeHostFromUrl as u, quoteRelation as v, readSchemaMetadata as y };
+export { compositeKeySkipReason as a, getIconForTable as c, safeHostFromUrl as d, singularize as f, humanize as g, mapPgType as h, buildTablesMap as i, identifyJoinTables as l, lookupCandidates as m, COMMON_PACKAGE as n, generateCollectionFile as o, classifyTables as p, buildEnumMap as r, generateIndexContent as s, ADMIN_TYPES_PACKAGE as t, mergeIndexContent as u };
 
-//# sourceMappingURL=introspect-db-logic-WMuAfxvw.js.map
+//# sourceMappingURL=introspect-db-logic-kCETE8TY.js.map