@rebasepro/server-postgres 0.23.0 → 0.24.1-canary.g19596ef

package/dist/schema/boot-ddl.d.ts

@@ -0,0 +1,47 @@
+/** `lock_timeout` for each attempt at a boot DDL statement or batch. See the module comment. */
+export declare const BOOT_LOCK_TIMEOUT_MS = 1000;
+/** Attempts per table, including the first, before a contended table is given up on. */
+export declare const BOOT_LOCK_ATTEMPTS = 3;
+/**
+ * The most lock waiting one boot step spends on *retries*, in total.
+ *
+ * Without a cap, a holder that covers the whole database — a `pg_dump` takes
+ * `ACCESS SHARE` on every table it dumps, for as long as it runs — costs
+ * tables × attempts × timeout: four minutes at 240 tables. Retrying is for the
+ * holder that is about to finish (a report, a transaction), and ten seconds is
+ * plenty to wait that out; past it, waiting longer only delays the boot.
+ */
+export declare const BOOT_LOCK_RETRY_BUDGET_MS = 10000;
+export interface BootLockOptions {
+    /** Per-attempt `lock_timeout`, ms. Default {@link BOOT_LOCK_TIMEOUT_MS}. */
+    lockTimeoutMs?: number;
+    /** Attempts per table, including the first. Default {@link BOOT_LOCK_ATTEMPTS}. */
+    attempts?: number;
+    /** Total retry waiting per step, ms. Default {@link BOOT_LOCK_RETRY_BUDGET_MS}. */
+    retryBudgetMs?: number;
+    /** Pause before retry round `round` (1-based), ms. Default: jittered, growing. */
+    backoffMs?: (round: number) => number;
+}
+export interface ResolvedBootLockOptions {
+    lockTimeoutMs: number;
+    attempts: number;
+    retryBudgetMs: number;
+    backoffMs: (round: number) => number;
+}
+export declare const resolveBootLockOptions: (options?: BootLockOptions) => ResolvedBootLockOptions;
+/** `55P03 lock_not_available` — what `lock_timeout` raises. */
+export declare const isLockTimeout: (err: unknown) => boolean;
+/**
+ * `42601` "cannot insert multiple commands into a prepared statement": the
+ * handle runs every query over the extended protocol, which carries exactly one
+ * statement. Raised before anything runs, so nothing needs undoing.
+ */
+export declare const isMultiStatementRefusal: (err: unknown) => boolean;
+/**
+ * `SET LOCAL lock_timeout`, then the statements: one string, one implicit
+ * transaction. See the module comment for why this and not `BEGIN … COMMIT`.
+ */
+export declare const atomicBatch: (statements: readonly string[], lockTimeoutMs: number) => string;
+/** Statements as one multi-statement string — one implicit transaction — each `;`-terminated. */
+export declare const joinStatements: (statements: readonly string[]) => string;
+export declare const sleep: (ms: number) => Promise<void>;

package/dist/schema/carved-out-migration.d.ts

@@ -49,10 +49,11 @@ export interface StripResult {
     empty: boolean;
 }
 /**
- * Split `schema.table.object` patterns. Anything not in three parts is
- * ignored rather than guessed at — the two-part form is the one Atlas itself
- * silently mis-reads, and repeating that mistake here would be worse than
- * doing nothing.
+ * Split `schema.table.object` patterns back into the names they were built
+ * from (`excludePatternParts`, the inverse of how every exclude is spelled).
+ * Anything not in three parts is ignored rather than guessed at — the two-part
+ * form is the one Atlas itself silently mis-reads, and repeating that mistake
+ * here would be worse than doing nothing.
  */
 export declare function parseExcludePatterns(patterns: string[]): CarvedOutObject[];
 /**

package/dist/schema/classify-change.d.ts

@@ -30,6 +30,23 @@
  * `diverges` is the whole point of this module: an editor that reports them as
  * safe is worse than one that refuses them.
  *
+ * ## Read from the plan, not from the properties
+ *
+ * Whether an edit changes the database is decided by comparing what
+ * `planSchema` — the one reading of a `Property` every emitter renders — makes
+ * of the collections before and after it: each table's columns, their types,
+ * nullability, defaults, uniqueness and foreign keys, the junction tables,
+ * indexes and triggers. It used to be decided by a hand-picked list of property
+ * fields, which knew nothing of `validation.integer`, of a string becoming an
+ * enum, of an array's element type or of anything about a relation beyond its
+ * name — and every one of those was reported "safe, no change", committed, and
+ * never applied. A difference in the plan cannot be missed that way: a new kind
+ * of edit either changes the plan, and is classified here from the difference,
+ * or it does not change the database.
+ *
+ * The property-level reading is still here, for the parts only it can name: a
+ * property added or removed, a required flag, an enum's values, a key renamed.
+ *
  * ## Why refusing is the right default for the rest
  *
  * Dropping a column, narrowing a type, changing a primary key: each is
@@ -37,7 +54,7 @@
  * somebody wrote and read. `needs-migration` says exactly that, and naming the
  * change is more useful than attempting it.
  */
-import type { CollectionConfig, SchemaChange, SchemaChangeKind, SchemaChangeVerdict, ClassifiedSchemaChanges } from "@rebasepro/types";
+import { type CollectionConfig, type SchemaChange, type SchemaChangeKind, type SchemaChangeVerdict, type ClassifiedSchemaChanges } from "@rebasepro/types";
 /**
  * The vocabulary lives in `@rebasepro/types` so that `@rebasepro/server`, which
  * cannot import this package, can still describe a change. Re-exported here
@@ -66,6 +83,10 @@ export interface SchemaFacts {
     notNullColumns?: Set<string>;
     /** `schema.typename` → the values that type currently holds. */
     enumValues?: Map<string, string[]>;
+    /** `schema.table.column` → the type Postgres reports for it (`udt_name`). */
+    columnTypes?: Map<string, string>;
+    /** `schema.table.column` of every column that has a DEFAULT. */
+    columnDefaults?: Set<string>;
 }
 /**
  * Classify the difference between two collection sets.
@@ -78,5 +99,12 @@ export interface SchemaFacts {
  * get the conservative reading.
  */
 export declare function classifyCollectionChanges(before: CollectionConfig[], after: CollectionConfig[], facts?: SchemaFacts): ClassifiedChanges;
+/**
+ * The statements a default change needs that the additive ensure does not
+ * plan: it sets a DEFAULT only on a column that has none, and never changes or
+ * drops one. Both are metadata-only — a DEFAULT binds future writes and touches
+ * no row — so a reviewed change may make them.
+ */
+export declare function defaultChangeStatements(before: CollectionConfig[], after: CollectionConfig[], existingTables: Map<string, Set<string>>): string[];
 /** A one-line summary, for a log or a refusal message. */
 export declare function summarizeChanges(classified: ClassifiedChanges): string;

package/dist/schema/collection-index.d.ts

@@ -71,6 +71,16 @@ export interface CollectionIndexSpec {
     reason: string;
     /** Derived by {@link deriveIndexName}. Frozen — see the module comment. */
     indexName: string;
+    /**
+     * Set when Rebase derived this index for a foreign key rather than anybody
+     * declaring it — see {@link foreignKeyIndexSpec}. Never enters the name, so
+     * the derived index and a declared one over the same column are one object.
+     *
+     * Read by exactly one consumer: boot-ensure, which builds these in the
+     * background on a table that already exists instead of holding the boot
+     * for the build. Every renderer treats them like any other index.
+     */
+    derived?: "foreign-key";
 }
 /**
  * A declaration that cannot become an index.
@@ -189,3 +199,38 @@ export declare const buildCollectionIndexPlan: (collections: readonly Collection
  * is a second order the moment either is edited.
  */
 export declare const sortIndexSpecs: (specs: readonly CollectionIndexSpec[]) => CollectionIndexSpec[];
+/**
+ * The `reason` a derived foreign-key index carries. Never part of the name —
+ * see {@link indexFingerprint} — so rewording it renames nothing.
+ */
+export declare const FOREIGN_KEY_INDEX_REASON = "Derived for a foreign key: Postgres indexes the key a constraint points at, never the column holding it.";
+/**
+ * Whether an index already serves an equality lookup on `column` alone.
+ *
+ * A btree whose *leading* key is the column does, unique or not — that is the
+ * prefix rule, and it is why a composite `(author_id, created_at)` makes a
+ * second index on `author_id` pure write amplification. A partial index does
+ * not: it serves only the rows its predicate admits, and a foreign-key lookup
+ * has to reach every row. Nor does GIN or BRIN, which answer different
+ * questions than "the rows whose key is one of these".
+ */
+export declare const leadsWithColumn: (spec: Pick<CollectionIndexSpec, "method" | "predicate" | "keys">, column: string) => boolean;
+/**
+ * The btree a foreign-key column gets when nothing else already leads with it.
+ *
+ * Postgres creates the index a foreign key *references* (the target's primary
+ * key) and never the one on the column *holding* it. Every read from the other
+ * side of the link filters on that column — a `hasMany`/`hasOne` include, a
+ * nested listing (`/authors/5/posts`, page and count), the reverse side of a
+ * many-to-many — and so does the `ON DELETE` check when a target row goes. With
+ * no index each of those is a sequential scan of the child table: measured at
+ * 13 ms for 25 parents over 100k children, and about 250 ms per nested listing
+ * at a million.
+ *
+ * Named by {@link deriveIndexName} like every other index, so it is a
+ * Rebase-managed name (`_ix_<fingerprint>`), it is in the Atlas diff, and it
+ * is byte-for-byte the name an author's own plain index on the column would
+ * derive. That identity is what makes the derived index and a declared one the
+ * same object rather than two.
+ */
+export declare const foreignKeyIndexSpec: (schema: string, table: string, column: string) => CollectionIndexSpec;

package/dist/schema/column-plan-helpers.d.ts

@@ -16,9 +16,9 @@
  * this is where they belong.
  *
  * Everything here is pure and synchronous, and it throws rather than guesses:
- * an enum with no values, a `cuid` id on Postgres and a second `isId` are all
- * configurations that produce a broken database in silence, so they are refused
- * where every path passes.
+ * an enum with no values, a `cuid` id on Postgres and a foreign key into a
+ * composite key are all configurations that produce a broken database in
+ * silence, so they are refused where every path passes.
  */
 import type { CollectionConfig, Property } from "@rebasepro/types";
 /**
@@ -29,21 +29,14 @@ import type { CollectionConfig, Property } from "@rebasepro/types";
  */
 export declare const resolveColumnName: (propName: string, prop?: Property | null) => string;
 /**
- * Refuse a collection that declares two primary keys.
+ * The properties marked `isId`, in declaration order.
  *
- * Postgres allows a composite primary key; Rebase does not model one, and the
- * three emitters each invented a different wrong answer for it. The Drizzle
- * generator appended `.primaryKey()` to both columns (two primary keys, which
- * drizzle-kit turns into an error at push time), the DDL generator wrote two
- * inline `PRIMARY KEY` clauses in one `CREATE TABLE` (Postgres: "multiple
- * primary keys for table are not allowed"), and boot-ensure created the table
- * with the *first* id column and silently never added the second — so a managed
- * tenant got a table missing a column its own collection reads.
- *
- * None of those is recoverable at runtime, and two of them fail long after the
- * config was written. Refused here instead, where the collection has a name.
+ * Several of them are one composite primary key: the table carries a single
+ * `PRIMARY KEY (a, b)` constraint over their columns, and a row's address lists
+ * the parts in this same order (`buildCompositeId`), which is the order the
+ * admin reads them in too.
  */
-export declare const assertSinglePrimaryKey: (collection: CollectionConfig) => void;
+export declare const primaryKeyPropertyNames: (collection: CollectionConfig) => string[];
 /**
  * A collection's primary key, by both of its names.
  *
@@ -64,11 +57,30 @@ export interface PrimaryKey {
     /** The declaring property; absent for the implicit `id TEXT` of a collection that declares none. */
     prop?: Property;
 }
-export declare const getPrimaryKeyProp: (collection: CollectionConfig) => PrimaryKey;
-/** The primary key's property key. What a Drizzle relation's `references` names. */
-export declare const getPrimaryKeyName: (collection: CollectionConfig) => string;
-/** The primary key's column. What a foreign key's `REFERENCES` names. */
-export declare const getPrimaryKeyColumn: (collection: CollectionConfig) => string;
+/**
+ * The one column a link into this collection points at.
+ *
+ * A foreign key column references a single column, and Postgres only accepts
+ * that column when it is unique on its own — `REFERENCES t (a)` against a
+ * composite key `(a, b)` fails with "there is no unique constraint matching
+ * given keys for referenced table". So a link into a collection whose key
+ * spans several columns has no column to point at, and it is refused here,
+ * naming the link, rather than emitted as a constraint `db push` or boot would
+ * then fail to create.
+ *
+ * @param via the link that needs the column, for the refusal: `relation "posts.author"`.
+ */
+export declare const getPrimaryKeyProp: (collection: CollectionConfig, via: string) => PrimaryKey;
+/**
+ * The primary key's property key. What a Drizzle relation's `references`
+ * names. Refused on the same terms as {@link getPrimaryKeyProp}.
+ */
+export declare const getPrimaryKeyName: (collection: CollectionConfig, via: string) => string;
+/**
+ * The primary key's column. What a foreign key's `REFERENCES` names. Refused
+ * on the same terms as {@link getPrimaryKeyProp}.
+ */
+export declare const getPrimaryKeyColumn: (collection: CollectionConfig, via: string) => string;
 export declare const isIdProperty: (propName: string, prop: Property, collection: CollectionConfig) => boolean;
 /**
  * The labels an `enum` declares, in order, whichever form it was written in.
@@ -142,3 +154,8 @@ export type IdColumnDefault =
  * write itself in one line of SQL.
  */
 export declare const idColumnDefault: (propName: string, prop: Property, collection: CollectionConfig) => IdColumnDefault | undefined;
+/**
+ * The SQL inside a template-form expression (``sql`now()` `` → `now()`); a
+ * bare expression is returned as it is.
+ */
+export declare const sqlExpressionText: (value: string) => string;

package/dist/schema/deferred-index-build.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Building the indexes a live table is missing — or holds INVALID — without
+ * holding anything up: the derived foreign-key indexes, and the declared,
+ * search and vector ones the boot-time ensure finds missing on a table that
+ * already exists.
+ *
+ * ## Why not a boot action like an index on a new table
+ *
+ * A table that already exists may hold millions of rows, and an index over
+ * them takes minutes to build. Boot-ensure's actions run before the server
+ * listens, so an index planned there is minutes of a deployment not serving —
+ * on the first boot after an upgrade that adds one to every `belongsTo` in the
+ * project, that is every large table at once. So these are planned apart
+ * (`DeferredIndexBuild`) and built here, after the boot, one at a time. A
+ * UNIQUE one is the exception: `ensureCollectionTables` builds it here too, but
+ * before it returns.
+ *
+ * ## The build
+ *
+ * `CREATE INDEX CONCURRENTLY`, outside any transaction (Postgres refuses it
+ * inside one), on a connection of its own with `statement_timeout` lifted: the
+ * pool's 30 s would cancel any build worth deferring. `CONCURRENTLY` takes
+ * `SHARE UPDATE EXCLUSIVE`, which conflicts with no read and no write — only
+ * with other DDL, `VACUUM` and `ANALYZE` — so live traffic never queues behind
+ * it, however long it runs.
+ *
+ * The boot's lock budget still applies, to the one wait that matters: getting
+ * the table at all. A table something else holds — another instance's build,
+ * an `ALTER TABLE`, a `VACUUM FULL` — is probed for `BOOT_LOCK_TIMEOUT_MS` at a
+ * time within the boot's retry budget, and left for the next boot when it
+ * stays held. Once the build has the table, it waits for the transactions
+ * already running against it with no deadline: a timeout there would only turn
+ * a slow build into a failed one.
+ *
+ * ## The husk a failed build leaves
+ *
+ * A cancelled `CONCURRENTLY` — a timeout, a killed process, a deploy that
+ * replaced the pod mid-build, two instances racing on one name — leaves the
+ * index behind marked `indisvalid = false`: maintained on every write, used by
+ * no query. And `IF NOT EXISTS` is a *name* check, so every later attempt
+ * skips it and reports success. This reads `pg_index` instead: an invalid index
+ * under our name is dropped (`DROP INDEX CONCURRENTLY`) and built again, once.
+ * One that another backend is still building (`pg_stat_progress_create_index`)
+ * is left to it.
+ *
+ * Nothing here is fatal. A failure is logged with the index named and the
+ * reason, and the next boot plans the index again.
+ */
+import type { Pool } from "pg";
+import { type DeferredIndexBuild } from "./plan/diff-plan.js";
+import { type BootLockOptions } from "./boot-ddl.js";
+/**
+ * A connection the builder may hold for as long as an index takes.
+ *
+ * `dedicated` says whether consecutive queries reach the same backend. Only
+ * then can a session setting be relied on — and be reset afterwards: on a
+ * pool, `SET statement_timeout = 0` would land on whichever connection served
+ * it and stay there for the next request to inherit.
+ */
+export interface IndexBuildSession {
+    query<T = unknown>(sql: string): Promise<{
+        rows: T[];
+    }>;
+    readonly dedicated: boolean;
+    /** Hand the connection back. Called once, after the last index. */
+    release(): void | Promise<void>;
+}
+export type OpenIndexBuildSession = () => Promise<IndexBuildSession>;
+/** A `pg.Pool` — what `connect()` checks a client out of — and not a `pg.Client`, whose `connect()` opens a socket. */
+export declare const isPgPool: (value: unknown) => value is Pick<Pool, "connect" | "totalCount">;
+/**
+ * Sessions checked out of a `pg.Pool`, one connection each.
+ *
+ * Its own connection rather than the pool's next free one, because a build
+ * has to outlive both of a pool's timeouts: the server-side
+ * `statement_timeout` (30 s on this framework's pools), which the builder
+ * lifts for the session — something it may only do on a connection nobody
+ * else is handed until it is reset — and the client-side read timeout, which
+ * is lifted here per query.
+ */
+export declare const poolIndexBuildSession: (pool: Pick<Pool, "connect">) => OpenIndexBuildSession;
+export interface DeferredIndexOptions extends BootLockOptions {
+    /** Progress, one line per index. Failures are also `logger.warn`ed. */
+    log?: (message: string) => void;
+    /** Checked between indexes; once true, nothing further is started. */
+    cancelled?: () => boolean;
+}
+export interface DeferredIndexOutcome {
+    /** `schema.index` this run built. */
+    built: string[];
+    /** Left alone, and why — already valid, or another instance is on it. */
+    skipped: {
+        index: string;
+        reason: string;
+    }[];
+    /** Not built. Logged; the next boot plans them again. */
+    failed: {
+        index: string;
+        error: string;
+    }[];
+}
+/** Why an index is skipped while a build of another index holds its table. */
+export declare const TABLE_BUSY_REASON = "another index on the table is being built";
+/**
+ * Build every deferred index, one at a time, on one connection.
+ *
+ * Never throws for an index: each failure is recorded and the next one is
+ * attempted. Throws only when no connection can be had at all.
+ */
+export declare function buildDeferredIndexes(openSession: OpenIndexBuildSession, indexes: readonly DeferredIndexBuild[], options?: DeferredIndexOptions): Promise<DeferredIndexOutcome>;
+/**
+ * Start {@link buildDeferredIndexes} later, in the background.
+ *
+ * `start()` begins it after `delayMs`; the fallback timer begins it after
+ * `fallbackMs` if nothing calls `start()` — so a process whose boot never
+ * reaches the step that would have started it still builds. Both timers are
+ * unref'd: a pending build never keeps a process alive, and a process that
+ * exits mid-build leaves a husk the next boot rebuilds.
+ */
+export interface ScheduledIndexBuild {
+    /** Begin after the schedule's `delayMs`, instead of waiting for the fallback timer. */
+    start(): void;
+    /** Start nothing further. An index already building runs to completion. */
+    cancel(): void;
+    /** Settles when the run ends — `undefined` if it never ran or could not open a connection. */
+    done: Promise<DeferredIndexOutcome | undefined>;
+}
+export declare function scheduleDeferredIndexBuild(openSession: OpenIndexBuildSession, indexes: readonly DeferredIndexBuild[], options?: DeferredIndexOptions & {
+    delayMs?: number;
+    fallbackMs?: number;
+}): ScheduledIndexBuild;

package/dist/schema/destructive-sql.d.ts

@@ -9,16 +9,27 @@
  * here, and refuse to auto-approve anything destructive without an explicit
  * opt-in.
  *
- * A type change is the one destructive plan that names no DROP. `ALTER COLUMN
+ * A type change is a destructive plan that names no DROP. `ALTER COLUMN
  * "price" TYPE integer` rounds every 19.99 to 20, and `TYPE date` throws away
  * every timestamp's time of day, in a statement that reads like a routine
  * alter. So a type change is gated too, unless it is a widening every value
  * survives unchanged — which needs the column's current type, read from the
  * catalogue by the caller.
  *
+ * A primary key change names no DROP of data either: `DROP CONSTRAINT
+ * "<table>_pkey", ADD PRIMARY KEY ("id", "locale")` keeps every value and
+ * gives every row a new address. It is gated like a drop.
+ *
+ * So is the drop of a CHECK or EXCLUDE constraint. It keeps every row and
+ * stops refusing the ones the rule was there to refuse. `db push` keeps Atlas
+ * away from those constraints (`schema/undeclarable-constraints.ts`), so a plan
+ * that still drops one is a pattern that missed, and the gate is the second
+ * line. Which constraints those are is read from the catalogue by the caller.
+ *
  * Everything in this file is side-effect free so it can be unit-tested
  * without Atlas or a database.
  */
+import type { ExistingConstraint } from "./undeclarable-constraints.js";
 /**
  * Split a SQL script into individual statements, dropping blank lines and
  * `--` comment lines. Deliberately simple: Atlas emits one plain statement
@@ -26,6 +37,19 @@
  * plan, so a naive split is safe and keeps this dependency-free.
  */
 export declare function splitSqlStatements(sql: string): string[];
+/**
+ * The statements of an Atlas plan, each exactly once, without Atlas's
+ * rendering and without the trailing `;`. See {@link readPlan} for the shape
+ * it reads; `test/fixtures/atlas-dry-run/` holds real captures of it.
+ */
+export declare function extractPlanStatements(plan: string): string[];
+/**
+ * Whether Atlas answered the dry-run with "Schema is synced" and nothing else.
+ *
+ * Positive evidence only: an empty or unreadable report also yields no
+ * statements, and is not the same answer.
+ */
+export declare function isSyncedPlan(plan: string): boolean;
 export interface DestructiveStatement {
     /** The offending statement (trimmed, without the trailing `;`). */
     statement: string;
@@ -60,8 +84,21 @@ export declare const COLUMN_TYPES_SQL = "\n    SELECT n.nspname AS \"schema\",\n
  * `columnTypes` is what the database holds now. A type change to a column it
  * does not list is flagged: not knowing what a column is means not knowing
  * whether the change keeps its values.
+ *
+ * `constraints` are the CHECK and EXCLUDE constraints the database holds now.
+ * A `DROP CONSTRAINT` of one of them is flagged; of any other constraint (a
+ * foreign key, a `UNIQUE`) it is not, as before.
+ */
+export declare function detectDestructiveStatements(planSql: string, columnTypes?: readonly ExistingColumnType[], constraints?: readonly ExistingConstraint[]): DestructiveStatement[];
+/**
+ * The statement from its `ALTER TABLE` on, wherever on a line that starts.
+ *
+ * {@link readPlan} hands over clean statements. This is the second line of
+ * defence for text it could not clean — a rendering it does not know yet —
+ * where a line of prose above the statement must not hide the statement, which
+ * is exactly how an anchored match once read Atlas's whole plan as safe.
  */
-export declare function detectDestructiveStatements(planSql: string, columnTypes?: readonly ExistingColumnType[]): DestructiveStatement[];
+export declare function fromAlterTable(statement: string): string;
 /**
  * Is `ALTER COLUMN … TYPE to` a widening, one that keeps every value exactly
  * as it was?
@@ -83,6 +120,17 @@ export declare function detectDestructiveStatements(planSql: string, columnTypes
  */
 export declare function isLosslessTypeChange(from: string, to: string): boolean;
 export type PushDecision = "apply" | "confirm" | "refuse";
+/**
+ * The flag that opted a push into destructive changes, as it was given —
+ * `--allow-destructive`, or its alias `--yes` / `-y` — or `undefined` for
+ * none. The line that says why a destructive push went ahead names the one
+ * the user typed: "because --allow-destructive was passed" to someone who
+ * typed `--yes` reads like a flag they never set.
+ */
+export declare function destructiveOptInFlag(args: {
+    "--allow-destructive"?: boolean;
+    "--yes"?: boolean;
+}): "--allow-destructive" | "--yes" | undefined;
 /**
  * Decide how `db push` should proceed given the plan's destructiveness and
  * the invocation context.

package/dist/schema/doctor-cli.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { createRequire as __createRequire } from "module";
 __createRequire(import.meta.url);
-import { i as diagnoseDbError } from "../cli-errors-B8qHg02P.js";
-import { o as validatePolicyPgRoles, s as warnOnAnonymousGrants } from "../rls-enforcement-C6Xk0lA6.js";
-import { t as chalk } from "../source-Br7L7GOI.js";
-import { n as loadCollections, r as runDoctor } from "../doctor-Cb2thZ8s.js";
-import { n as formatPolicyDrift, r as hasDrift, t as checkPolicyDrift } from "../policy-drift-DljYdrpW.js";
+import { a as buildSearchColumnSpec } from "../search-column-BM-GV6vH.js";
+import { i as diagnoseDbError } from "../cli-errors-oVUuD8k0.js";
+import { l as validatePolicyPgRoles, u as warnOnAnonymousGrants } from "../rls-enforcement-D7P4-ZYX.js";
+import { n as describeFailure, t as chalk } from "../source-DB6xJv3p.js";
+import { n as loadCollections, r as runDoctor } from "../doctor-CUAAOFZm.js";
+import { n as formatPolicyDrift, r as hasDrift, t as checkPolicyDrift } from "../policy-drift-BKC50y2p.js";
+import { isPostgresCollectionConfig } from "@rebasepro/types";
+import { getTableName, relationalCollections } from "@rebasepro/common";
 import path from "path";
 //#region src/schema/doctor-policy-checks.ts
 /**
@@ -80,6 +83,106 @@ async function runPolicyChecks(collectionsPath, databaseUrl) {
 	return problems ? "problems" : "ok";
 }
 //#endregion
+//#region src/schema/doctor-search-scale.ts
+/**
+* `rebase doctor`: collections searched by a full scan of a large table.
+*
+* Without a `search` block, a search — the admin's search box, `?searchString=`,
+* `.search()` — is `ILIKE '%term%'` over every text column. A leading `%`
+* defeats a B-tree, so each one reads the whole table: on 100k posts a search
+* took 326 ms, half for the page and half for its count. Nothing reports it;
+* the box just gets slower as the table grows. This names the collections
+* where that has started to matter, and points at the block that fixes it.
+*
+* A hint, not a failure: it never changes doctor's exit code, and the database
+* is not changed — Rebase does not add a search index on its own.
+*
+* Lives beside `doctor-cli.ts` rather than inside it because that file runs
+* `main()` on import.
+*/
+/** Above this many rows an unindexed search is worth a word. */
+var UNINDEXED_SEARCH_ROWS = 1e4;
+/**
+* The collections a search reaches without an index: no `search` block (or
+* one that does not build), and at least one property the default search
+* reads — a `string`, not an enum, not a uuid key (the rule in
+* `DrizzleConditionBuilder.buildSearchConditions`).
+*/
+function ilikeSearchedCollections(collections) {
+	const found = [];
+	for (const collection of relationalCollections(collections)) {
+		if (!isPostgresCollectionConfig(collection)) continue;
+		let indexed;
+		try {
+			indexed = buildSearchColumnSpec(collection) !== void 0;
+		} catch {
+			indexed = false;
+		}
+		if (indexed) continue;
+		const fields = Object.entries(collection.properties ?? {}).filter(([, property]) => property.type === "string" && !property.enum && property.isId !== "uuid").map(([key]) => key);
+		const table = getTableName(collection);
+		if (fields.length === 0 || !table) continue;
+		found.push({
+			slug: collection.slug,
+			schema: collection.schema ?? "public",
+			table,
+			fields
+		});
+	}
+	return found;
+}
+/** Those of `candidates` whose table holds more than `threshold` rows, by estimate. */
+function unindexedSearchFindings(candidates, rowEstimates, threshold = UNINDEXED_SEARCH_ROWS) {
+	return candidates.map((candidate) => ({
+		...candidate,
+		rows: rowEstimates.get(`${candidate.schema}.${candidate.table}`) ?? 0
+	})).filter((candidate) => candidate.rows > threshold);
+}
+/**
+* Row counts by `schema.table`, estimated — `pg_class.reltuples`, or the
+* statistics collector's live-tuple count when the table was never analysed.
+* Nothing is scanned: counting the tables this is about would be the cost it
+* warns of.
+*/
+async function estimateRowCounts(query, schemas) {
+	const { rows } = await query(`SELECT n.nspname AS schema, c.relname AS table,
+                GREATEST(c.reltuples, COALESCE(s.n_live_tup, 0), 0)::bigint AS rows
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+         WHERE c.relkind IN ('r', 'p') AND n.nspname = ANY($1)`, [schemas]);
+	return new Map(rows.map((row) => [`${row.schema}.${row.table}`, Number(row.rows)]));
+}
+/** The report, one warning per collection. */
+function formatUnindexedSearches(findings) {
+	if (findings.length === 0) return [];
+	const lines = ["", chalk.yellow(`  ⚠ ${findings.length} collection(s) searched by reading the whole table:`)];
+	for (const finding of findings) lines.push(chalk.yellow(`     • ${finding.slug} — about ${finding.rows.toLocaleString("en-US")} rows, no \`search\` block: a search is ILIKE '%term%' over ${finding.fields.join(", ")}`));
+	lines.push(chalk.gray("    Each search reads every row, and its count reads them again. A `search` block indexes it\n    (full-text, or `mode: \"hybrid\"` for substrings too): https://rebase.pro/docs/backend/search"));
+	return lines;
+}
+/**
+* Print the warning for the project at `collectionsPath`, against
+* `databaseUrl`. Never throws and never fails the run: it is a hint, and a
+* check that could not run says so in one grey line.
+*/
+async function runSearchScaleCheck(collectionsPath, databaseUrl) {
+	if (!databaseUrl) return;
+	const { Client } = await import("pg");
+	const client = new Client({ connectionString: databaseUrl });
+	try {
+		const candidates = ilikeSearchedCollections(await loadCollections(path.resolve(process.cwd(), collectionsPath)));
+		if (candidates.length === 0) return;
+		await client.connect();
+		const estimates = await estimateRowCounts((text, values) => client.query(text, values), [...new Set(candidates.map((candidate) => candidate.schema))]);
+		for (const line of formatUnindexedSearches(unindexedSearchFindings(candidates, estimates))) console.log(line);
+	} catch (err) {
+		console.log(chalk.gray(`  ⏭ Search on large tables: not checked (${err instanceof Error ? err.message : String(err)})`));
+	} finally {
+		await client.end().catch(() => void 0);
+	}
+}
+//#endregion
 //#region src/schema/doctor-cli.ts
 /**
 * CLI entry point for `rebase doctor`.
@@ -111,6 +214,7 @@ async function main() {
 		databaseUrl: databaseUrl ?? void 0
 	});
 	const policyStatus = await runPolicyChecks(collectionsPath, databaseUrl);
+	await runSearchScaleCheck(collectionsPath, databaseUrl);
 	const blocked = [
 		report.collectionsToSchema,
 		report.schemaToDatabase,
@@ -121,7 +225,7 @@ async function main() {
 main().catch((err) => {
 	const banner = diagnoseDbError(err, process.env.DATABASE_URL || process.env.ADMIN_CONNECTION_STRING);
 	if (banner) console.error(banner);
-	else console.error(chalk.red("  ✗ Doctor failed"), err instanceof Error ? err.stack ?? err.message : String(err));
+	else console.error(chalk.red(`  ✗ Doctor failed: ${describeFailure(err)}`));
 	process.exit(1);
 });
 //#endregion