@rebasepro/server-postgres 0.17.3 → 0.18.0

package/LICENSE

@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

package/README.md

@@ -8,6 +8,37 @@ PostgreSQL database driver for Rebase, built on Drizzle ORM.
 pnpm add @rebasepro/server-postgres
 ```
 
+This package is ESM-only (`"type": "module"`, no CommonJS build), so it is
+loaded with `import`. `require()` of it from a CJS file works only on Node
+22.12+, which supports `require(esm)`.
+
+### Allow `@ariga/atlas` to run its install script
+
+`db push`, `db generate` and `db migrate` shell out to the `atlas` binary, and
+`@ariga/atlas` downloads that binary in a `preinstall` script. pnpm 10+ and npm
+12+ refuse a dependency's lifecycle scripts unless the project allowlists them —
+and the install still exits 0, so the only sign is
+`ERR_PNPM_IGNORED_BUILDS: @ariga/atlas` several screens up, followed by
+`Failed to create bin … ENOENT`. Nothing then fails until the first schema push.
+
+A project scaffolded by `rebase init` already carries the entry. Adding this
+package to an existing project needs it:
+
+```yaml
+# pnpm-workspace.yaml
+allowBuilds:
+  "@ariga/atlas": true
+```
+
+```json
+// package.json, for npm
+{ "allowScripts": { "@ariga/atlas": true } }
+```
+
+`rebase doctor` reports the state of that binary, and tells the three apart:
+not installed, installed with its script blocked, and on disk with only the
+`node_modules/.bin` link missing.
+
 ## What This Package Does
 
 Implements the Rebase `DatabaseAdapter` / `BackendBootstrapper` interfaces for PostgreSQL. It provides connection pooling, a Drizzle-based data driver, Postgres LISTEN/NOTIFY realtime, auth table management, snapshot history, schema generation, branching, read replicas, and WebSocket support. Plug it into `@rebasepro/server` via `createPostgresAdapter()` or `createPostgresBootstrapper()`.

package/dist/backup-argv.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which of the two things `rebase db backup …` means.
+ *
+ * The cloud family spells the listing `rebase cloud db backup list`. Locally
+ * the same words *created a backup*: `backup` dispatched straight to
+ * `backupCommand`, which parsed permissively and dropped "list" into the
+ * positionals it never reads. One CLI, two spellings, and the wrong guess wrote
+ * a dump instead of reading one — quiet, slow, and on a large database not
+ * free.
+ *
+ * A separate module for the same reason `branch-argv.ts` is one: the decision
+ * is pure, and the dispatch it lives in cannot be imported without loading the
+ * environment and reaching for a database.
+ */
+export type BackupAction = "create" | "list";
+/**
+ * @param rawArgs the driver's whole line, `["db", "backup", …]`.
+ */
+export declare function backupActionOf(rawArgs: readonly string[]): BackupAction;

package/dist/branch-argv.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Argument shapes for `rebase db branch`, with no dependencies.
+ *
+ * Its own module for the same reason `schema/atlas-argv.ts` is: `cli.ts` pulls
+ * in chalk, execa and the driver runtime, so a unit test that imports it cannot
+ * run. Argv parsing is the part most worth testing and the part least in need
+ * of any of that.
+ */
+/**
+ * Words on a `db branch` command line that no argument accounts for.
+ *
+ * `rebase db branch create alpha beta` created a branch called `alpha` and
+ * threw `beta` away without a word. The shapes that produces are all quiet and
+ * all wrong: an unquoted name (`create my feature` → `my`), a flag written
+ * without its dashes (`create feat from main` → `feat`), a shell that split
+ * something you thought was one token. In each case the command succeeds and
+ * the branch is not the one asked for — and branch names are the thing you
+ * later type to switch, delete, or point a deploy at.
+ *
+ * Anything starting with `-` is left alone rather than validated. This runs on
+ * every branch subcommand, including ones added later with flags this function
+ * has never heard of, and rejecting an unrecognised flag here would break them
+ * from a distance. The value after a flag that takes one is skipped for the
+ * same reason: it is that flag's argument, not a stray word.
+ *
+ * @param words The command's own arguments: action, name, then the rest.
+ */
+export declare function unexpectedBranchArgs(words: readonly string[]): string[];

package/dist/branch-prune.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What `rebase db branch prune` should remove, decided without a database.
+ *
+ * Branching had no cleanup story at all: no TTL, no prune, no `delete --all`,
+ * and every branch is a **full-size copy** — `CREATE DATABASE ... TEMPLATE`
+ * duplicates the files on disk, so five branches of a 100 GB database cost
+ * 500 GB. The only way to reclaim any of it was to remember every name you had
+ * ever typed.
+ *
+ * Three things drift apart, and they are not the same problem:
+ *
+ * 1. **Stale rows** — `rebase.branches` says a branch exists and its database
+ *    is gone. Someone dropped it with plain SQL, or restored the cluster from
+ *    a backup taken before it. The row is what `list` reads, so the branch goes
+ *    on being reported forever; `switch` and `info` then fail against a
+ *    database nothing can find.
+ *
+ * 2. **Orphan databases** — an `rb_*` database with no row. `createBranch`
+ *    creates the database first and records it second, so a crash between the
+ *    two leaves exactly this: disk consumed by something no Rebase command will
+ *    ever mention again.
+ *
+ * 3. **Expired branches** — alive, registered, and older than you meant to keep.
+ *    This is the ordinary case and the reason the command exists.
+ *
+ * Atlas's scratch databases are reported alongside but never removed by
+ * default. `rebase db push` creates `<db>_dev_diff` to compute its diff against
+ * and does not always clean it up, so they accumulate next to the branches and
+ * look like them. They are not branches, and one may belong to an Atlas run
+ * happening right now — so this names them and leaves the decision to a flag.
+ */
+/** A branch as `rebase.branches` records it. */
+export interface BranchRow {
+    name: string;
+    dbName: string;
+    createdAt: Date;
+}
+export interface PrunePlan {
+    /** Registered, but the database is gone. Remove the row only. */
+    staleRows: BranchRow[];
+    /** An `rb_*` database with no row. Drop the database only. */
+    orphanDatabases: string[];
+    /** Alive, registered, older than the cutoff. Drop both. */
+    expired: {
+        branch: BranchRow;
+        ageDays: number;
+    }[];
+    /** Atlas scratch databases. Reported; removed only when asked. */
+    devDiff: string[];
+}
+/** True when nothing at all needs doing. */
+export declare function planIsEmpty(plan: PrunePlan, includeDevDiff: boolean): boolean;
+/**
+ * Age in whole days, floored.
+ *
+ * Floored rather than rounded so `--older-than 7` never catches something six
+ * and a half days old: a prune that removes more than it said it would is worse
+ * than one that waits another twelve hours.
+ */
+export declare function ageInDays(createdAt: Date, now: Date): number;
+/**
+ * Parse `--older-than`. Accepts a bare number of days, or `7d` / `2w`.
+ *
+ * Returns null for anything else, so the caller refuses rather than guessing —
+ * silently reading `--older-than 7h` as seven *days* would delete a week of
+ * work.
+ */
+export declare function parseOlderThan(value: string): number | null;
+export declare function planPrune(input: {
+    rows: readonly BranchRow[];
+    /** Every database name on the server. */
+    databases: readonly string[];
+    branchPrefix: string;
+}, options?: {
+    olderThanDays?: number | null;
+    now?: Date;
+}): PrunePlan;

package/dist/cli-collections-path.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Thrown rather than exited, so the tests can see it and the entry point owns
+ * the exit code.
+ *
+ * `alreadyReported` is read by `reportCommandFailure`: the full diagnosis is on
+ * stderr by the time this is thrown, and the point of the whole change is that
+ * it is printed once.
+ */
+export declare class CollectionsPathMissing extends Error {
+    readonly typed: string;
+    readonly resolved: string;
+    readonly alreadyReported = true;
+    constructor(typed: string, resolved: string);
+}
+/**
+ * The whole message, in one place, because it is printed by two callers.
+ *
+ * Names what was typed, what it resolved to, and the working directory it
+ * resolved against — a relative `--collections` is resolved against the cwd,
+ * and the generated npm script runs with `cwd: backend/`, so "the path is
+ * right and the directory is wrong" is the commonest way to arrive here.
+ */
+export declare function describeMissingCollectionsPath(typed: string, resolved: string): string;
+/**
+ * Refuse a `--collections` path that does not exist.
+ *
+ * `null` means the flag was not given: the default (`../config/collections`) is
+ * left to the loader, which warns and continues — a project may legitimately
+ * have no collections directory, and a headless scaffold does.
+ */
+export declare function assertCollectionsPathExists(typed: string | null): void;

package/dist/cli-errors.d.ts

@@ -26,6 +26,26 @@ export declare function isSslNotEnabled(err: unknown): boolean;
  * an enum type it defined is still referenced by another object.
  */
 export declare function isDependencyDropError(err: unknown): boolean;
+/**
+ * Parse host:port from a DATABASE_URL for display purposes.
+ *
+ * Exported because every message about a connection has to name the thing it
+ * could not reach, and the boot path needs the same rendering the CLI banners
+ * use — including the same refusal to print the URL itself, which carries the
+ * password.
+ */
+export declare function parseHostInfo(databaseUrl: string): string;
+/**
+ * The sentence the operating system actually produced, dug out of the wrappers.
+ *
+ * `connect ECONNREFUSED 127.0.0.1:5432` is written by `net`, then wrapped by
+ * `pg`, then wrapped again by Drizzle as `Failed query: …` — and on a
+ * dual-stack host it is not in `.cause` at all but inside the
+ * `AggregateError.errors` array of one attempt per resolved address. Printing
+ * the banner without it loses the one token every search engine, runbook and
+ * colleague recognises.
+ */
+export declare function deepestErrorMessage(err: unknown): string | null;
 /**
  * Pre-flight check: verify that the database is reachable before running
  * a heavy subprocess (Atlas, migrations, etc.).
@@ -40,3 +60,106 @@ export declare function checkDatabaseConnectivity(databaseUrl: string): Promise<
  * or null if unrecognized.
  */
 export declare function diagnoseDbError(err: unknown, databaseUrl?: string): string | null;
+/**
+ * Say why the command failed, on the way out.
+ *
+ * The entry point below used to be `.catch(() => process.exit(1))`, which threw
+ * the error away. Every message this file and its services raise — "Branch
+ * \"x\" already exists.", "the source database has active connections", "Branch
+ * name is too long" — was written, wrapped in the right PG error code, and then
+ * discarded one frame before it reached a terminal. What a developer saw was a
+ * header line, no error, and exit 1.
+ *
+ * Two shapes are deliberately kept quiet:
+ *
+ * - **A child process that already spoke.** Atlas, `pg_dump` and `psql` run
+ *   with inherited stdio, so their diagnosis is on the terminal already and
+ *   execa's wrapper adds only `Command failed with exit code 1: atlas …`.
+ *   `packages/cli` filters exactly these two phrasings one level up
+ *   (`runDbCommand`), and this is that filter, for the process that is actually
+ *   throwing.
+ *
+ * - **A message that is only a query.** Drizzle reports failures as
+ *   `Failed query: <sql> params:` and hides the real PostgreSQL error in
+ *   `cause`, so the wrapper alone tells a reader nothing they can act on. The
+ *   cause is appended when it says something the message does not.
+ *
+ * - **An error that has already printed its own diagnosis**, marked
+ *   `alreadyReported`. `CollectionsPathMissing` is one: it prints the path, what
+ *   it resolved to and the cwd it resolved against, and then throws so the entry
+ *   point owns the exit code. Repeating its one-line summary underneath would
+ *   undo the "printed once" this whole path exists for.
+ */
+export declare function reportCommandFailure(error: unknown): void;
+/**
+ * `migrate apply` refusing because the database already has the schema.
+ *
+ * `42710` (duplicate_object) and `42P07` (duplicate_table) are what a migration
+ * hits when boot-ensure — or a `db push` — has already provisioned the objects
+ * it was going to create. Since boot-ensure provisions *every* production
+ * database, this is the normal case rather than the exotic one, and the raw
+ * failure (`pq: type "posts_status" already exists (42710)`, then `sql/migrate:
+ * write revision: … current transaction is aborted`) names no way forward.
+ */
+export declare function parseAlreadyProvisioned(text: string): {
+    object: string;
+    code: string;
+} | null;
+/**
+ * What to do about it: tell Atlas the database is already at a version.
+ *
+ * Atlas's own mechanism (`migrate apply --baseline <version>`), not a ledger of
+ * ours — it writes the revision row Atlas reads, so every later `rebase db
+ * migrate` is an ordinary one.
+ */
+export declare function formatBaselineRemedy(version: string | null, object?: string): string;
+/** `ALTER TABLE … SET NOT NULL` on a table that already holds rows (23502). */
+export declare function parseNotNullViolation(text: string): {
+    table: string;
+    column: string;
+} | null;
+/**
+ * The three ways out, because there is no fourth.
+ *
+ * Boot-ensure handles this case — it adds the column nullable and sets NOT NULL
+ * only when the table is empty — so a push that dies here is strictly worse
+ * than the boot that would have run instead, and the developer deserves to be
+ * told which of the three they want rather than left with `pq: … contains null
+ * values (23502)` and no next step.
+ */
+export declare function formatNotNullViolationBanner(violation: {
+    table: string;
+    column: string;
+}, rowCount: number | null): string;
+/** Atlas refusing to remove a label from an enum — a renamed `enum` option id. */
+export declare function parseEnumLabelDrop(text: string): {
+    label: string;
+    enumType: string;
+} | null;
+/**
+ * Why the two paths disagree, and what retiring an option id actually costs.
+ *
+ * Boot-ensure adds enum labels and never removes one, so `rebase dev` accepts
+ * the very edit that stops `db push` dead. PostgreSQL has no `ALTER TYPE …
+ * DROP VALUE`: a label goes only by rewriting the type, which is a data
+ * migration and not a schema push.
+ */
+export declare function formatEnumLabelDropBanner(drop: {
+    label: string;
+    enumType: string;
+}): string;
+/**
+ * The remedy for an Atlas invocation that failed, or `null`.
+ *
+ * Scoped by the invocation, because the same database state means different
+ * things to different subcommands: "already exists" under `migrate apply` wants
+ * a baseline, while under `schema apply` it is a genuine conflict.
+ */
+export declare function diagnoseAtlasFailure(context: {
+    domain: string;
+    args: string[];
+    stderr: string;
+    databaseUrl?: string;
+    /** The newest migration version on disk, named in the baseline remedy. */
+    latestMigrationVersion?: string | null;
+}): Promise<string | null>;

package/dist/cli-flags.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The flags each driver command takes, in one place, and the check that
+ * enforces them.
+ *
+ * Every parser in `cli.ts` runs `arg(..., { permissive: true })`, which does not
+ * mean "be lenient" — it means **an undeclared flag becomes a positional**. So
+ * `rebase db push --alow-destructive` did not fail: the typo landed in `_`, the
+ * push ran with the destructive gate still closed, and the developer read the
+ * refusal as Rebase ignoring the flag they had just typed. `rebase schema
+ * generate --ouput src/schema.ts` was worse — it wrote the default path and
+ * said nothing, so the next build compiled a file nobody had regenerated.
+ *
+ * The check has to live at the entry point rather than in those parsers, and
+ * that is not a detail: `db push` and `db generate` re-enter `schemaCommand`
+ * and `generatePostgresDdlCommand` with the *db* line, so a strict parser
+ * inside either of them would reject `--allow-destructive` on a line where it
+ * is correct. One validation, once, against the spec for the command the user
+ * actually named; the inner parsers keep reading an already-validated line.
+ *
+ * Commands with their own argument handling — `db branch` (`unexpectedBranchArgs`),
+ * `db backup`, `db restore`, `db backups` — are deliberately absent: they own
+ * their spec, and a second list here would be one more thing to keep in step.
+ * An absent entry is "not checked here", never "takes nothing".
+ */
+import arg from "arg";
+/** Keyed by `"<domain> <subcommand>"`, the way the user types it. */
+export declare const DRIVER_FLAG_SPECS: Record<string, arg.Spec>;
+/**
+ * One destination flag, two spellings, everywhere.
+ *
+ * `--out` is the primary on `rebase build`, an alias on `generate-sdk`, `db
+ * backup` and `cloud env pull`, and was refused outright by the three `schema`
+ * commands — so the spelling a user learned on one command was an
+ * "unknown or unexpected option" on the next. Neither name can be retired (both
+ * are shipped), so both are accepted, and {@link assertOutputAliasesPaired}
+ * makes that the rule rather than a habit.
+ */
+export declare const OUTPUT_FLAG_ALIASES: readonly ["--out", "--output"];
+/**
+ * Every spec that names one of the pair names both.
+ *
+ * Exported so the CLI's own specs can be held to it too: the drift this fixes
+ * ran across two packages, and a check that only reads this file would let the
+ * next `--out`-only command through.
+ */
+export declare function assertOutputAliasesPaired(specs: Record<string, arg.Spec>): string[];
+/**
+ * The `--collections` path the user typed, or `null` if they typed none.
+ *
+ * Read once, at the entry point, because every command that takes it re-enters
+ * the generators with the same line and each of them resolved it again — which
+ * is how "Collections path not found" came to be printed four times before the
+ * real output, and how a path that does not exist got as far as *writing* an
+ * empty schema.
+ *
+ * Permissive, and it has to be: {@link assertKnownFlags} has already judged the
+ * line, and `db push` carries flags the `--collections` spec does not name.
+ */
+export declare function collectionsPathIn(args: string[]): string | null;
+/**
+ * The long flags a `--help` usage line documents.
+ *
+ * `"rebase db push [--collections <dir>] [--dry-run] …"` → `["--collections",
+ * "--dry-run"]`. Placeholders (`<dir>`) and the alternation inside a positional
+ * (`<create|list|switch>`) are not flags and are not returned.
+ */
+export declare function flagsInUsage(usage: string): string[];
+/**
+ * Every flag the help documents is accepted, and every flag accepted is documented.
+ *
+ * The drift this catches shipped: `rebase db push --help` has printed
+ * `[--dry-run]` since the flag was written, `DRIVER_FLAG_SPECS["db push"]` never
+ * listed it, and {@link assertKnownFlags} — added later to stop typos being
+ * swallowed — turned the documented flag into `unknown or unexpected option`.
+ * The only way to see a push's SQL was to trip the destructive gate, which is
+ * the exact problem `--dry-run` was written to solve. Worse in a project on an
+ * older driver, whose permissive parser *applied* the schema on that line.
+ *
+ * Two hand-maintained lists in two packages cannot be kept in step by care, so
+ * they are held to each other instead: `usages` is keyed the way
+ * {@link DRIVER_FLAG_SPECS} is (`"db push"`), and comes from the CLI's own help
+ * pages. A key in only one of the two is not this function's business — the
+ * help covers commands that parse their own lines (`db branch`, `db backup`),
+ * and an absent spec entry means "not checked here".
+ *
+ * Aliases (`"-c": "--collections"`, `"--out": "--output"`) need no line of their
+ * own: they are spellings of a documented flag. Neither do {@link RELAYED_FLAGS},
+ * which every driver command accepts because the CLI relays them.
+ */
+export declare function assertSpecMatchesUsage(specs: Record<string, arg.Spec>, usages: Record<string, string>): string[];
+/**
+ * Reject a flag the named command does not take.
+ *
+ * `args` is the driver's whole line — `["db", "push", …]` — so the flags are
+ * read from `args.slice(2)`, past the two command words.
+ *
+ * Throws rather than exiting: `runPluginCommand`'s caller already turns a
+ * thrown error into one red line and exit 1, and a thrown error is what the
+ * tests can see.
+ */
+export declare function assertKnownFlags(domain: string, subcommand: string | undefined, args: string[]): void;

package/dist/cli-helpers.d.ts

@@ -22,22 +22,106 @@ import type { CollectionConfig } from "@rebasepro/types";
  * second, matching the order {@link resolveLocalBin} searches — the driver may
  * be installed a level up from where the command runs.
  */
-export declare function diagnoseMissingBin(packageName: string): "not-installed" | "build-script-blocked";
+export type ProjectPackageManager = "pnpm" | "npm" | "yarn" | "bun" | "unknown";
+/**
+ * Which package manager installed this project, read off its lockfile.
+ *
+ * Every remedy for a blocked build script is package-manager specific, and
+ * naming the wrong one is the same failure as naming none: `pnpm approve-builds`
+ * is not a thing an npm user can run, and `pnpm.onlyBuiltDependencies` is a key
+ * npm does not read. This existed as a pnpm-only message for long enough that
+ * npm 12 — which blocks dependency lifecycle scripts by default, the way pnpm 10
+ * does — could ship and leave every npm reader three unfollowable commands deep.
+ *
+ * The lockfile, not `npm_config_user_agent`: the question is how the project's
+ * `node_modules` was built, not which binary happens to be invoking us. Walks up
+ * because commands run from `backend/` in a scaffolded project, and the lockfile
+ * is at the workspace root.
+ */
+export declare function detectProjectPackageManager(startDir?: string): ProjectPackageManager;
+/**
+ * How to let `@ariga/atlas` run its `preinstall`, in the reader's own package
+ * manager.
+ *
+ * Returns the lines to print after "the binary is missing but the package is
+ * installed". Kept next to {@link detectProjectPackageManager} so the two move
+ * together, and returned rather than printed so it can be asserted on.
+ */
+export declare function describeBuildScriptRemedy(packageName: string, manager?: ProjectPackageManager): string[];
+/**
+ * "Install again, from scratch", in the reader's own package manager.
+ *
+ * For the `bin-link-missing` state: the tree is half-written, and re-resolving
+ * it is what recreates the `.bin` shim. `--force` on pnpm is what makes it
+ * relink rather than decide the tree is already up to date.
+ */
+export declare function describeReinstallCommand(manager?: ProjectPackageManager): string;
+/** `add <pkg>` as a dev dependency, in the reader's own package manager. */
+export declare function describeDevAddCommand(packageName: string, manager?: ProjectPackageManager): string;
+/**
+ * Why a dependency's binary is not on `PATH`.
+ *
+ * `bin-link-missing` is the third state, and the reason this is not a boolean.
+ * The `preinstall` did run and the binary IS on disk — only the
+ * `node_modules/.bin` shim that points at it is absent. pnpm produces exactly
+ * that when it writes the link before the script that creates the target
+ * ("Failed to create bin … ENOENT"), and so does a tree copied without its
+ * symlinks. Telling that reader their build scripts are blocked sends them to
+ * `approve-builds`, which does nothing, because nothing is blocked.
+ */
+export type MissingBinDiagnosis = "not-installed" | "build-script-blocked" | "bin-link-missing";
+/**
+ * The binaries a package's own manifest declares, as absolute paths.
+ *
+ * `bin` is a string for a single binary named after the package, or a map.
+ * Both forms appear in the wild and `@ariga/atlas` uses the map.
+ */
+export declare function declaredBinaries(manifestPath: string): string[];
+export declare function diagnoseMissingBin(packageName: string): MissingBinDiagnosis;
 export declare function resolveLocalBin(binName: string): string | null;
 export declare function getTableIncludesFromCollections(allCollections: CollectionConfig[]): Promise<string[]>;
 export declare function getTableIncludes(collectionsPath: string): Promise<string[]>;
+export declare function loadCollectionsForCli(collectionsPath: string): Promise<CollectionConfig[]>;
+export declare function getDevDatabaseUrl(databaseUrl: string): string;
 /**
- * Load a project's collections the way the Atlas-facing commands need them.
+ * Create the scratch database Atlas plans against, and say so when we cannot.
+ *
+ * Atlas needs a `--dev-url` — an empty database it can build the desired state
+ * in — and this makes `<db>_dev_diff` next to the real one. The whole body used
+ * to be wrapped in an empty catch commented "Ignore, let Atlas handle
+ * connection failures", and Atlas's version of handling it is `postgres:
+ * querying system variables: pq: database "app_dev_diff" does not exist
+ * (3D000)` — the symptom, four frames downstream of the cause, with the cause
+ * thrown away.
  *
- * Deliberately forgiving — a file that fails to import is skipped rather than
- * fatal — because the callers use this to *narrow* what Atlas may touch, and a
- * hard failure here would block a push over an unrelated broken file. Callers
- * that cannot tolerate a partial answer (the table excludes, which fail closed)
- * check the result themselves.
+ * The cause is almost always `42501`: `CREATE DATABASE` is a privilege managed
+ * providers do not grant, so this is the first thing a hosted user hits and the
+ * one they can do least with.
+ *
+ * @returns whether the scratch database was created by *this* call — the only
+ *          case in which dropping it afterwards is ours to do.
  */
-export declare function loadCollectionsForCli(collectionsPath: string): Promise<CollectionConfig[]>;
-export declare function getDevDatabaseUrl(databaseUrl: string): string;
-export declare function ensureDevDatabaseExists(databaseUrl: string, devDatabaseUrl: string): Promise<void>;
+export declare function ensureDevDatabaseExists(databaseUrl: string, devDatabaseUrl: string): Promise<boolean>;
+/**
+ * What went wrong creating the scratch database, and what to do about it.
+ *
+ * Exported for its test: the `42501` branch is the one that matters and it
+ * cannot be provoked without a non-superuser role.
+ */
+export declare function describeDevDatabaseFailure(err: unknown, devDbName: string): string;
+/**
+ * Drop the scratch database again, after the command that needed it succeeded.
+ *
+ * It is a full copy of the schema — no rows, but every table, type and index —
+ * and it was left behind per target forever. The only notice anyone got was
+ * `rebase db branch prune` reporting "3 Atlas scratch database(s) left over
+ * from db push", and on a provider that bills per database it is a silent cost.
+ *
+ * Deliberately NOT called on the failure path: after a failed push the scratch
+ * database holds the state Atlas was planning against, which is the one thing
+ * worth inspecting.
+ */
+export declare function dropDevDatabase(databaseUrl: string, devDatabaseUrl: string): Promise<void>;
 /**
  * The generated SQL for the project's `search` blocks, if it has any.
  *