@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g06dbe5b

package/dist/schema/ensure-collection-tables.d.ts

@@ -54,9 +54,17 @@ export interface ExistingSchema {
      * constraint that then fails harmlessly as a duplicate.
      */
     constraints?: Set<string>;
+    /**
+     * `schema.table.column` → that column's comment, for the columns that have
+     * one. This is where a generated search column's fingerprint lives, so it
+     * is the only evidence that a `search` block has changed since the column
+     * was built. Absent is read as "no column is stamped", which plans a stamp
+     * and reports nothing as drifted.
+     */
+    columnComments?: Map<string, string>;
 }
 export interface EnsureAction {
-    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column";
+    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column" | "create-extension" | "create-function" | "create-index" | "comment-column";
     /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
     target: string;
     sql: string;
@@ -76,6 +84,49 @@ export interface EnsurePlan {
      * resolving to nothing — which is indistinguishable from having no data.
      */
     legacyForeignKeys: LegacyForeignKey[];
+    /**
+     * Generated search columns whose `search` block has changed since they were
+     * built. Reported, never planned into `actions` — see
+     * {@link SearchColumnDrift} for why applying it is not this path's call.
+     */
+    searchDrift: SearchColumnDrift[];
+    /**
+     * Generated search columns that exist but carry no fingerprint — created
+     * before this check existed, or by `search.sql` on an older CLI. The plan
+     * stamps them so the *next* change is detectable; whether they match the
+     * current block cannot be known, which is what the caller reports.
+     */
+    searchAdopted: {
+        table: string;
+        column: string;
+    }[];
+}
+/**
+ * A generated search column built from a `search` block that has since changed.
+ *
+ * Reported instead of applied because the two ways to apply it are both worse
+ * than stopping. `ALTER COLUMN … SET EXPRESSION` exists only on PG17+ and
+ * rewrites the table either way; `DROP COLUMN` + `ADD COLUMN` rewrites it under
+ * an ACCESS EXCLUSIVE lock and rebuilds the GIN index. This module runs
+ * unattended against live customer data with nobody reading a diff — the same
+ * reason it withholds `SET NOT NULL` from an adopted table — so a multi-minute
+ * outage is not a decision it may take on its own.
+ *
+ * Not applying it silently is not an option either: that is the bug this
+ * detection exists for. A collection that added a field, flipped `unaccent` or
+ * raised a weight kept indexing the *old* set forever, and the only symptom was
+ * searches returning nothing for content plainly in the row.
+ */
+export interface SearchColumnDrift {
+    /** `schema.table`. */
+    table: string;
+    column: string;
+    /** The fingerprint recorded on the column. */
+    found: string;
+    /** The fingerprint the current `search` block computes. */
+    expected: string;
+    /** The statements that would rebuild the column, for the operator to run. */
+    rebuild: string[];
 }
 /** A relation column whose old and new spellings both plausibly apply. */
 export interface LegacyForeignKey {
@@ -88,14 +139,17 @@ export interface LegacyForeignKey {
 }
 export interface EnsureOutcome extends EnsurePlan {
     /**
-     * Constraints that could not be added — always non-fatal.
+     * Actions that could not be applied and are non-fatal by nature.
      *
-     * A foreign key can only fail on data that already violates it, and the
-     * column it would police exists either way, so the collection still serves.
-     * Refusing to boot over one would turn a pre-existing data problem into an
-     * outage. Reported loudly instead.
+     * Two kinds qualify. A foreign key can only fail on data that already
+     * violates it, and the column it would police exists either way, so the
+     * collection still serves; refusing to boot over one would turn a
+     * pre-existing data problem into an outage. A column comment is the search
+     * fingerprint, which needs table ownership — losing it costs drift
+     * detection on the next boot, not the deployment. Both are reported loudly.
      */
     failures: {
+        kind: EnsureAction["kind"];
         target: string;
         error: string;
     }[];
@@ -107,7 +161,7 @@ export interface EnsureOutcome extends EnsurePlan {
  * that reference them, tables before the columns added to other tables (a new
  * table may be the target of a relation), and nothing is emitted twice.
  */
-export declare function planCollectionSchemaEnsure(collections: CollectionConfig[], existing: ExistingSchema): EnsurePlan;
+export declare function planCollectionSchemaEnsure(allCollections: CollectionConfig[], existing: ExistingSchema): EnsurePlan;
 /** Read what the database has, for the schemas the collections live in. */
 export declare function readExistingSchema(client: Queryable, schemas: string[]): Promise<ExistingSchema>;
 /**

package/dist/schema/generate-drizzle-schema-logic.d.ts

@@ -1,2 +1,10 @@
-import { CollectionConfig } from "@rebasepro/types";
-export declare const generateSchema: (collections: CollectionConfig[], stripPolicies?: boolean) => Promise<string>;
+import { CollectionConfig, Property } from "@rebasepro/types";
+/**
+ * The Drizzle column declaration a property compiles to, or `null` when the
+ * property puts no column on *this* table (an inverse relation, whose column
+ * lives on the target). Exported so it can be checked against its DDL twin
+ * `getSqlColumnType` directly — the two disagreeing is what left `geopoint`
+ * with a database column and no Drizzle key.
+ */
+export declare const getDrizzleColumn: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string | null;
+export declare const generateSchema: (allCollections: CollectionConfig[], stripPolicies?: boolean) => Promise<string>;

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -29,8 +29,56 @@ export declare const generatePolicyStatements: (collection: CollectionConfig, ru
  */
 export declare const quoteSqlLiteral: (value: string) => string;
 export declare const getSqlColumnType: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string;
-export declare const generatePostgresDdl: (collections: CollectionConfig[], options?: {
+/**
+ * Everything a `search` block needs, as a file Rebase applies itself.
+ *
+ * Search is the one part of the schema Atlas does not own. Two independent
+ * reasons, and either alone would be enough:
+ *
+ * 1. Its free tier refuses to *parse* a desired-state file that so much as
+ *    contains a function — "functions and procedures are available to
+ *    logged-in users only". A generated `tsvector` column cannot avoid one:
+ *    `unaccent` is STABLE and jsonb flattening needs a set-returning function,
+ *    so both have to be wrapped in an IMMUTABLE helper to be legal in a
+ *    generated column at all.
+ * 2. Even with the file accepted, Atlas *wipes* the dev database it diffs
+ *    against, so a helper seeded there beforehand is gone by the time the plan
+ *    is analysed. There is no hook to reinstate it.
+ *
+ * So the column, its index and its helpers are excluded from Atlas's view
+ * (`searchExcludePatterns`) and applied from here — the same arrangement the
+ * RLS policies already use, and for the same underlying reason.
+ *
+ * Ordered as it must run: extensions, then helpers, then the column whose
+ * expression calls them, then the index over that column. Every statement is
+ * `IF NOT EXISTS` / `OR REPLACE`, because this is replayed on every push and
+ * appended to migrations that run against databases at any stage of their
+ * life. Empty when nothing opted in — the caller writes no file then.
+ *
+ * The leading half — extensions and helpers, without the table-shaped
+ * statements — is available on its own as {@link searchPrerequisiteStatements},
+ * for the dev database Atlas analyses plans against. That database has none of
+ * the project's tables, so it wants the functions and nothing else.
+ */
+export declare const searchPrerequisiteStatements: (allCollections: CollectionConfig[]) => string[];
+export declare const generatePostgresSearchDdl: (allCollections: CollectionConfig[]) => string;
+/**
+ * Glob patterns telling Atlas to leave the search column and its index alone.
+ *
+ * Without these, a desired state that omits search reads to Atlas as an
+ * instruction to drop the column — taking the index and the whole search
+ * feature with it on the next push.
+ *
+ * Fully qualified, `schema.table.object`, matching the include list. The
+ * two-part form is what Atlas wants when the connection URL scopes it to one
+ * schema and is *silently ignored* otherwise: it reads `posts.search_vector`
+ * as a table named `search_vector` in a schema named `posts`, matches nothing,
+ * and reports no error for the pattern that never fired.
+ */
+export declare const searchExcludePatterns: (allCollections: CollectionConfig[]) => string[];
+export declare const generatePostgresDdl: (allCollections: CollectionConfig[], options?: {
     includePolicies?: boolean;
+    includeSearch?: boolean;
 }) => Promise<string>;
 /** The RLS statements one declared collection's table needs, ready to run. */
 /**
@@ -100,7 +148,7 @@ export interface JunctionTablePlan {
  * is unknown yields the column without a constraint. Both mirror the generator
  * exactly — a divergence here is a schema fork between boot and `db push`.
  */
-export declare const planRelationalColumns: (collections: CollectionConfig[]) => RelationalColumnPlan[];
+export declare const planRelationalColumns: (allCollections: CollectionConfig[]) => RelationalColumnPlan[];
 /**
  * The junction tables a bundle's many-to-many relations imply.
  *
@@ -109,7 +157,7 @@ export declare const planRelationalColumns: (collections: CollectionConfig[]) =>
  * junction with row-level security left off is readable and writable by every
  * signed-in user, which is why the two must ship together.
  */
-export declare const planJunctionTables: (collections: CollectionConfig[]) => JunctionTablePlan[];
+export declare const planJunctionTables: (allCollections: CollectionConfig[]) => JunctionTablePlan[];
 export interface CollectionPolicyPlan {
     /** The table's schema (e.g. `public`, `rebase`). */
     schema: string;
@@ -137,6 +185,6 @@ export interface CollectionPolicyPlan {
  * writable by every signed-in user. A junction whose table is still absent is
  * skipped by the applier, not planned away here.
  */
-export declare const planCollectionPolicies: (collections: CollectionConfig[]) => CollectionPolicyPlan[];
-export declare const generatePostgresPoliciesDdl: (collections: CollectionConfig[]) => string;
+export declare const planCollectionPolicies: (allCollections: CollectionConfig[]) => CollectionPolicyPlan[];
+export declare const generatePostgresPoliciesDdl: (allCollections: CollectionConfig[]) => string;
 export {};

package/dist/schema/generated-schema-staleness.d.ts

@@ -0,0 +1,39 @@
+import { CollectionConfig } from "@rebasepro/types";
+/**
+ * Notice a generated Drizzle schema that a *library upgrade* invalidated.
+ *
+ * `rebase dev` already watches `config/collections` and warns when a collection
+ * file changes. That covers drift the developer caused. It cannot cover this one,
+ * because nothing the developer owns changed: 0.13 derives `category_id` where
+ * 0.12 derived `categorie_id`, from the same unedited collection. The watcher
+ * never fires, and `backend/src/schema.generated.ts` quietly stops describing the
+ * schema the runtime expects.
+ *
+ * The consequence is not cosmetic. Boot-ensure renames the column in the
+ * database, then relation validation reads the stale module and refuses to
+ * start — on that boot and every boot after it, because the rename is already
+ * applied and will not be attempted again.
+ *
+ * Deliberately narrow: this answers "does the generated schema name a foreign key
+ * the way the previous rule did", not "is this file what we would generate now".
+ * The wide question would report every whitespace change in the generator as a
+ * fatal staleness, and a check that cries wolf gets switched off.
+ */
+/** One column the generated schema names under the pre-0.13 rule. */
+export interface LegacyForeignKeyName {
+    /** Table whose column declaration is stale. */
+    table: string;
+    /** The name the generated schema declares. */
+    legacy: string;
+    /** The name this release derives, and which the database now carries. */
+    current: string;
+    /** `<collection>.<relation>` that derives it, for the message. */
+    relation: string;
+}
+/**
+ * @param generatedSource contents of `backend/src/schema.generated.ts`
+ * @param collections     the project's collections, as this release reads them
+ */
+export declare function findLegacyForeignKeyNames(generatedSource: string, collections: CollectionConfig[]): LegacyForeignKeyName[];
+/** One-line summary for a log or a CLI notice. */
+export declare function describeLegacyForeignKeyNames(found: LegacyForeignKeyName[]): string;

package/dist/schema/rls-bootstrap-sql.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Canonical SQL bootstrap for the RLS helper functions.
+ *
+ * Generated RLS policies reference `rebase.uid()` / `rebase.roles()` /
+ * `rebase.jwt()`, so any SQL stream that can contain policies must be
+ * self-contained: it has to (re)create these helpers first. This matters for
+ * the migration directory in particular — Atlas replays migrations against a
+ * clean dev database where no out-of-band bootstrap has ever run, so a
+ * migration carrying policies without this preamble fails with
+ * "function rebase.uid() does not exist".
+ *
+ * Idempotent (`IF NOT EXISTS` / `OR REPLACE`) so it can be prepended to every
+ * policies block and re-applied freely. The runtime boot path
+ * (`auth/ensure-tables.ts`) creates the same functions under an advisory lock
+ * for HMR-safety; keep the definitions in sync.
+ *
+ * ## Creating the `rebase` schema here is now safe, and required
+ *
+ * It deliberately did not, once. These functions lived in a schema called
+ * `auth`, and the note here read: creating `rebase` would leak it into Atlas's
+ * replayed migration state, and — absent from the desired `schema.sql` — Atlas
+ * would then plan `DROP SCHEMA "rebase" CASCADE`, taking the auth tables with
+ * it. That reasoning still holds; what changed is the second half of it. The
+ * DDL generator now emits `CREATE SCHEMA IF NOT EXISTS "rebase"`
+ * unconditionally, so the schema is always in the desired state and the diff is
+ * empty. (It used to appear only when some collection happened to declare
+ * `schema: "rebase"` — true for the scaffold's users collection, and not a
+ * property anything guaranteed.) `db push` additionally excludes the whole
+ * schema from the declarative apply.
+ *
+ * See `@rebasepro/types`' `rls-functions` for why the functions moved out of
+ * `auth` at all: the short version is that the name was Supabase's, and
+ * `CREATE OR REPLACE FUNCTION auth.uid() RETURNS text` cannot be applied over
+ * Supabase's `RETURNS uuid` — Postgres refuses, and the refusal used to be
+ * swallowed.
+ */
+/**
+ * The bootstrap as individual statements.
+ *
+ * Kept as an array because the two consumers need different shapes and only one
+ * of them can take a multi-command string: the migration preamble is written to
+ * a file and replayed by Atlas, but the boot path runs through drizzle, whose
+ * node-postgres handle speaks the extended query protocol and rejects more than
+ * one command per call. Splitting a joined string back apart on `$$;` would be
+ * a parser for a problem that does not need one.
+ */
+export declare const RLS_BOOTSTRAP_STATEMENTS: readonly string[];
+/** The same statements as one script, for migration files and raw clients. */
+export declare const RLS_BOOTSTRAP_SQL: string;
+/**
+ * Removes the pre-1.0 `auth` schema, but only when Rebase is what put it there.
+ *
+ * ## Why this is safe against a Supabase database
+ *
+ * Two independent guards, and both have to pass:
+ *
+ *  1. **Each function is identified before it is dropped.** Ours returns `text`
+ *     and reads the `app.uid` GUC; Supabase's returns `uuid` and reads
+ *     `request.jwt.claims`. Nothing is dropped on a signature we did not write,
+ *     so a Supabase database — where our `CREATE OR REPLACE` could never have
+ *     succeeded in the first place, Postgres refusing to change a return type —
+ *     matches nothing and this is a no-op.
+ *  2. **`DROP SCHEMA … RESTRICT`**, never CASCADE. If anything else at all still
+ *     lives in `auth` (Supabase's `users` table, its other helpers), the drop
+ *     fails and the schema stays. CASCADE here would be unrecoverable.
+ *
+ * ## Why it cannot run too early
+ *
+ * Postgres records a dependency from every RLS policy to the functions its body
+ * calls, so `DROP FUNCTION auth.uid()` fails for as long as a single policy
+ * still references it. That is the interlock, and it is load-bearing: the drop
+ * can only succeed once every policy has been recompiled to \`rebase.uid()\`.
+ * Callers therefore run this *after* applying policies, and treat a failure as
+ * "not yet — try again next boot" rather than as an error.
+ */
+export declare const DROP_LEGACY_AUTH_SCHEMA_SQL = "\nDO $rebase_drop_legacy$\nDECLARE\n    dropped_any boolean := false;\nBEGIN\n    -- Each function is matched on its own result type and body, so a schema\n    -- that merely shares the name keeps everything it has.\n    IF EXISTS (\n        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n        WHERE n.nspname = 'auth' AND p.proname = 'uid'\n          AND pg_get_function_result(p.oid) = 'text'\n          AND p.prosrc LIKE '%app.uid%'\n    ) THEN\n        DROP FUNCTION auth.uid();\n        dropped_any := true;\n    END IF;\n\n    IF EXISTS (\n        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n        WHERE n.nspname = 'auth' AND p.proname = 'jwt'\n          AND pg_get_function_result(p.oid) = 'jsonb'\n          AND p.prosrc LIKE '%app.jwt%'\n    ) THEN\n        DROP FUNCTION auth.jwt();\n        dropped_any := true;\n    END IF;\n\n    IF EXISTS (\n        SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n        WHERE n.nspname = 'auth' AND p.proname = 'roles'\n          AND pg_get_function_result(p.oid) = 'text'\n          AND p.prosrc LIKE '%app.user_roles%'\n    ) THEN\n        DROP FUNCTION auth.roles();\n        dropped_any := true;\n    END IF;\n\n    -- RESTRICT: only an empty schema goes. Anything else in there \u2014 including a\n    -- Supabase installation left untouched above \u2014 keeps it.\n    IF dropped_any THEN\n        BEGIN\n            EXECUTE 'DROP SCHEMA auth RESTRICT';\n        EXCEPTION WHEN OTHERS THEN\n            NULL;\n        END;\n    END IF;\nEND\n$rebase_drop_legacy$;\n";
+/** Somebody's policy that still calls a pre-1.0 helper. */
+export interface LegacyRlsDependent {
+    schema: string;
+    table: string;
+    policy: string;
+}
+/**
+ * Policies whose body still calls `auth.uid()` / `auth.roles()` / `auth.jwt()`.
+ *
+ * Postgres will not drop a function a policy depends on, so this is exactly the
+ * set standing between a database and losing the legacy schema. Rebase's own
+ * policies leave the list on the next push or boot, when they are recompiled —
+ * anything still here afterwards is hand-written, will never be recompiled by
+ * anybody, and is the reason the drop keeps being skipped. Silence there would
+ * leave an operator staring at a schema the release notes said would go.
+ */
+export declare const LEGACY_RLS_DEPENDENTS_SQL = "\n    SELECT n.nspname AS schema, c.relname AS \"table\", p.polname AS policy\n    FROM pg_policy p\n    JOIN pg_class c ON c.oid = p.polrelid\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    WHERE pg_get_expr(p.polqual, p.polrelid) ~* '\\mauth\\.(uid|jwt|roles)\\s*\\('\n       OR pg_get_expr(p.polwithcheck, p.polrelid) ~* '\\mauth\\.(uid|jwt|roles)\\s*\\('\n    ORDER BY 1, 2, 3\n";
+/** Somebody's *function* that still calls a pre-1.0 helper from its own body. */
+export interface LegacyRlsFunctionDependent {
+    schema: string;
+    function: string;
+}
+/**
+ * Functions whose body calls `auth.uid()` / `auth.roles()` / `auth.jwt()`.
+ *
+ * This is the half `DROP FUNCTION ... RESTRICT` cannot see, and the reason it
+ * needs its own query. Postgres records a dependency for a *policy* that calls a
+ * function, which is why the drop is safe against the policies above — but a
+ * `LANGUAGE sql` function whose body is a **string literal** is not parsed when
+ * it is created, so nothing is recorded and `RESTRICT` has nothing to refuse on.
+ * The drop succeeds and the caller is left pointing at a function that no longer
+ * exists, which fails at *query* time rather than at boot.
+ *
+ * A downstream project building on these helpers is not hypothetical: the Rebase
+ * control plane defines `auth.is_org_member(uuid)` and `auth.is_org_admin(uuid)`
+ * in this very schema, each calling `auth.uid()` in a string body, and eleven of
+ * its row-level-security policies go through them. Every one of those would have
+ * started failing the first time a recompile left no policy referencing
+ * `auth.uid()` directly — the drop's own precondition.
+ *
+ * Matching on the body text is the only option available, and it is deliberately
+ * broad: a false positive costs a schema that stays one release longer and says
+ * why, while a false negative costs somebody their policies.
+ */
+export declare const LEGACY_RLS_FUNCTION_DEPENDENTS_SQL = "\n    SELECT n.nspname AS schema, p.proname AS function\n    FROM pg_proc p\n    JOIN pg_namespace n ON n.oid = p.pronamespace\n    WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')\n      AND NOT (n.nspname = 'auth' AND p.proname IN ('uid', 'jwt', 'roles'))\n      AND p.prosrc ~* '\\mauth\\.(uid|jwt|roles)\\s*\\('\n    ORDER BY 1, 2\n";
+/**
+ * Retire the pre-1.0 `auth` schema, reporting what is holding it back.
+ *
+ * The shared implementation behind the CLI's post-push step and the runtime's
+ * post-policy step. Both used to just fire {@link DROP_LEGACY_AUTH_SCHEMA_SQL}
+ * and swallow whatever came back, which is right for the ordinary case — a
+ * table not recompiled *yet* — and wrong for the one that never resolves: a
+ * hand-written policy nothing will ever rewrite. Then the schema stays forever
+ * and nothing ever says why.
+ */
+export declare function dropLegacyAuthSchema(run: (sql: string) => Promise<Record<string, unknown>[]>, report: {
+    info: (m: string) => void;
+    warn: (m: string) => void;
+}): Promise<void>;

package/dist/schema/search-column.d.ts

@@ -0,0 +1,248 @@
+/**
+ * The one place a collection's `search` block becomes SQL.
+ *
+ * Four things describe a Postgres table in this codebase — the DDL generator,
+ * the Drizzle schema generator, the runtime table builder for BaaS mode, and
+ * the boot-time schema ensure — and each of them has, at some point, described
+ * a column differently from the others. The `varchar(255)` note in
+ * `generate-postgres-ddl-logic` is one such scar: the same property produced a
+ * capped column down one path and an uncapped one down the other, and nothing
+ * failed until a user hit the cap.
+ *
+ * So the search column is not implemented four times. It is computed once,
+ * here, and every generator renders the same {@link SearchColumnSpec}. There is
+ * a test asserting exactly that (`search-column-contract.test.ts`); the point of
+ * this module is that the test has something to assert *about*.
+ *
+ * ## Why the expressions look the way they do
+ *
+ * A `GENERATED ALWAYS AS … STORED` expression must be strictly IMMUTABLE, and
+ * Postgres is stricter here than intuition. Verified against PostgreSQL 18:
+ *
+ * | expression                              | immutable |
+ * |-----------------------------------------|-----------|
+ * | `to_tsvector('spanish', col)`           | yes       |
+ * | `to_tsvector(col)` (1-arg)              | **no** — depends on `default_text_search_config` |
+ * | `array_to_string(col, ' ')`             | **no**    |
+ * | `col::text` on `text[]`                 | **no**    |
+ * | `to_jsonb(col)`                         | **no**    |
+ * | `unaccent(col)`                         | **no** — dictionary lookup is STABLE |
+ * | `jsonb_to_tsvector('spanish', j, '["string"]')` | yes |
+ * | `setweight(...) || setweight(...)`      | yes       |
+ *
+ * Three of the four things a real search column needs are therefore unavailable
+ * directly, which is why {@link searchHelperFunctions} exists: each wraps a
+ * stable built-in in an SQL function declared IMMUTABLE. That declaration is a
+ * promise, and it is a true one for these three — array joining, JSON string
+ * extraction and accent folding are all deterministic for a given input; the
+ * built-ins are marked stable only because they must account for element types
+ * and dictionaries in general.
+ *
+ * The alternative was to skip `unaccent` and text arrays entirely. That is not
+ * a real option in an accented language: Postgres stems `auditoría` to
+ * `auditor` and `auditoria` to `auditori` — *different lexemes* — so a query
+ * typed without accents misses every row that carries them.
+ */
+import { CollectionConfig, SearchConfig, SearchWeight } from "@rebasepro/types";
+/**
+ * Names of the helper functions. Frozen: they are recorded in the stored
+ * generation expression of every search column ever created, so renaming one
+ * orphans every table that already has a search column.
+ */
+export declare const SEARCH_TEXT_FN = "public.rebase_search_text";
+export declare const SEARCH_UNACCENT_FN = "public.rebase_search_unaccent";
+/** How a declared path reaches text, which decides the SQL that extracts it. */
+type FieldKind = "text" | "text_array" | "jsonb";
+/** One resolved field: where it lives, how to read it, what it is worth. */
+export interface ResolvedSearchField {
+    /** The path exactly as the author wrote it, for error messages. */
+    path: string;
+    /** The physical column the path starts at. */
+    column: string;
+    /** Dotted remainder addressed inside a JSONB column, if any. */
+    jsonPath: string[];
+    kind: FieldKind;
+    weight: SearchWeight;
+    /** The `setweight(to_tsvector(…), 'X')` term this field contributes. */
+    sql: string;
+    /** The plain-text term this field contributes, for the fuzzy column. */
+    textSql: string;
+}
+/** Everything the generators need to render one collection's search column. */
+export interface SearchColumnSpec {
+    schema: string;
+    table: string;
+    /** The generated `tsvector` column. */
+    column: string;
+    language: string;
+    unaccent: boolean;
+    fields: ResolvedSearchField[];
+    /** Body of `GENERATED ALWAYS AS ( … ) STORED` for the tsvector column. */
+    expression: string;
+    indexName: string;
+    /** Extensions that must exist before the column can be created. */
+    extensions: string[];
+    fuzzy?: {
+        column: string;
+        expression: string;
+        indexName: string;
+        threshold: number;
+    };
+}
+/** Raised when a `search` block names something that cannot be searched. */
+export declare class SearchConfigError extends Error {
+    constructor(message: string);
+}
+/** The `search` block of a collection, or undefined when it has none. */
+export declare const getSearchConfig: (collection: CollectionConfig) => SearchConfig | undefined;
+/**
+ * Refuse a `search` block on a collection this engine does not store.
+ *
+ * The type only permits one on a `PostgresCollectionConfig`, so TypeScript
+ * already stops the ordinary case. This catches the rest — a JS config, a cast,
+ * a collection whose `engine` was changed after the block was written — because
+ * the alternative is the exact failure the block exists to prevent: a developer
+ * who declared what to index, saw no error, and got the substring fallback.
+ *
+ * Called with *every* collection, before the Postgres ones are filtered out.
+ */
+export declare const assertSearchIsPostgresOnly: (collections: CollectionConfig[]) => void;
+/**
+ * Build the full spec for a collection, or undefined when it has not opted in.
+ *
+ * Throws {@link SearchConfigError} on a config that cannot be honoured. Callers
+ * at boot surface that as a startup failure — a search block that half-works is
+ * worse than one that refuses.
+ */
+export declare const buildSearchColumnSpec: (collection: CollectionConfig) => SearchColumnSpec | undefined;
+/**
+ * The IMMUTABLE wrappers the generated expressions call.
+ *
+ * `CREATE OR REPLACE` so a boot against an existing database is a no-op rather
+ * than an error, and idempotent for the same reason every other boot-time DDL
+ * statement here is.
+ *
+ * The bodies are stable built-ins wrapped in an immutable promise — see the
+ * module comment for why that promise is sound. `STRICT` matters: it makes NULL
+ * in mean NULL out without executing the body, which is what the `coalesce` at
+ * each call site then absorbs.
+ */
+export declare const searchHelperFunctions: (spec: SearchColumnSpec) => string[];
+/**
+ * `CREATE EXTENSION` statements the spec's expressions depend on.
+ *
+ * `WITH SCHEMA public` is load-bearing, not tidiness. An unqualified
+ * `CREATE EXTENSION` installs into the first schema on `search_path`, which
+ * defaults to `"$user", public` — and the scaffold's database role is named
+ * `rebase`, the same as the schema the generator creates one statement earlier.
+ * So the moment that schema exists, `CREATE EXTENSION unaccent` puts the
+ * dictionary in `rebase`, and every reference to `public.unaccent` below fails
+ * with "text search dictionary does not exist". Observed, not theorised.
+ */
+export declare const searchExtensionStatements: (spec: SearchColumnSpec) => string[];
+/** The column definition as it appears inside `CREATE TABLE`. */
+export declare const searchColumnDefinition: (spec: SearchColumnSpec) => string;
+/** The fuzzy column definition, when the spec asks for one. */
+export declare const fuzzyColumnDefinition: (spec: SearchColumnSpec) => string | undefined;
+/**
+ * Index statements for the spec.
+ *
+ * `CONCURRENTLY` is deliberately *not* used here. This form is emitted into a
+ * SQL file replayed as one unit — a migration, or `search.sql` — where a
+ * concurrent build is not allowed. The boot-time ensure path runs statement by
+ * statement against tables that are live and populated, and uses the
+ * concurrent form instead; see `ensureSearchColumns`.
+ */
+export declare const searchIndexStatements: (spec: SearchColumnSpec) => string[];
+/**
+ * Marker on the comment of every generated search column this module creates.
+ *
+ * Versioned because the fingerprint below is only comparable against itself: a
+ * future change to how it is computed has to read as "not stamped by this
+ * version" rather than as drift on every existing column.
+ */
+export declare const SEARCH_STAMP_PREFIX = "rebase:search:v1:";
+/**
+ * A stable fingerprint of one generated column's expression.
+ *
+ * Why a stamp rather than reading the expression back: Postgres stores a
+ * generated column's expression *parsed*, and hands it back deparsed — casts
+ * made explicit, identifiers requoted, schema qualifications added or dropped
+ * according to `search_path`. Comparing that text to the text we generated
+ * would report drift on wording, and this comparison decides whether a boot
+ * refuses, so a false positive is an outage. The stamp is written by the same
+ * code that writes the column, so equality means what it says.
+ */
+export declare const searchExpressionFingerprint: (expression: string) => string;
+/** One generated column, with the fingerprint that identifies its expression. */
+export interface SearchColumnStamp {
+    column: string;
+    /** The expression the column is generated from. */
+    expression: string;
+    fingerprint: string;
+    /** `COMMENT ON COLUMN …`, which is where the fingerprint is recorded. */
+    sql: string;
+}
+/**
+ * The stamps for a spec's generated columns — one per column, never shared.
+ *
+ * Per column on purpose: turning `fuzzy` on adds a second column and changes
+ * nothing about the first, and a spec-wide fingerprint would report the
+ * untouched `tsvector` column as drifted and refuse a boot over a change that
+ * is purely additive.
+ */
+export declare const searchColumnStamps: (spec: SearchColumnSpec) => SearchColumnStamp[];
+/**
+ * The same drift check as the boot ensure, for the SQL file.
+ *
+ * Needed because {@link searchColumnStamps} would otherwise *launder* drift on
+ * the migration path: `ADD COLUMN IF NOT EXISTS` does nothing to a column that
+ * exists, so a re-generated `search.sql` would stamp a stale column with the
+ * new block's fingerprint and the next boot would find them in agreement.
+ * Guarding first means the file refuses instead — `rebase db push` is attended,
+ * and the operator reading the failure is the person who changed the block.
+ */
+export declare const searchStampGuards: (spec: SearchColumnSpec) => string[];
+/**
+ * The index names the spec creates.
+ *
+ * Needed by name, not just by statement, so Atlas can be told to exclude them
+ * from its diff — see `searchExcludePatterns`.
+ */
+export declare const searchIndexNames: (spec: SearchColumnSpec) => string[];
+/**
+ * The generated column names a collection's search block adds, if any.
+ *
+ * These are physical columns on the table, so `SELECT *` returns them. They are
+ * an index in column form — a list of lexeme positions, or a concatenation of
+ * every searchable field on the row — and nothing outside the query planner has
+ * any use for them. Left in, every list response carries a second, larger copy
+ * of the row's text.
+ */
+export declare const searchColumnNames: (collection: CollectionConfig) => string[];
+/**
+ * True for a column whose type only ever holds a search index.
+ *
+ * Independent of any collection config on purpose: an introspected database
+ * (BaaS mode) can carry a `tsvector` column this framework never created —
+ * Pagila's `film.fulltext` is the canonical one — and it should not be returned
+ * to callers either. `isDerivedIndexColumn` already keeps such a column out of
+ * the *properties*; this keeps it out of the *rows*.
+ */
+export declare const isSearchIndexColumn: (column: {
+    getSQLType?: () => string;
+}) => boolean;
+/**
+ * A drizzle select projection over `table` with the search columns dropped.
+ *
+ * Returns undefined when nothing needs dropping, so the common case keeps using
+ * a plain `select()` and this stays invisible in the generated SQL.
+ */
+export declare const visibleColumnProjection: (tableColumns: Record<string, {
+    getSQLType?: () => string;
+}> | undefined, collection?: CollectionConfig) => Record<string, unknown> | undefined;
+/** The same exclusion as a drizzle `db.query` `columns` denylist. */
+export declare const hiddenColumnsOption: (tableColumns: Record<string, {
+    getSQLType?: () => string;
+}> | undefined, collection?: CollectionConfig) => Record<string, false> | undefined;
+export {};