@rebasepro/server-postgres 0.17.1 → 0.17.2-canary.g4d21a53

package/src/schema/generate-postgres-ddl-logic.ts

@@ -16,8 +16,15 @@ import {
     type SearchColumnSpec
 } from "./search-column";
 import {
+    buildVectorColumnSpecs,
     buildVectorIndexPlan,
+    vectorColumnDefinition,
+    vectorDimensionGuard,
+    vectorExtensionDeclared,
+    vectorExtensionStatement,
     vectorIndexStatements,
+    vectorObjectNames,
+    VECTOR_EXTENSION_OPT_IN,
     type VectorIndexPlan
 } from "./vector-index";
 import { buildCollectionIndexSpecs, collectionIndexStatements } from "./collection-index";
@@ -297,22 +304,15 @@ export const getSqlColumnType = (propName: string, prop: Property, collection: C
  * 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.
+ * The dev database Atlas plans against needs none of this. `searchExcludePatterns`
+ * removes the search column from the *inspected* state, so the state Atlas
+ * replays there never mentions the column and never calls a helper. Seeding the
+ * helpers into that database was tried and removed: measured on Atlas 1.2.3, a
+ * `schema apply --dry-run` produces byte-identical output seeded or not, and
+ * Atlas wipes the dev database before it plans anyway — so a seed could not have
+ * helped even where the excludes are missing, which is the case that really does
+ * fail with `function public.rebase_search_unaccent(text) does not exist`.
  */
-export const searchPrerequisiteStatements = (allCollections: CollectionConfig[]): string[] => {
-    const specs = relationalCollections(allCollections)
-        .map(c => buildSearchColumnSpec(c))
-        .filter((s): s is SearchColumnSpec => s !== undefined);
-    if (specs.length === 0) return [];
-    return [
-        ...new Set(specs.flatMap(searchExtensionStatements)),
-        ...new Set(specs.flatMap(searchHelperFunctions))
-    ];
-};
-
 export const generatePostgresSearchDdl = (allCollections: CollectionConfig[]): string => {
     const collections = relationalCollections(allCollections);
     const specs = collections
@@ -391,11 +391,112 @@ export const searchExcludePatterns = (allCollections: CollectionConfig[]): strin
     return patterns;
 };
 
+/**
+ * Everything a `{ type: "vector" }` property needs, as a file Rebase applies
+ * itself.
+ *
+ * Vector is the second part of the schema Atlas does not own, and it is out for
+ * a narrower reason than search: not that Atlas refuses to parse the file, but
+ * that it cannot *execute* it. To compute a desired state Atlas materialises
+ * `schema.sql` in a dev database, that database is created empty, and Atlas
+ * empties it again at the start of every run — so `VECTOR(384)` resolves
+ * against a database that structurally cannot have pgvector, and every push
+ * dies with `type "vector" does not exist`. Seeding the extension beforehand
+ * does not survive the clean (measured: present before the run, gone after),
+ * putting `CREATE EXTENSION` in `schema.sql` is refused as an Atlas Pro
+ * feature, and `--exclude` alone cannot help because Atlas still parses and
+ * applies the whole file.
+ *
+ * So the column, its ANN indexes and the extension are excluded from Atlas's
+ * view ({@link vectorExcludePatterns}) and applied from here — the same
+ * arrangement search and the RLS policies already use.
+ *
+ * `CREATE EXTENSION` appears only when the project's database named `vector` in
+ * its `extensions` — see `DatabaseOptions.extensions`. Everything else is
+ * emitted either way: a database that already has pgvector installed by hand
+ * needs no permission from anyone, and one that does not gets the column
+ * refused by Postgres with a message this repo makes name the opt-in.
+ *
+ * Ordered as it must run: the extension, then the drift guard, then the column
+ * whose type needs the extension, then the indexes over that column. Every
+ * statement is `IF NOT EXISTS`, because this is replayed on every push and
+ * appended to migrations that run against databases at any stage of their life.
+ * Empty when no collection declares a vector — the caller writes no file then.
+ */
+export const generatePostgresVectorDdl = (
+    allCollections: CollectionConfig[],
+    options: { extensions?: readonly string[] } = {}
+): string => {
+    const collections = relationalCollections(allCollections);
+    const withVectors = collections.filter(c => buildVectorColumnSpecs(c, resolveColumnName).length > 0);
+    if (withVectors.length === 0) return "";
+
+    let ddl = "-- This file is auto-generated by the Rebase DDL generator. Do not edit manually.\n";
+    ddl += "--\n";
+    ddl += "-- Vector columns and their ANN indexes, for the collections declaring a\n";
+    ddl += "-- `vector` property. Applied by Rebase, not by Atlas — see\n";
+    ddl += "-- generatePostgresVectorDdl.\n\n";
+    // The note is not decoration. Someone reading this file after a failed push
+    // is looking for the reason the type does not exist, and "no CREATE
+    // EXTENSION here" is invisible unless it is written down.
+    ddl += vectorExtensionDeclared(options.extensions)
+        ? `${vectorExtensionStatement()}\n\n`
+        : `-- pgvector is not installed from here: no database declared it. To let Rebase\n` +
+          `-- install it, add ${VECTOR_EXTENSION_OPT_IN} in config/resources.ts.\n` +
+          `-- Otherwise install it once by hand; the column below needs the type either way.\n\n`;
+
+    for (const collection of withVectors) {
+        const table = `"${isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public"}"."${getTableName(collection)}"`;
+        for (const spec of buildVectorColumnSpecs(collection, resolveColumnName)) {
+            // Guard before the ADD, so a changed `dimensions` is reported rather
+            // than skipped over — see `vectorDimensionGuard`.
+            ddl += `${vectorDimensionGuard(spec)}\n`;
+            // ADD COLUMN IF NOT EXISTS rather than the inline definition the
+            // CREATE TABLE would use: by the time this runs the table exists,
+            // whether Atlas just created it or it has been live for a year.
+            ddl += `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${vectorColumnDefinition(spec)};\n`;
+        }
+        const plan = buildVectorIndexPlan(collection, resolveColumnName);
+        vectorIndexStatements(plan).forEach(s => { ddl += `${s}\n`; });
+        for (const skip of plan.skipped) {
+            ddl += `-- No ANN index on "${skip.schema}"."${skip.table}"."${skip.column}": ${skip.reason}\n`;
+        }
+        ddl += "\n";
+    }
+
+    return ddl;
+};
+
+/**
+ * Glob patterns telling Atlas to leave the vector column and its ANN indexes
+ * alone.
+ *
+ * Without these, a desired state that omits the column reads to Atlas as an
+ * instruction to drop it, taking the embeddings and the indexes with it on the
+ * next push.
+ *
+ * Fully qualified, `schema.table.object`, for the reason spelled out on
+ * {@link searchExcludePatterns}: the two-part form matches nothing and reports
+ * no error, which turns a protection into a `DROP COLUMN`.
+ */
+export const vectorExcludePatterns = (allCollections: CollectionConfig[]): string[] => {
+    const patterns: string[] = [];
+    for (const collection of relationalCollections(allCollections)) {
+        const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+        const table = getTableName(collection);
+        for (const name of vectorObjectNames(collection, resolveColumnName)) {
+            patterns.push(`${schema}.${table}.${name}`);
+        }
+    }
+    return patterns;
+};
+
 export const generatePostgresDdl = async (
     allCollections: CollectionConfig[],
-    options: { includePolicies?: boolean; includeSearch?: boolean } = {
+    options: { includePolicies?: boolean; includeSearch?: boolean; includeVector?: boolean } = {
         includePolicies: true,
-        includeSearch: true
+        includeSearch: true,
+        includeVector: true
     }
 ): Promise<string> => {
     // Only the collections this engine stores. See `relationalCollections`.
@@ -446,6 +547,18 @@ export const generatePostgresDdl = async (
         }
     }
 
+    // 1c. Vector support, for collections that declared a `vector` property.
+    //
+    // Only a note, never a statement — unlike 1b, which emits search's
+    // extensions when they are included. `CREATE EXTENSION vector` is the one
+    // thing this file must never carry whichever way the flag goes: Atlas
+    // rejects an extension in a desired state as a paid feature. The note is
+    // for whoever opens the generated file looking for the column.
+    if (options.includeVector === false
+        && collections.some(c => buildVectorColumnSpecs(c, resolveColumnName).length > 0)) {
+        ddl += "-- Vector columns and their ANN indexes live in `vector.sql`, applied separately.\n\n";
+    }
+
     // 2. Generate Enums
     //
     // The enum type name is derived from table + column, so two collections
@@ -579,6 +692,13 @@ export const generatePostgresDdl = async (
             const columns: string[] = [];
 
             Object.entries(collection.properties ?? {}).forEach(([propName, prop]) => {
+                // A vector column is not Atlas's — `vector.sql` adds it. Skipped
+                // here rather than filtered upstream so the column keeps its
+                // place in the generator's order when it *is* included, which is
+                // what the derived-names contract renders.
+                if (prop.type === "vector" && options.includeVector === false) {
+                    return;
+                }
                 if (prop.type === "relation") {
                     const refProp = prop as RelationProperty;
                     const resolvedRelations = resolveCollectionRelations(collection);
@@ -729,10 +849,16 @@ export const generatePostgresDdl = async (
             // rather than inline, because `CREATE INDEX` is a statement and a
             // column definition is not — and because a column too wide for
             // pgvector to index still needs its column.
-            const vectorPlan: VectorIndexPlan = buildVectorIndexPlan(collection, resolveColumnName);
-            indexStatements.push(...vectorIndexStatements(vectorPlan));
-            for (const skip of vectorPlan.skipped) {
-                indexStatements.push(`-- No ANN index on "${skip.schema}"."${skip.table}"."${skip.column}": ${skip.reason}`);
+            //
+            // Absent alongside their column when vector is carved out: an index
+            // over a column this file no longer declares would not resolve, and
+            // `USING hnsw` needs the extension the dev database cannot have.
+            if (options.includeVector !== false) {
+                const vectorPlan: VectorIndexPlan = buildVectorIndexPlan(collection, resolveColumnName);
+                indexStatements.push(...vectorIndexStatements(vectorPlan));
+                for (const skip of vectorPlan.skipped) {
+                    indexStatements.push(`-- No ANN index on "${skip.schema}"."${skip.table}"."${skip.column}": ${skip.reason}`);
+                }
             }
 
             // The collection's own `indexes:` block. Last of the three index

package/src/schema/generate-postgres-ddl.ts

@@ -5,12 +5,43 @@ import { pathToFileURL } from "url";
 import {
     generatePostgresDdl,
     generatePostgresPoliciesDdl,
-    generatePostgresSearchDdl
+    generatePostgresSearchDdl,
+    generatePostgresVectorDdl
 } from "./generate-postgres-ddl-logic";
-import { CollectionConfig } from "@rebasepro/types";
+import { CollectionConfig, declaredDatabaseExtensions } from "@rebasepro/types";
 import { loadCollectionsFromDirectory } from "@rebasepro/server";
 import { out, outError } from "../cli-output";
 
+/** Where a project declares its resources, relative to the config directory. */
+const RESOURCE_ENTRIES = ["resources.ts", "resources.js", "resources/index.ts", "resources/index.js"];
+
+/**
+ * Evaluate the project's `resources.ts`, so `declaredDatabaseExtensions()` can
+ * answer.
+ *
+ * This generator runs as its own tsx subprocess and loads only the collections
+ * directory, so nothing else in it would ever import the resources module — and
+ * a permission that reads as absent because nobody loaded it is the worst shape
+ * this could take: the push succeeds, `vector.sql` quietly omits the
+ * `CREATE EXTENSION`, and the failure lands one statement later looking like a
+ * database problem.
+ *
+ * Imported directly rather than through the config index, for the reason
+ * `boot/resource-loading.ts` gives: re-exporting from the index would work only
+ * for projects that remember to.
+ *
+ * A project with no resources module is the normal case and declares nothing.
+ * An import that *throws* is not swallowed — a resources module that does not
+ * evaluate is a configuration error, and treating it as "declared nothing"
+ * would turn it into a silently missing extension.
+ */
+async function loadDeclaredResources(configDir: string): Promise<void> {
+    const entry = RESOURCE_ENTRIES
+        .map(name => path.join(configDir, name))
+        .find(candidate => fs.existsSync(candidate));
+    if (!entry) return;
+    await import(pathToFileURL(entry).href);
+}
 
 const runGeneration = async (collectionsFilePath?: string, outputPath?: string) => {
     try {
@@ -21,6 +52,11 @@ const runGeneration = async (collectionsFilePath?: string, outputPath?: string)
 
         const resolvedPath = path.resolve(collectionsFilePath);
 
+        // `<config>/collections` is the path this is given, so the config
+        // directory is its parent — the same relationship `rebase resources`
+        // and the boot loader assume.
+        await loadDeclaredResources(path.dirname(resolvedPath));
+
         // Shared with the runtime and the doctor: what gets generated here must
         // be exactly what the server serves, including directory-level defaults.
         let collections: CollectionConfig[] = await loadCollectionsFromDirectory(resolvedPath);
@@ -34,15 +70,19 @@ const runGeneration = async (collectionsFilePath?: string, outputPath?: string)
         collections.sort((a, b) => a.slug.localeCompare(b.slug));
 
         // `schema.sql` is Atlas's desired state, and it carries neither the RLS
-        // policies nor the search apparatus: Atlas manages neither, and in the
-        // search case cannot. Both are written beside it and applied by the CLI
-        // in their own right.
+        // policies, nor the search apparatus, nor the vector columns: Atlas
+        // manages none of them, and in the search and vector cases cannot. All
+        // three are written beside it and applied by the CLI in their own right.
         const ddlContent = await generatePostgresDdl(collections, {
             includePolicies: false,
-            includeSearch: false
+            includeSearch: false,
+            includeVector: false
         });
         const policiesContent = generatePostgresPoliciesDdl(collections);
         const searchContent = generatePostgresSearchDdl(collections);
+        const vectorContent = generatePostgresVectorDdl(collections, {
+            extensions: declaredDatabaseExtensions()
+        });
 
         if (outputPath) {
             const outputDir = path.dirname(outputPath);
@@ -64,6 +104,19 @@ const runGeneration = async (collectionsFilePath?: string, outputPath?: string)
             } else if (fs.existsSync(searchPath)) {
                 await fsPromises.rm(searchPath);
             }
+
+            // Removed when the last `vector` property goes, for the same reason
+            // `search.sql` is: the CLI applies whichever of these files exists,
+            // and a stale one would keep re-adding a column the collections no
+            // longer declare — which Atlas, no longer told to exclude it, would
+            // then plan a DROP for on the very next push.
+            const vectorPath = path.join(outputDir, "vector.sql");
+            if (vectorContent) {
+                await fsPromises.writeFile(vectorPath, vectorContent);
+                out(`✅ PostgreSQL vector DDL generated successfully at ${vectorPath}`);
+            } else if (fs.existsSync(vectorPath)) {
+                await fsPromises.rm(vectorPath);
+            }
         } else {
             out("✅ PostgreSQL DDL generated successfully.");
             out(String(ddlContent));

package/src/schema/generate-schema-commit.ts

@@ -37,11 +37,17 @@
  * migration this module cannot make valid would be worse than handing the
  * statements to a caller who knows which kind of project it is.
  */
-import { DEFAULT_COMMIT_PATHS, type CollectionConfig, type SchemaCommitPaths } from "@rebasepro/types";
+import {
+    DEFAULT_COMMIT_PATHS,
+    declaredDatabaseExtensions,
+    type CollectionConfig,
+    type SchemaCommitPaths
+} from "@rebasepro/types";
 import {
     generatePostgresDdl,
     generatePostgresPoliciesDdl,
-    generatePostgresSearchDdl
+    generatePostgresSearchDdl,
+    generatePostgresVectorDdl
 } from "./generate-postgres-ddl-logic";
 import { generateSchema } from "./generate-drizzle-schema-logic";
 import {
@@ -207,18 +213,37 @@ export async function generateSchemaCommit(input: SchemaCommitInput): Promise<Sc
         );
     }
 
-    const [schema, ddl, policies, search] = await Promise.all([
+    // The same split `rebase db generate` writes, and it has to be the same:
+    // these files land in the repository, and the next `db push` runs Atlas
+    // against `schema.sql`. Generated whole, it carries the RLS policies (which
+    // Atlas would then own and drop), the search helpers (which its free tier
+    // refuses to parse at all) and `VECTOR(n)` (which its dev database cannot
+    // resolve) — so a live schema edit used to leave behind a desired-state
+    // file that `db push` chokes on.
+    const [schema, ddl, policies, search, vector] = await Promise.all([
         generateSchema(input.after),
-        generatePostgresDdl(input.after),
+        generatePostgresDdl(input.after, {
+            includePolicies: false,
+            includeSearch: false,
+            includeVector: false
+        }),
         Promise.resolve(generatePostgresPoliciesDdl(input.after)),
-        Promise.resolve(generatePostgresSearchDdl(input.after))
+        Promise.resolve(generatePostgresSearchDdl(input.after)),
+        // The registry, because this runs inside the booted server, which has
+        // already evaluated the project's `resources.ts`. A commit that wrote a
+        // `vector.sql` disagreeing with the one `rebase db generate` produces
+        // would show up as drift in the repository the moment anyone regenerated.
+        Promise.resolve(generatePostgresVectorDdl(input.after, {
+            extensions: declaredDatabaseExtensions()
+        }))
     ]);
 
     const generated: SchemaCommitFile[] = [
         { path: paths.schemaFile, contents: schema },
         { path: paths.ddlFile, contents: ddl },
         { path: paths.policiesFile, contents: policies },
-        { path: paths.searchFile, contents: search }
+        { path: paths.searchFile, contents: search },
+        { path: paths.vectorFile, contents: vector }
     ];
 
     // Both sides planned once, here, rather than through `additiveStatements` —

package/src/schema/vector-index.ts

@@ -28,6 +28,17 @@
  * boot-time ensure render the *same* specification rather than describing the
  * same index twice, differently. `contracts/derived-names.txt` records the
  * names both produce, and CI fails if they diverge.
+ *
+ * ## And why the column itself is described here too
+ *
+ * `VECTOR(n)` is a type Atlas cannot be shown. It has to materialise the
+ * desired state in a dev database to diff against, that database is created
+ * empty and *emptied again* by Atlas at the start of every run, and nothing in
+ * the free tier can put `CREATE EXTENSION vector` back — so a `schema.sql`
+ * mentioning the type fails with `type "vector" does not exist` on every push,
+ * for good. Search hit the same wall for its own reasons and took the same way
+ * out: the objects leave `schema.sql`, Atlas is told to exclude them, and
+ * Rebase applies them itself. See `generatePostgresVectorDdl`.
  */
 import type { CollectionConfig, Property, VectorDistance, VectorIndexConfig } from "@rebasepro/types";
 import { isPostgresCollectionConfig } from "@rebasepro/types";
@@ -276,3 +287,205 @@ export const vectorIndexStatements = (plan: VectorIndexPlan): string[] =>
 /** The index names a plan creates — what the derived-names contract records. */
 export const vectorIndexNames = (plan: VectorIndexPlan): string[] =>
     plan.specs.map(spec => spec.indexName);
+
+// ── The column, for the file Rebase applies itself ──────────────────────────
+
+const quote = (v: string): string => `'${v.replace(/'/g, "''")}'`;
+
+/**
+ * The schema pgvector's types are installed into.
+ *
+ * `WITH SCHEMA public` for the same load-bearing reason `searchExtensionStatements`
+ * gives: an unqualified `CREATE EXTENSION` lands in the first schema on
+ * `search_path`, which is `"$user", public` — and the scaffold's role is named
+ * `rebase`, the same as a schema the generator creates. Left to itself the
+ * extension would install into `rebase`, and every unqualified `VECTOR(n)`
+ * below would fail to resolve.
+ */
+export const VECTOR_EXTENSION_SCHEMA = "public";
+
+/** The extension name a database has to name to let Rebase install pgvector. */
+export const VECTOR_EXTENSION = "vector";
+
+/**
+ * How a project says Rebase may install pgvector, quoted into the messages that
+ * have to name it. Spelled once so the option and the advice cannot drift.
+ */
+export const VECTOR_EXTENSION_OPT_IN = `database({ extensions: ["${VECTOR_EXTENSION}"] })`;
+
+/** Did the project give Rebase leave to install pgvector? */
+export const vectorExtensionDeclared = (extensions: readonly string[] | undefined): boolean =>
+    (extensions ?? []).includes(VECTOR_EXTENSION);
+
+/**
+ * Install pgvector — emitted only when the database asked for it.
+ *
+ * Opt-in because installing an extension is a decision with a deployment behind
+ * it: the image has to ship the library, the role has to be allowed to install
+ * it, and a managed provider has to have it on an allow-list. None of that is
+ * visible from inside the connection, so Rebase does not decide it. See
+ * `DatabaseOptions.extensions`.
+ *
+ * Withholding the statement is not withholding the *column*: the column is
+ * still created, and Postgres refuses it with `type "vector" does not exist`
+ * on a database where pgvector was never installed by hand. That error is the
+ * one this design accepts, and `vectorExtensionHint` is what makes it name
+ * {@link VECTOR_EXTENSION_OPT_IN} rather than nothing.
+ */
+export const vectorExtensionStatement = (): string =>
+    `CREATE EXTENSION IF NOT EXISTS ${VECTOR_EXTENSION} WITH SCHEMA ${VECTOR_EXTENSION_SCHEMA};`;
+
+/**
+ * The missing-pgvector explanation, appended to whichever error revealed it.
+ *
+ * Two readers, needing opposite things, which is why the branch is on the error
+ * text rather than on the configuration:
+ *
+ *  - **`type "vector" does not exist`** — nobody opted in and the database has
+ *    no pgvector. The fix is one line of config they cannot guess, so naming
+ *    the option *is* the hint.
+ *  - **the install itself failed** — the config is already right, and repeating
+ *    the option would send them to edit a correct line. What is missing is the
+ *    library on the server, or the grant.
+ *
+ * Lives here rather than beside either caller because both need it: the boot
+ * ensure raises the first through its action applier, and `rebase db push`
+ * raises it out of `applyVectorDdl`. A hint on only one path is how a bare
+ * `type "vector" does not exist` reaches somebody — which is the thing this
+ * exists to prevent.
+ */
+export const vectorExtensionHint = (message: string): string => {
+    const installRefused = /extension "vector" is not available/i.test(message)
+        || /(permission denied to create extension|must be (superuser|owner).{0,40}extension)/i.test(message);
+    if (installRefused) {
+        return (
+            "\n  pgvector was declared and could not be installed. It is a server extension, so it needs an image " +
+            "that ships the library (the scaffold's `pgvector/pgvector:pg18` does; a stock `postgres:18` does not) " +
+            "and a role allowed to run `CREATE EXTENSION vector;`. Managed Postgres usually allows it once the " +
+            "extension is on the provider's allow-list."
+        );
+    }
+    if (!/type "(vector|halfvec|sparsevec)" does not exist/i.test(message)) return "";
+    return (
+        "\n  pgvector is not installed on this database, and Rebase installs it only where a database says it may: " +
+        `add \`${VECTOR_EXTENSION_OPT_IN}\` in config/resources.ts, or install it once by hand with ` +
+        "`CREATE EXTENSION vector;`. Either way the server needs an image that ships the library — the scaffold's " +
+        "`pgvector/pgvector:pg18` does, a stock `postgres:18` does not. Rebase then creates the column and its ANN " +
+        "index automatically — see the `index` option on the property."
+    );
+};
+
+/** One `{ type: "vector" }` property, as a column. */
+export interface VectorColumnSpec {
+    schema: string;
+    table: string;
+    column: string;
+    dimensions: number;
+    /** Rendered after the type, in the generator's order: UNIQUE then NOT NULL. */
+    modifiers: string;
+}
+
+/**
+ * Every vector column a collection declares.
+ *
+ * Wider than {@link buildVectorIndexPlan} on purpose: that one answers "what
+ * gets an ANN index", and skips both a property with `index: false` and one too
+ * wide to index. Either still needs its column.
+ */
+export const buildVectorColumnSpecs = (
+    collection: CollectionConfig,
+    resolveColumn: (propName: string, prop?: Property | null) => string
+): VectorColumnSpec[] => {
+    const table = getTableName(collection);
+    const schema = isPostgresCollectionConfig(collection) && collection.schema ? collection.schema : "public";
+    const specs: VectorColumnSpec[] = [];
+
+    for (const [propName, prop] of Object.entries(collection.properties ?? {})) {
+        if (!isVectorProperty(prop)) continue;
+        // Assembled in the CREATE TABLE generator's order, so the column this
+        // file adds and the column `schema.sql` used to declare are the same
+        // column. A vector property is never a primary key and carries no
+        // SQL-level default, which is what leaves only these two.
+        const validation = (prop as { validation?: { required?: boolean; unique?: boolean } }).validation;
+        let modifiers = "";
+        if (validation?.unique) modifiers += " UNIQUE";
+        if (validation?.required) modifiers += " NOT NULL";
+        specs.push({
+            schema,
+            table,
+            column: resolveColumn(propName, prop as Property),
+            dimensions: prop.dimensions,
+            modifiers
+        });
+    }
+
+    return specs;
+};
+
+/** The column type — the one place `VECTOR(n)` is spelled. */
+export const vectorColumnType = (spec: Pick<VectorColumnSpec, "dimensions">): string =>
+    `VECTOR(${spec.dimensions})`;
+
+/** The column definition as it appears inside `CREATE TABLE`. */
+export const vectorColumnDefinition = (spec: VectorColumnSpec): string =>
+    `"${spec.column}" ${vectorColumnType(spec)}${spec.modifiers}`;
+
+/**
+ * Refuse — or perform — a `dimensions` change that `ADD COLUMN IF NOT EXISTS`
+ * would otherwise swallow.
+ *
+ * Without this the file *launders* the change: the ADD is a no-op against a
+ * column that exists, so a project that went from 384 to 768 dimensions would
+ * push clean, keep a 384-wide column, and fail on the next insert with a
+ * message about the row rather than about the config. Atlas used to catch this
+ * — it owned the column and planned the `ALTER … TYPE` — and taking the column
+ * out of its sight is exactly what makes the guard necessary.
+ *
+ * The widening is performed when the column holds no values, because that is
+ * the case Atlas handled and it is the common one: a developer changing
+ * embedding models before there are any embeddings. With values present the
+ * conversion is pgvector's to reject — every stored vector is the old width —
+ * so this refuses first and names the statement to run afterwards.
+ *
+ * `atttypmod` on a `vector` column *is* the dimension count: pgvector stores it
+ * directly rather than offsetting it the way `varchar` does. `-1` means the
+ * column was declared as a bare `vector`, which is drift in the same sense.
+ */
+export const vectorDimensionGuard = (spec: VectorColumnSpec): string => {
+    const relation = `"${spec.schema}"."${spec.table}"`;
+    return `DO $rebase_vector$
+DECLARE actual int;
+BEGIN
+    SELECT a.atttypmod INTO actual
+    FROM pg_attribute a
+    JOIN pg_type t ON t.oid = a.atttypid
+    WHERE a.attrelid = ${quote(relation)}::regclass
+      AND a.attname = ${quote(spec.column)}
+      AND NOT a.attisdropped
+      AND t.typname = 'vector';
+    IF actual IS NOT NULL AND actual <> ${spec.dimensions} THEN
+        IF EXISTS (SELECT 1 FROM ${relation} WHERE "${spec.column}" IS NOT NULL) THEN
+            RAISE EXCEPTION 'Rebase: ${spec.schema}.${spec.table}."${spec.column}" declares ${spec.dimensions} dimensions but the column is vector(%), and it already holds values of the old width. pgvector cannot convert them. Re-embed the rows at ${spec.dimensions} dimensions (or clear the column), then re-apply: ALTER TABLE ${relation} ALTER COLUMN "${spec.column}" TYPE ${vectorColumnType(spec)};', actual;
+        END IF;
+        ALTER TABLE ${relation} ALTER COLUMN "${spec.column}" TYPE ${vectorColumnType(spec)};
+    END IF;
+END
+$rebase_vector$;`;
+};
+
+/**
+ * The object names a collection's vector properties own, unqualified.
+ *
+ * What Atlas has to be told to exclude. Only the column and the ANN indexes: a
+ * `UNIQUE` or `NOT NULL` on the column is a property *of* the column, and
+ * excluding the column takes them with it — measured against Atlas 1.2.3 and
+ * 1.3.2, where a target carrying `vector(3) NOT NULL UNIQUE` and a `schema.sql`
+ * carrying neither reported "Schema is synced, no changes to be made".
+ */
+export const vectorObjectNames = (
+    collection: CollectionConfig,
+    resolveColumn: (propName: string, prop?: Property | null) => string
+): string[] => [
+    ...buildVectorColumnSpecs(collection, resolveColumn).map(spec => spec.column),
+    ...vectorIndexNames(buildVectorIndexPlan(collection, resolveColumn))
+];