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

package/dist/cli-helpers.d.ts

@@ -84,6 +84,45 @@ 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[]>;
+type PgClient = import("pg").Client;
+/**
+ * Run one step on this process's connection to the app database.
+ *
+ * Every step leaves the session as it found it, which is what a connection of
+ * its own used to guarantee by being closed. None of them sets anything for
+ * the session — `SET LOCAL` inside their own transaction, or `RESET` — and one
+ * that fails part-way through a transaction it opened is rolled back here, so
+ * the next step does not meet `current transaction is aborted`.
+ *
+ * @param options.connectionTimeoutMillis applies only when this call is the one
+ *        that connects.
+ */
+export declare function withAppClient<T>(databaseUrl: string, step: (client: PgClient) => Promise<T>, options?: {
+    connectionTimeoutMillis?: number;
+}): Promise<T>;
+/** Close every connection {@link withAppClient} opened. Called once, as the command ends. */
+export declare function closeAppClients(): Promise<void>;
+/**
+ * Names the empty database Atlas plans against, instead of `<db>_dev_diff`.
+ *
+ * The derived one is made with `CREATE DATABASE` beside the real database,
+ * which assumes a server that holds more than one. PGlite — the managed
+ * development database — serves exactly one: the CREATE succeeds and creates
+ * nothing, so Atlas connected straight back to the database it was comparing
+ * and refused it as "not clean". `rebase db push` on the managed database now
+ * starts a second, throwaway PGlite and names it here. Anyone can name their
+ * own the same way; a named database is neither created nor dropped.
+ */
+export declare const ATLAS_DEV_URL_ENV = "REBASE_ATLAS_DEV_URL";
+/**
+ * The database Atlas replays the desired schema into: the one
+ * {@link ATLAS_DEV_URL_ENV} names (`named: true` — not ours to create or
+ * drop), else `<db>_dev_diff`.
+ */
+export declare function atlasDevDatabaseUrl(databaseUrl: string, env: Readonly<Record<string, string | undefined>>): {
+    url: string;
+    named: boolean;
+};
 export declare function getDevDatabaseUrl(databaseUrl: string): string;
 /**
  * Create the scratch database Atlas plans against, and say so when we cannot.
@@ -127,10 +166,10 @@ export declare function dropDevDatabase(databaseUrl: string, devDatabaseUrl: str
 /**
  * The generated SQL for the project's `search` blocks, if it has any.
  *
- * @param drizzleDir directory holding the generated SQL. Defaults to `drizzle`
- *        under the working directory.
+ * @param sqlDir directory holding the generated SQL. Defaults to
+ *        `.rebase/sql` under the working directory.
  */
-export declare function readSearchDdl(drizzleDir?: string): string;
+export declare function readSearchDdl(sqlDir?: string): string;
 /**
  * Bring the search column, its index and their helpers up to date.
  *
@@ -144,7 +183,7 @@ export declare function readSearchDdl(drizzleDir?: string): string;
  * silently pushing a schema whose search column never appeared is how a
  * collection ends up with search configured, no error anywhere, and no results.
  */
-export declare function applySearchDdl(databaseUrl: string, drizzleDir?: string): Promise<void>;
+export declare function applySearchDdl(databaseUrl: string, sqlDir?: string): Promise<void>;
 /**
  * Glob patterns keeping Atlas away from the search objects.
  *
@@ -181,10 +220,10 @@ export declare function dropGeneratedColumns(databaseUrl: string, statements: st
 /**
  * The generated SQL for the project's `vector` properties, if it has any.
  *
- * @param drizzleDir directory holding the generated SQL. Defaults to `drizzle`
- *        under the working directory.
+ * @param sqlDir directory holding the generated SQL. Defaults to
+ *        `.rebase/sql` under the working directory.
  */
-export declare function readVectorDdl(drizzleDir?: string): string;
+export declare function readVectorDdl(sqlDir?: string): string;
 /**
  * Install pgvector and bring the vector columns and their ANN indexes up to
  * date.
@@ -200,7 +239,7 @@ export declare function readVectorDdl(drizzleDir?: string): string;
  * appeared is how a project ends up with vector search configured, no error
  * anywhere, and no results.
  */
-export declare function applyVectorDdl(databaseUrl: string, drizzleDir?: string): Promise<void>;
+export declare function applyVectorDdl(databaseUrl: string, sqlDir?: string): Promise<void>;
 /**
  * Glob patterns keeping Atlas away from the vector objects.
  *
@@ -212,10 +251,10 @@ export declare function getVectorExcludes(collectionsPath: string): Promise<stri
  * The generated SQL for the project's `autoValue: "on_update"` properties, if
  * it has any.
  *
- * @param drizzleDir directory holding the generated SQL. Defaults to `drizzle`
- *        under the working directory.
+ * @param sqlDir directory holding the generated SQL. Defaults to
+ *        `.rebase/sql` under the working directory.
  */
-export declare function readTriggersDdl(drizzleDir?: string): string;
+export declare function readTriggersDdl(sqlDir?: string): string;
 /**
  * Install the `updated_at` trigger function and bind it to every column that
  * asked for one.
@@ -230,7 +269,7 @@ export declare function readTriggersDdl(drizzleDir?: string): string;
  * appeared is how `updated_at` ends up silently stale for every writer that is
  * not the driver, which is the whole reason the trigger exists.
  */
-export declare function applyTriggersDdl(databaseUrl: string, drizzleDir?: string): Promise<void>;
+export declare function applyTriggersDdl(databaseUrl: string, sqlDir?: string): Promise<void>;
 /** @see getSearchExcludes */
 export declare function getTriggerExcludes(collectionsPath: string): Promise<string[]>;
 /**
@@ -322,3 +361,4 @@ export declare function getTableExcludes(databaseUrl: string, collectionsPath: s
  * `import.meta` and cannot be imported by the jest runner.
  */
 export declare function promptConfirm(question: string): Promise<boolean>;
+export {};

package/dist/cli-output.d.ts

@@ -1,34 +1,22 @@
-/**
- * Terminal output for the `rebase db|schema|doctor` commands.
- *
- * These commands used to write every line through `logger`, and that is a
- * category error with three separate consequences:
- *
- *  - `logger` prefixes each line with its own level, so a box-drawn report
- *    arrived as `ℹ️ [INFO]   ┌─ ✗ Missing Column ───` and the frame no longer
- *    lined up with anything;
- *  - `logger` is gated by `LOG_LEVEL`, which ships in the scaffold's own
- *    `.env.example` — a developer who quietened their dev server with
- *    `LOG_LEVEL=warn` got a `rebase db push` that printed almost nothing and
- *    still exited non-zero, indistinguishable from a crash;
- *  - under `NODE_ENV=production` `logger` emits JSON, so the whole report
- *    became log records with the chalk escape codes embedded in them.
- *
- * A CLI's report *is* its return value. It goes to the terminal unconditionally
- * and unadorned. `packages/cli` has always written its output this way; this is
- * the same three functions for the plugin CLI that `rebase` delegates to.
- *
- * `logger` still belongs in this package's *runtime* — a request handler has no
- * terminal and its lines want levels, timestamps and redaction. The rule is the
- * caller, not the severity: anything a developer reads because they typed a
- * command goes here, anything a server emits while running goes to `logger`.
- *
- * Errors and warnings go to stderr so `rebase db push > plan.txt` keeps the
- * diagnosis on the terminal where it is readable.
- */
 /** One line of human-facing output on stdout. */
 export declare const out: (line?: string) => void;
 /** One line of human-facing warning output on stderr. */
 export declare const outWarn: (line?: string) => void;
 /** One line of human-facing error output on stderr. */
 export declare const outError: (line?: string) => void;
+/**
+ * Whether a failure should be printed with its stack — `rebase --debug`, which
+ * the launcher passes down as `REBASE_DEBUG`, or `REBASE_DEBUG` set by hand.
+ */
+export declare const wantsStack: () => boolean;
+/**
+ * An error as a person reads it: its message, and its stack only under
+ * `--debug`.
+ *
+ * The rule `rebase` itself follows (`bin/rebase.js`). These commands run in a
+ * child process the launcher's handler never sees, so a syntax error in a
+ * collection file reached the terminal as `Doctor failed CollectionConfigError:`
+ * followed by twenty frames of loader internals, under a sentence that already
+ * said which file and which line.
+ */
+export declare const describeFailure: (error: unknown) => string;

package/dist/cli-push.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The steps `rebase db push` takes once the dry-run has been read and gated.
+ *
+ * Callbacks rather than calls, so the order is testable without a database or
+ * an Atlas binary: `cli.ts` itself cannot be loaded by the jest suite.
+ */
+export interface PushApplySteps {
+    /** Drop the generated columns that read a column the plan retypes. */
+    dropRebuildable: () => Promise<void>;
+    /** `atlas schema apply --auto-approve`: Atlas plans again, then applies. */
+    atlasApply: () => Promise<void>;
+    /** Say what the skipped apply would have printed. */
+    reportSynced: () => void;
+    /** Put those generated columns back after a failed apply. */
+    rebuildAfterFailure: () => Promise<void>;
+    /**
+     * Everything Atlas cannot see: RLS locks, auth tables, vector, search,
+     * triggers, policies, the user role. Runs whether or not Atlas had work.
+     */
+    afterApply: () => Promise<void>;
+}
+/**
+ * Apply a planned push.
+ *
+ * A dry-run that answered "Schema is synced" skips the second Atlas run: that
+ * run would plan the same diff again (≈0.9 s at 111 tables, 5.5 s at 411 —
+ * Atlas's cost grows faster than the table count) and then apply nothing. The
+ * steps after it still run, because Atlas cannot see what they own. A plan with
+ * anything in it keeps the old flow, including Atlas re-planning at apply time.
+ *
+ * @returns `"synced"` when Atlas was not run again, `"applied"` otherwise.
+ */
+export declare function applyPushPlan(plan: {
+    dryRun: string;
+    rebuildable: number;
+}, steps: PushApplySteps): Promise<"applied" | "synced">;
+/** The one call {@link applyPoliciesFile} needs from a connection. */
+export interface PolicyConnection {
+    query(text: string): Promise<unknown>;
+}
+/** What {@link applyPoliciesFile} stamps, and how to read the definitions back. */
+export interface PolicyStamping {
+    /**
+     * `policyStampSql` of every table whose policies `policies.sql` creates
+     * exactly as the boot would — see {@link stampableTables}.
+     */
+    statements: string[];
+    /**
+     * The `search_path` a boot reads policies under, when the connection's own
+     * differs. A stamp hashes `pg_get_expr`, which spells a function on the
+     * path unqualified: read under `"$user", public` with a `rebase` role, the
+     * boot's `rebase.uid()` prints as `uid()` and no stamp would ever match.
+     */
+    searchPath?: string;
+}
+/**
+ * The tables whose stamp `db push` may write: those every one of whose planned
+ * statements `policies.sql` carries, verbatim.
+ *
+ * A stamp says "this stored definition is what the plan's statement made". It
+ * is only true of a policy the statement *did* make — and since both are
+ * rendered by the same function from the same collections, a table whose
+ * statements are all in the file is one whose policies the file just created.
+ * Anything else (a hand-edited file, a file generated elsewhere) is not
+ * stamped, and the next boot re-applies that table, as before.
+ */
+export declare function stampableTables<T extends {
+    policyStatements: string[];
+}>(plans: readonly T[], policiesSql: string): T[];
+/**
+ * Run `policies.sql`, then stamp the policies it created the way a boot does,
+ * in the same transaction.
+ *
+ * Before stamps the push's policies carried none, so the first boot after
+ * every push re-applied them all — a DROP and a CREATE per policy, an ACCESS
+ * EXCLUSIVE lock per table. Stamped here, that boot finds them current.
+ *
+ * The file runs in one transaction, as it did as one implicit one: a policy
+ * that fails leaves the previous ones in place. The stamps run after it, under
+ * a savepoint: a stamp that cannot be written costs the next boot a re-apply,
+ * which is what it did before, so it is reported and the policies are kept.
+ * Nothing is left set on the connection: `SET LOCAL` ends with the transaction.
+ */
+export declare function applyPoliciesFile(client: PolicyConnection, policiesSql: string, stamping: PolicyStamping): Promise<{
+    stamped: number;
+    stampError?: string;
+}>;