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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-postgres",
   "type": "module",
-  "version": "0.17.1",
+  "version": "0.17.2-canary.g4d21a53",
   "description": "PostgreSQL data source backend implementation for Rebase with Drizzle ORM",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -47,11 +47,11 @@
     "execa": "^9.6.1",
     "pg": "^8.22.0",
     "ws": "^8.21.1",
-    "@rebasepro/codegen": "0.17.1",
-    "@rebasepro/utils": "0.17.1",
-    "@rebasepro/types": "0.17.1",
-    "@rebasepro/server": "0.17.1",
-    "@rebasepro/common": "0.17.1"
+    "@rebasepro/codegen": "0.17.2-canary.g4d21a53",
+    "@rebasepro/common": "0.17.2-canary.g4d21a53",
+    "@rebasepro/server": "0.17.2-canary.g4d21a53",
+    "@rebasepro/types": "0.17.2-canary.g4d21a53",
+    "@rebasepro/utils": "0.17.2-canary.g4d21a53"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.12",

package/src/cli-helpers.ts

@@ -264,42 +264,70 @@ export async function getSearchExcludes(collectionsPath: string): Promise<string
 }
 
 /**
- * Give the dev database the search helper functions before Atlas plans.
+ * The generated SQL for the project's `vector` properties, if it has any.
  *
- * Excluding the search column keeps Atlas from *diffing* it, but not from
- * materialising the inspected schema — column and all — in the dev database to
- * analyse the plan against. That replay is where a push against an
- * already-searchable database died with `function public.rebase_search_text
- * (jsonb) does not exist`: the column came across, the function it calls did
- * not, because Atlas will not carry a function at all.
+ * @param drizzleDir directory holding the generated SQL. Defaults to `drizzle`
+ *        under the working directory.
+ */
+export function readVectorDdl(drizzleDir: string = path.resolve(process.cwd(), "drizzle")): string {
+    const vectorFile = path.join(drizzleDir, "vector.sql");
+    if (!fs.existsSync(vectorFile)) return "";
+    return fs.readFileSync(vectorFile, "utf-8").trim();
+}
+
+/**
+ * Install pgvector and bring the vector columns and their ANN indexes up to
+ * date.
  *
- * Only the extensions and functions, never the tables: the dev database holds
- * whatever Atlas puts there and nothing of ours.
+ * Runs *after* Atlas, like {@link applySearchDdl} and for the same reason: the
+ * statements are `ALTER TABLE … ADD COLUMN`, so the table has to exist. Atlas
+ * is told to ignore these objects entirely ({@link getVectorExcludes}) — it
+ * cannot manage a type its dev database is structurally incapable of having,
+ * and left to itself it would plan a `DROP COLUMN` for every one.
  *
- * Best-effort by design. Failing here would block a push for a project whose
- * collections merely failed to import, and if the functions really are needed
- * and really are missing, Atlas says so a moment later in its own words.
+ * A no-op when no collection declares a `vector` property. A failure is *not*
+ * swallowed: a push that reported success while the embedding column never
+ * appeared is how a project ends up with vector search configured, no error
+ * anywhere, and no results.
  */
-export async function seedDevDatabaseSearchHelpers(
-    devDatabaseUrl: string,
-    collectionsPath: string
+export async function applyVectorDdl(
+    databaseUrl: string,
+    drizzleDir: string = path.resolve(process.cwd(), "drizzle")
 ): Promise<void> {
-    try {
-        const { searchPrerequisiteStatements } = await import("./schema/generate-postgres-ddl-logic");
-        const statements = searchPrerequisiteStatements(await loadCollectionsForCli(collectionsPath));
-        if (statements.length === 0) return;
+    const sql = readVectorDdl(drizzleDir);
+    if (!sql) return;
 
-        const { Client } = await import("pg");
-        const client = new Client({ connectionString: devDatabaseUrl });
-        await client.connect();
-        try {
-            await client.query(statements.join("\n"));
-        } finally {
-            await client.end();
-        }
-    } catch {
-        // See above: not worth failing a push over.
+    const { vectorExtensionHint } = await import("./schema/vector-index");
+    const { Client } = await import("pg");
+    const client = new Client({ connectionString: databaseUrl });
+    await client.connect();
+    try {
+        await client.query(sql);
+    } catch (err) {
+        // The boot ensure explains this failure and the push has to as well —
+        // it is the same missing extension, and a push is the *more* likely
+        // place to meet it. Without this the developer gets a bare
+        // `type "vector" does not exist`, which names nothing they can act on
+        // and reads like a broken database rather than a line of config.
+        const message = err instanceof Error ? err.message : String(err);
+        const hint = vectorExtensionHint(message);
+        if (!hint) throw err;
+        throw new Error(`${message}${hint}`, { cause: err });
+    } finally {
+        await client.end();
     }
+    out(chalk.gray("  ✓ Applied vector columns and ANN indexes"));
+}
+
+/**
+ * Glob patterns keeping Atlas away from the vector objects.
+ *
+ * Returns an empty list — and so changes nothing — for a project with no
+ * `vector` property, which is every project that has not opted in.
+ */
+export async function getVectorExcludes(collectionsPath: string): Promise<string[]> {
+    const { vectorExcludePatterns } = await import("./schema/generate-postgres-ddl-logic");
+    return vectorExcludePatterns(await loadCollectionsForCli(collectionsPath));
 }
 
 /**
@@ -405,16 +433,19 @@ export async function getForeignIndexExcludes(
  */
 async function managedIndexNames(collectionsPath: string): Promise<Set<string>> {
     const collections = await loadCollectionsForCli(collectionsPath);
-    const { resolveColumnName, searchExcludePatterns } = await import("./schema/generate-postgres-ddl-logic");
+    const { resolveColumnName, searchExcludePatterns, vectorExcludePatterns } =
+        await import("./schema/generate-postgres-ddl-logic");
     const { buildCollectionIndexPlan } = await import("./schema/collection-index");
 
     const names = new Set<string>(
         buildCollectionIndexPlan(collections, resolveColumnName).map(spec => spec.indexName)
     );
-    // Search objects are excluded from Atlas wholesale by their own patterns;
-    // listing them here too is harmless and keeps this the single answer to
-    // "is this index one of ours".
-    for (const pattern of searchExcludePatterns(collections)) {
+    // Search and vector objects are excluded from Atlas wholesale by their own
+    // patterns; listing them here too is harmless and keeps this the single
+    // answer to "is this index one of ours". The doc comment above claimed
+    // vector was here long before it was — so an ANN index answered that
+    // question with "somebody else's".
+    for (const pattern of [...searchExcludePatterns(collections), ...vectorExcludePatterns(collections)]) {
         names.add(pattern.slice(pattern.lastIndexOf(".") + 1));
     }
     return names;

package/src/cli.ts

@@ -16,7 +16,9 @@ import {
     applySearchDdl,
     getSearchExcludes,
     readSearchDdl,
-    seedDevDatabaseSearchHelpers,
+    applyVectorDdl,
+    getVectorExcludes,
+    readVectorDdl,
     getTableExcludes,
     getForeignIndexExcludes,
     ExcludeIntrospectionError,
@@ -26,6 +28,8 @@ import { checkDatabaseConnectivity, diagnoseDbError } from "./cli-errors";
 import { forLibpq } from "./utils/connection-string";
 import { dropLegacyAuthSchema, RLS_BOOTSTRAP_SQL } from "./schema/rls-bootstrap-sql";
 import { detectDestructiveStatements, decidePushSafety } from "./schema/destructive-sql";
+import { stripCarvedOutStatements } from "./schema/carved-out-migration";
+import { acceptsExcludeFlag, buildAtlasArgs } from "./schema/atlas-argv";
 
 const __cliDirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -90,6 +94,82 @@ function listMigrationFiles(): string[] {
     return fs.readdirSync(dir).filter(f => f.endsWith(".sql")).sort();
 }
 
+/**
+ * Take Atlas's carve-outs back out of the migration `migrate diff` just wrote.
+ *
+ * The apply path hands Atlas `--exclude` and it never sees the search or vector
+ * columns. The diff path has no such flag — `atlas migrate diff` rejects
+ * `--exclude` outright, and an `atlas.hcl` `env` block's `exclude` is accepted
+ * and then ignored — so Atlas replays the migration directory (which builds
+ * both columns, because that DDL is appended to migrations), does not find them
+ * in `schema.sql`, and plans `DROP COLUMN`. Applied, that would take search and
+ * the embeddings away from every database the migration reaches.
+ *
+ * Returns whether a migration Atlas just wrote is still there afterwards: a
+ * file whose only content was the spurious drop is deleted, because an empty
+ * migration is worse than none — it takes a slot in the revision history and
+ * the caller would append the carved-out DDL and the policies to it.
+ *
+ * @returns true when a new migration survives and may be appended to.
+ */
+async function stripCarvedOutFromNewestMigration(collectionsPath: string): Promise<boolean> {
+    // Both carve-outs, for one reason: they are the same problem. Search is out
+    // of Atlas's sight because its free tier will not parse a function; vector
+    // is out because Atlas resolves the desired state in a dev database that
+    // can never have pgvector. What follows from that is identical — the diff
+    // replays a migration directory holding objects `schema.sql` omits, and
+    // plans a drop for every one.
+    const patterns = [
+        ...await getSearchExcludes(collectionsPath),
+        ...await getVectorExcludes(collectionsPath)
+    ];
+    if (patterns.length === 0) return true;
+
+    const newest = listMigrationFiles().at(-1);
+    if (!newest) return false;
+    const file = path.resolve(process.cwd(), "drizzle", "migrations", newest);
+
+    const result = stripCarvedOutStatements(fs.readFileSync(file, "utf-8"), patterns);
+
+    // Fail CLOSED, and loudly. A drop this could not rewrite stays in the file
+    // exactly as Atlas wrote it, and the file is one somebody applies next week
+    // — by which time the column is gone and nothing connects it to this run.
+    // The destructive gate does not cover it either: that reads the *push*
+    // plan. So `db generate` stops here rather than hand back a migration that
+    // destroys a column the developer never asked to lose.
+    if (result.unhandled.length > 0) {
+        outError(chalk.red(
+            `\n  ✗ ${newest} drops an object Rebase manages outside Atlas, in a form the CLI`
+        ));
+        outError(chalk.red("    could not remove:"));
+        for (const statement of result.unhandled) {
+            outError(chalk.gray(`       ${statement.replace(/\s+/g, " ")}`));
+        }
+        outError(chalk.gray(
+            "    Left as Atlas wrote it. Delete those statements by hand before running\n" +
+            "    `rebase db migrate` — and please report them: rewriting this is meant to\n" +
+            "    be automatic."
+        ));
+        process.exit(1);
+    }
+
+    if (result.removed.length === 0) return true;
+
+    if (result.empty) {
+        fs.rmSync(file);
+        out(chalk.gray(
+            `  ✓ Dropped ${newest} — it planned nothing but the removal of columns\n` +
+            "    Atlas cannot see and Rebase applies itself."
+        ));
+    } else {
+        fs.writeFileSync(file, result.sql, "utf-8");
+        out(chalk.gray(`  ✓ Kept Rebase's own columns out of ${newest} (${result.removed.length} statement(s))`));
+    }
+
+    await runAtlas("migrate", ["hash", "--dir", "file://drizzle/migrations"], collectionsPath);
+    return !result.empty;
+}
+
 async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
     const VALID_ACTIONS = ["push", "generate", "migrate", "branch", "backup", "restore", "backups"];
     if (!subcommand || !VALID_ACTIONS.includes(subcommand)) {
@@ -97,6 +177,20 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
         process.exit(1);
     }
 
+    // A second line of defence, and not a redundant one. `rebase db` answers
+    // `--help` before it ever spawns this file, but this file is also its own
+    // CLI — the driver is spawned directly by `resolvePluginCliScript`, and is
+    // executable on its own — so a `--help` reaching here means nobody upstream
+    // caught it. Only `branch` had a case for it; `push`, `migrate` and
+    // `restore` all took `--help` as an ordinary flag and did the work.
+    if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+        out("");
+        out(chalk.bold(`  rebase db ${subcommand}`));
+        out(chalk.gray("  Run `rebase db --help` for the full page — this is the driver's own entry point."));
+        out("");
+        return;
+    }
+
     if (subcommand === "branch") {
         await branchCommand(rawArgs);
         return;
@@ -138,12 +232,27 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
         const migrationName = argsList._[0] || "migration";
         const migrationsBefore = listMigrationFiles();
         await runAtlas("migrate", ["diff", migrationName, "--dir", "file://drizzle/migrations", "--to", "file://drizzle/schema.sql"], collectionsPath);
-        const wroteNewMigration = listMigrationFiles().length > migrationsBefore.length;
+        // The diff cannot be told to ignore the carved-out objects the way the
+        // apply can, so the drop it plans for them is taken back out of the
+        // file it just wrote. A migration that was nothing else is deleted.
+        let wroteNewMigration = listMigrationFiles().length > migrationsBefore.length;
+        if (wroteNewMigration) {
+            wroteNewMigration = await stripCarvedOutFromNewestMigration(collectionsPath);
+        }
         
-        // Post-process the newest migration file
+        // Post-process the migration Atlas just wrote.
+        //
+        // `wroteNewMigration` gates the whole block, and that gate is the point.
+        // "The newest migration file" is only Atlas's when Atlas wrote one;
+        // otherwise it is a migration that has already run in production, and
+        // appending to it changes a hash Atlas has recorded while the appended
+        // SQL never runs anywhere. The search half already said so and checked;
+        // the `CREATE SCHEMA` rewrite and the policy append did not, so every
+        // `db generate` that found nothing to diff still grew the last
+        // migration by another copy of the policies.
         try {
             const migrationsDir = path.resolve(process.cwd(), "drizzle", "migrations");
-            if (fs.existsSync(migrationsDir)) {
+            if (fs.existsSync(migrationsDir) && wroteNewMigration) {
                 const files = fs.readdirSync(migrationsDir);
                 const sqlFiles = files
                     .filter(f => f.endsWith(".sql"))
@@ -159,31 +268,27 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
                         /CREATE SCHEMA (?!IF NOT EXISTS)("[^"]+");/g,
                         "CREATE SCHEMA IF NOT EXISTS $1;"
                     );
-                    // Atlas never writes the search objects into a migration —
-                    // it is not shown them — so a migration replayed against a
-                    // fresh database would build every table except the part
-                    // that makes search work. Appending, because these are
-                    // `ALTER TABLE ... ADD COLUMN` over the tables the
-                    // migration just created.
+                    // Atlas never writes the search or vector objects into a
+                    // migration — it is not shown them — so a migration
+                    // replayed against a fresh database would build every table
+                    // except the parts that make search and vector search work.
+                    // Appending, because these are `ALTER TABLE ... ADD COLUMN`
+                    // over the tables the migration just created.
                     //
-                    // Only into a migration Atlas just wrote. The file picked
-                    // here is simply the newest one, which when there was no
-                    // diff is a migration that has already run in production:
-                    // editing it changes a hash Atlas has recorded, and the
-                    // appended SQL would never be applied anywhere.
+                    // Vector first: `vector.sql` may open with
+                    // `CREATE EXTENSION vector`, so prerequisites lead, which is
+                    // the order a reader of the migration expects. Nothing in
+                    // search depends on it either way.
+                    const vectorContent = readVectorDdl();
+                    if (vectorContent) {
+                        migrationContent = `${migrationContent}\n\n${vectorContent}`;
+                        out(chalk.gray("  ✓ Appended vector DDL to the migration"));
+                    }
+
                     const searchContent = readSearchDdl();
-                    if (searchContent && wroteNewMigration) {
+                    if (searchContent) {
                         migrationContent = `${migrationContent}\n\n${searchContent}`;
                         out(chalk.gray("  ✓ Appended search DDL to the migration"));
-                    } else if (searchContent) {
-                        // Reachable whenever a `search` block is the *only*
-                        // thing that changed: Atlas cannot see one, so it finds
-                        // nothing to diff and writes no file.
-                        out(chalk.gray(
-                            "  ℹ Search DDL not written to a migration — this change produced none.\n" +
-                            "    It is applied by `rebase db push`, and at boot by the schema ensure.\n" +
-                            "    For a migration-only deployment, add drizzle/search.sql to a migration by hand."
-                        ));
                     }
 
                     fs.writeFileSync(newestMigrationFile, migrationContent, "utf-8");
@@ -197,7 +302,7 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
                         const policiesContent = fs.readFileSync(policiesFile, "utf-8");
                         fs.appendFileSync(newestMigrationFile, "\n\n" + RLS_BOOTSTRAP_SQL + "\n" + policiesContent);
                         out(chalk.gray(`  ✓ Appended RLS policies to migration file: ${path.basename(newestMigrationFile)}`));
-                        
+
                         // Re-hash the migration directory
                         out(chalk.gray("  Re-hashing migration files..."));
                         await runAtlas("migrate", ["hash", "--dir", "file://drizzle/migrations"], collectionsPath);
@@ -209,6 +314,20 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
             outWarn(chalk.yellow(`  ⚠️  Failed to append policies or re-hash migration: ${err instanceof Error ? err.message : String(err)}`));
         }
 
+        if (!wroteNewMigration) {
+            // Reachable whenever the only thing that changed is something Atlas
+            // cannot see — a `search` block, a `vector` property, or a
+            // `securityRules` edit. There is no new file to carry it, and the
+            // previous migration must not be reopened: it has already run
+            // wherever this project is deployed.
+            out(chalk.gray(
+                "  ℹ No migration written — nothing in this change is visible to Atlas.\n" +
+                "    Search, vector and RLS DDL are applied by `rebase db push`, and at boot by\n" +
+                "    the schema ensure. For a migration-only deployment, add drizzle/search.sql,\n" +
+                "    drizzle/vector.sql and drizzle/policies.sql to a migration by hand."
+            ));
+        }
+
         out("");
         out(`  You can now run ${chalk.bold.green("rebase db migrate")} to apply the migrations to your database.`);
         out("");
@@ -283,9 +402,10 @@ async function dbCommand(subcommand: string, rawArgs: string[]): Promise<void> {
             
             if (databaseUrl) {
                 await ensureAuthTables(databaseUrl, collectionsPath);
-                // After the tables exist and before the policies: the search
-                // column is `ALTER TABLE ... ADD COLUMN`, and a policy may
-                // reference the table it is added to.
+                // After the tables exist and before the policies: the vector and
+                // search columns are `ALTER TABLE ... ADD COLUMN`, and a policy
+                // may reference the table they are added to.
+                await applyVectorDdl(databaseUrl);
                 await applySearchDdl(databaseUrl);
                 await applyPolicies(databaseUrl);
                 await reconcilePolicies(databaseUrl, collectionsPath);
@@ -812,9 +932,6 @@ async function runAtlas(
 
     const devDatabaseUrl = getDevDatabaseUrl(databaseUrl);
     await ensureDevDatabaseExists(databaseUrl, devDatabaseUrl);
-    if (collectionsPath) {
-        await seedDevDatabaseSearchHelpers(devDatabaseUrl, collectionsPath);
-    }
 
     // Atlas speaks libpq, which rejects the `sslmode=no-verify` that
     // node-postgres accepts — see `forLibpq`. Rewritten only for the argv, so
@@ -822,43 +939,28 @@ async function runAtlas(
     const atlasUrl = forLibpq(databaseUrl);
     const atlasDevUrl = forLibpq(devDatabaseUrl);
 
-    const atlasArgs = [domain, ...args];
-
-    if (domain === "schema") {
-        if (args.includes("apply")) {
-            atlasArgs.push("--url", atlasUrl, "--dev-url", atlasDevUrl);
-        } else if (args.includes("clean") || args.includes("inspect")) {
-            atlasArgs.push("--url", atlasUrl);
-        }
-    } else if (domain === "migrate") {
-        if (args.includes("diff")) {
-            atlasArgs.push("--dev-url", atlasDevUrl);
-        } else if (args.includes("apply") || args.includes("status")) {
-            atlasArgs.push("--url", atlasUrl, "--revisions-schema", "rebase");
-            if (args.includes("apply")) {
-                atlasArgs.push("--allow-dirty");
-            }
-        }
-    }
-
-    // Search objects are Rebase's, not Atlas's — on both paths. `schema apply`
-    // would drop them as absent from the desired state; `migrate diff` would
-    // write that same drop into the next migration file, where it would sit
-    // waiting to be applied later.
-    if (collectionsPath && (args.includes("apply") || args.includes("diff"))) {
-        for (const exc of await getSearchExcludes(collectionsPath)) {
-            atlasArgs.push("--exclude", exc);
-        }
-    }
+    // Everything Atlas must keep its hands off, in one list.
+    //
+    // Gathered only for the invocations that accept the flag — which is
+    // `schema apply` and nothing else. `atlas migrate diff` and `migrate apply`
+    // both reject `--exclude` outright with `unknown flag`, and passing it there
+    // took `rebase db generate` and `rebase db migrate` down for every project
+    // declaring a `search` block; the diff keeps the same objects out of the
+    // migration afterwards instead, with `stripCarvedOutStatements`. See
+    // `acceptsExcludeFlag`.
+    const excludes: string[] = [];
+    if (collectionsPath && acceptsExcludeFlag(domain, args)) {
+        // Search and vector objects are Rebase's, not Atlas's: the desired state
+        // does not carry them, so an apply left to itself would drop them.
+        excludes.push(...await getSearchExcludes(collectionsPath));
+        excludes.push(...await getVectorExcludes(collectionsPath));
 
-    if (domain === "schema" && args.includes("apply") && collectionsPath) {
         // Fail CLOSED: the exclude list is the only thing shielding
         // non-collection tables from the auto-approved apply. If we can't
         // introspect the database to build it, abort rather than proceed with
         // a partial list that would let Atlas drop unmanaged tables.
-        let excludes: string[];
         try {
-            excludes = await getTableExcludes(databaseUrl, collectionsPath);
+            excludes.push(...await getTableExcludes(databaseUrl, collectionsPath));
         } catch (err) {
             if (err instanceof ExcludeIntrospectionError) {
                 outError(chalk.red("\n✗ Aborting push: could not determine which tables to protect."));
@@ -870,16 +972,12 @@ async function runAtlas(
             }
             throw err;
         }
-        for (const exc of excludes) {
-            atlasArgs.push("--exclude", exc);
-        }
 
         // And the indexes on those tables that Rebase did not create. Same
         // fail-closed contract as the table list above, for the same reason: a
         // partial answer here silently drops somebody's index.
-        let indexExcludes: string[];
         try {
-            indexExcludes = await getForeignIndexExcludes(databaseUrl, collectionsPath);
+            excludes.push(...await getForeignIndexExcludes(databaseUrl, collectionsPath));
         } catch (err) {
             if (err instanceof ExcludeIntrospectionError) {
                 outError(chalk.red("\n✗ Aborting push: could not determine which indexes to protect."));
@@ -891,11 +989,10 @@ async function runAtlas(
             }
             throw err;
         }
-        for (const exc of indexExcludes) {
-            atlasArgs.push("--exclude", exc);
-        }
     }
 
+    const atlasArgs = buildAtlasArgs({ domain, args, url: atlasUrl, devUrl: atlasDevUrl, excludes });
+
     // Stream stdout live but tee stderr so we can inspect Atlas's error text
     // for known, actionable failure modes (e.g. a dependency-drop that leaves
     // the schema half-applied) after the process exits. When capturing (used

package/src/schema/atlas-argv.ts

@@ -0,0 +1,94 @@
+/**
+ * The argv `runAtlas` hands the Atlas binary, as a pure function.
+ *
+ * Split out of `cli.ts` because the flags an Atlas subcommand accepts are not
+ * uniform and getting one wrong is fatal rather than degraded: Atlas rejects an
+ * unknown flag before doing any work, so a flag on the wrong subcommand takes
+ * the whole command down.
+ *
+ * `--exclude` is the one that bit. Of the six invocations here, exactly one
+ * accepts it. The guard this replaces was `args.includes("apply") ||
+ * args.includes("diff")`, and reading it as a *subcommand* test is the trap:
+ * `migrate apply` passes `args.includes("apply")` just as `schema apply` does.
+ * So the flag went onto three invocations, two of which reject it, and both
+ * `rebase db generate` and `rebase db migrate` exited 1 with `unknown flag:
+ * --exclude` for every project declaring a `search` block.
+ *
+ * The domain is half the identity of an Atlas subcommand, and a guard that
+ * looks only at `args` cannot tell `schema apply` from `migrate apply`.
+ *
+ * Nothing here touches a database or the filesystem, so the whole matrix is
+ * unit-tested in `atlas-argv.test.ts`.
+ */
+
+export interface AtlasInvocation {
+    /** `schema` or `migrate`. */
+    domain: string;
+    /** The subcommand and its own flags, e.g. `["diff", "--dir", "file://…"]`. */
+    args: string[];
+    /** The target database, already rewritten for libpq. */
+    url: string;
+    /** The database Atlas plans against, already rewritten for libpq. */
+    devUrl: string;
+    /**
+     * Everything the caller resolved for `--exclude`, in the order it should
+     * appear. Dropped entirely when the subcommand does not accept the flag —
+     * see {@link acceptsExcludeFlag}.
+     */
+    excludes?: string[];
+}
+
+/**
+ * Does this Atlas invocation accept `--exclude`?
+ *
+ * Only `atlas schema apply` does, on the pinned 1.2.3. Measured against the
+ * binary: `migrate diff` and `migrate apply` both answer `unknown flag:
+ * --exclude`, and neither lists it in `--help` (`migrate apply` offers
+ * `--url/--dir/--format/--revisions-schema/--dry-run/--lock-name/--lock-timeout/`
+ * `--skip-lock/--baseline/--to-version/--tx-mode/--exec-order/--allow-dirty`).
+ * Hence `domain === "schema"` and not just the subcommand.
+ *
+ * The `exclude` attribute of an `atlas.hcl` `env` block is not a way round it
+ * either: measured, it is accepted and then ignored on the diff path, which is
+ * the silent-no-match shape that costs the most time to notice.
+ *
+ * So the diff keeps the carved-out objects out of the migration afterwards
+ * instead, with `stripCarvedOutStatements`.
+ */
+export function acceptsExcludeFlag(domain: string, args: string[]): boolean {
+    return domain === "schema" && args.includes("apply");
+}
+
+/** Assemble the full argv, connection flags and all. */
+export function buildAtlasArgs(invocation: AtlasInvocation): string[] {
+    const { domain, args, url, devUrl, excludes = [] } = invocation;
+    const argv = [domain, ...args];
+
+    if (domain === "schema") {
+        if (args.includes("apply")) {
+            argv.push("--url", url, "--dev-url", devUrl);
+        } else if (args.includes("clean") || args.includes("inspect")) {
+            argv.push("--url", url);
+        }
+    } else if (domain === "migrate") {
+        if (args.includes("diff")) {
+            argv.push("--dev-url", devUrl);
+        } else if (args.includes("apply") || args.includes("status")) {
+            argv.push("--url", url, "--revisions-schema", "rebase");
+            if (args.includes("apply")) {
+                argv.push("--allow-dirty");
+            }
+        }
+    }
+
+    // Second line of defence, deliberately not a caller's responsibility: a
+    // future caller that resolves excludes for the diff path gets them dropped
+    // here rather than a command that will not run.
+    if (acceptsExcludeFlag(domain, args)) {
+        for (const exclude of excludes) {
+            argv.push("--exclude", exclude);
+        }
+    }
+
+    return argv;
+}