@rebasepro/server-postgres 0.25.0-canary.ge06257e → 0.25.1

package/dist/backup/backup-service.d.ts

@@ -17,6 +17,24 @@ export { resolvePgBinary };
 export declare function detectToolMajor(bin: string): Promise<number | null>;
 /** Query the server for its major version via `server_version_num`. */
 export declare function getServerVersionMajor(connectionString: string): Promise<number | null>;
+/**
+ * Put back what a client tool left set on a database that is one session
+ * every connection shares, and do nothing on any other.
+ *
+ * The managed development database is PGlite: one session behind a socket
+ * server, so what `pg_dump` sets for itself — `search_path` emptied,
+ * `row_security` off, `PREPARE dumpEnumType …` — stays set for every client
+ * after it, a running `rebase dev` included. One `rebase db backup` there left
+ * every API request answering 500 "table does not exist", a restart did not
+ * help (the database outlives `rebase dev`), and the next backup failed on
+ * `prepared statement "dumpenumtype" already exists`.
+ *
+ * `RESET ALL` and `DEALLOCATE ALL`, not `DISCARD ALL`: that would also drop
+ * the `LISTEN` a running `rebase dev`'s realtime holds on the same session.
+ * Best effort: it runs after the tool, whose own outcome is what the caller
+ * reports.
+ */
+export declare function resetSharedSession(connectionString: string): Promise<void>;
 export interface PreflightResult extends VersionCompatibility {
     bin: string;
     toolMajor: number | null;
@@ -114,8 +132,69 @@ export declare function restoreDump(opts: {
     inheritStdio?: boolean;
     env?: Record<string, string | undefined>;
 }): Promise<void>;
+/**
+ * A `restore --clean` that stopped, and so was rolled back whole.
+ *
+ * `tool` is the one that stopped it: `pg_restore`, writing the dump's script,
+ * or `psql`, running it. `lockTimeout` when what `psql` stopped on was the
+ * wait for a lock — `CLEAN_LOCK_TIMEOUT` in `pg-tools.ts`.
+ */
+export declare class CleanRestoreFailed extends Error {
+    readonly tool: "pg_restore" | "psql";
+    readonly exitCode: number | undefined;
+    readonly lockTimeout: boolean;
+    constructor(tool: "pg_restore" | "psql", exitCode: number | undefined, lockTimeout: boolean);
+}
+/**
+ * Restore a dump over what the database holds, as one transaction:
+ * {@link cleanRestorePrelude} first, then the dump as `pg_restore` writes it
+ * for `psql`, and the `COMMIT` only after the last of it.
+ *
+ * One unit, so it either replaces what the dump holds or changes nothing:
+ * `pg_restore --clean` runs each statement on its own, so the drops it starts
+ * with had all happened when a later one failed — and its plain `DROP SCHEMA
+ * rebase` fails on any table the backup lacks, which left a database with
+ * every table dropped and nothing restored. Here a failure anywhere —
+ * `pg_restore` cannot read the archive, a statement fails, the connection
+ * drops — ends the transaction without a `COMMIT`, and Postgres rolls it back.
+ *
+ * Throws {@link CleanRestoreFailed} when it did not commit.
+ */
+export declare function restoreDumpReplacing(opts: {
+    connectionString: string;
+    inputFile: string;
+    objects: DumpObjects;
+    noOwner?: boolean;
+    inheritStdio?: boolean;
+    env?: Record<string, string | undefined>;
+}): Promise<void>;
+/**
+ * What `restore --clean` drops that the backup does not hold, so it can say
+ * so before it runs: what a schema the backup replaces whole holds that it has
+ * no copy of — tables, views, sequences, functions, procedures, aggregates,
+ * types and domains — and the views and foreign keys elsewhere that reference
+ * one of the relations it replaces. As `<kind> <name>`.
+ *
+ * A function is matched by its name, so an overload the backup lacks beside
+ * one it holds is not named. Sequences a column owns go with their table,
+ * and what an extension owns with the extension, so neither is named.
+ *
+ * None for a database that does not exist yet.
+ */
+export declare function findCleanExtras(connectionString: string, objects: DumpObjects): Promise<string[]>;
 /** The schemas and tables a dump creates, from `pg_restore --list`. See {@link parseDumpObjects}. */
 export declare function readDumpObjects(inputFile: string, env?: Record<string, string | undefined>): Promise<DumpObjects>;
+/**
+ * What `db restore` says of a file whose table of contents pg_restore cannot
+ * read: before anything is restored, so nothing has changed.
+ *
+ * `pgRestoreStderr` is what `pg_restore --list` printed. Its first error line
+ * is quoted, so the reader sees the tool's own words too.
+ */
+export declare function describeUnreadableDump(file: string, pgRestoreStderr: string): {
+    message: string;
+    hint: string;
+};
 /**
  * Which of a dump's schemas and tables the target database already holds,
  * as `schema <name>` / `table <schema>.<name>`: what a restore without

package/dist/backup/pg-binary.d.ts

@@ -1,5 +1,5 @@
-export type PgTool = "pg_dump" | "pg_restore" | "pg_dumpall";
+export type PgTool = "pg_dump" | "pg_restore" | "pg_dumpall" | "psql";
 /** The variable that points at `tool` when it is not on the PATH. */
 export declare function pgToolVariable(tool: PgTool): string;
-/** Locate `pg_dump` / `pg_restore` / `pg_dumpall`, honouring an env override. */
+/** Locate `pg_dump` / `pg_restore` / `pg_dumpall` / `psql`, honouring an env override. */
 export declare function resolvePgBinary(tool: PgTool, env?: Record<string, string | undefined>): string | null;

package/dist/backup/pg-tools.d.ts

@@ -168,6 +168,25 @@ export interface DumpObjects {
         schema: string;
         table: string;
     }[];
+    /**
+     * Every relation it creates — tables, views, materialized views, foreign
+     * tables and sequences — by schema and name: what `restore --clean` can
+     * tell apart from what the target holds besides.
+     */
+    relations: {
+        schema: string;
+        name: string;
+    }[];
+    /** Every function, procedure and aggregate it creates, by schema and name: an overloaded name once for each. */
+    routines: {
+        schema: string;
+        name: string;
+    }[];
+    /** Every type it creates — enum, composite, range — and every domain, by schema and name. */
+    types: {
+        schema: string;
+        name: string;
+    }[];
 }
 /**
  * The schemas and tables in `pg_restore --list` output: the objects a
@@ -176,9 +195,49 @@ export interface DumpObjects {
  * A TOC line ends in the object's owner, after its namespace and its name;
  * a schema's namespace is `-`. The name is what lies between the two, so a
  * name with a space in it (`Odd Name`) reads whole. `TABLE DATA` and every
- * other kind of entry are not objects of their own here.
+ * other kind of entry are not objects of their own here. Its relations,
+ * functions and types are read too, for what `restore --clean` would drop
+ * that the dump does not hold (`findCleanExtras`).
  */
 export declare function parseDumpObjects(list: string): DumpObjects;
+/**
+ * How long `restore --clean` waits for a lock before it gives up.
+ *
+ * A `rebase dev` serving from the database holds connections, and one inside a
+ * transaction would otherwise make the restore wait without a word. The dump's
+ * own script sets `lock_timeout = 0` after this, for the objects it creates.
+ */
+export declare const CLEAN_LOCK_TIMEOUT = "15s";
+/**
+ * What `restore --clean` runs first, in the transaction the restore runs in:
+ * every schema the dump creates, dropped with `CASCADE`, and every table it
+ * creates in a schema it does not (`public`), the same.
+ *
+ * `CASCADE`, which `pg_restore --clean` never uses: a table the backup lacks
+ * in one of its schemas — `rebase.atlas_schema_revisions` from `rebase db
+ * migrate`, a table a newer runtime added — is exactly what stopped its plain
+ * `DROP SCHEMA rebase`, and a table that references one of the backup's is what
+ * stops a plain `DROP TABLE`. The dump's script follows, with its own `DROP …
+ * IF EXISTS` for everything else it creates.
+ */
+export declare function cleanRestorePrelude(objects: DumpObjects): string[];
+/**
+ * `pg_restore` writing the dump as a SQL script on stdout, with the `DROP …
+ * IF EXISTS` that `--clean` adds, for `psql` to run. See {@link buildPsqlScriptArgs}.
+ */
+export declare function buildPgRestoreScriptArgs(opts: {
+    inputFile: string;
+    noOwner?: boolean;
+}): string[];
+/**
+ * `psql` running a script read from stdin, stopping at its first error.
+ *
+ * `-X`, so no `.psqlrc` changes what runs; `-q`, so it prints errors and
+ * warnings, not a command tag per statement. The transaction is the script's
+ * own: `restore --clean` writes the `BEGIN`, and the `COMMIT` only once
+ * `pg_restore` has written the whole dump.
+ */
+export declare function buildPsqlScriptArgs(connectionString: string): string[];
 /**
  * Assemble the `pg_dumpall --globals-only` argument vector. Roles (and other
  * cluster-wide objects) live outside any single database, so a per-database