@rebasepro/server-postgres 0.9.1-canary.ff338b5 → 0.10.1-canary.14e53ae

package/README.md

@@ -76,6 +76,27 @@ process.on("SIGTERM", async () => {
 | `statementTimeout` | 30,000 |
 | `keepAlive` | true |
 
+## Testing
+
+This package runs **two test runners**, split by directory. This is deliberate — check which half you are in before running anything.
+
+| Tests | Runner | Config | Command |
+|-------|--------|--------|---------|
+| `test/*.ts` (unit) | jest | [`jest.config.cjs`](./jest.config.cjs) | `pnpm test` |
+| `test/e2e/**` (integration) | vitest | [`vitest.e2e.config.ts`](./vitest.e2e.config.ts) | `pnpm test:e2e` |
+
+The unit tests use jest's injected globals (`describe`/`it`/`expect`) and `jest.mock`. The e2e tests import explicitly from `vitest` and need Docker (testcontainers spins up a real Postgres).
+
+**Running a single unit test:**
+
+```bash
+npx jest test/auth-services.test.ts
+```
+
+Pointing `vitest` at a unit test is the easy mistake here — it produces a bare `ReferenceError: jest is not defined` and a "no tests" result, which looks exactly like a dead or broken test file rather than the wrong runner. [`vitest.config.ts`](./vitest.config.ts) exists solely to intercept that and print the command you actually wanted.
+
+`pnpm test` runs jest **without** `--passWithNoTests`: if the unit suite ever stops being collected, CI fails instead of going quietly green.
+
 ## Related Packages
 
 | Package | Role |

package/dist/PostgresBackendDriver.d.ts

@@ -114,6 +114,24 @@ export declare class PostgresBackendDriver implements DataDriver {
     }): Promise<Record<string, unknown>[]>;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
+    /**
+     * Application-level roles actually in use in this project.
+     *
+     * Distinct from {@link fetchAvailableRoles}, which returns native
+     * PostgreSQL roles from `pg_roles` (`postgres`, `rebase_user`, …). Those
+     * are the roles the SQL editor can `SET ROLE` to. *These* are the strings
+     * held in the users table's `roles` column, injected per-transaction as
+     * `auth.roles()` and matched by `SecurityRule.roles`. Feeding the pg roles
+     * into a `SecurityRule.roles` field produces a condition no user can ever
+     * satisfy, so the two must not be conflated.
+     *
+     * Roles have no registry table — they were migrated out of
+     * `rebase.user_roles` onto an inline `roles TEXT[]` column — so the live
+     * set is derived from what is assigned. A role that is declared in a policy
+     * but held by nobody yet cannot be discovered here; callers that need it
+     * should union in the roles they already know about.
+     */
+    fetchApplicationRoles(): Promise<string[]>;
     fetchCurrentDatabase(): Promise<string | undefined>;
     /**
      * Fetch public tables that are not yet mapped to a collection.

package/dist/PostgresBootstrapper.d.ts

@@ -4,7 +4,7 @@
  * Implements the `BackendBootstrapper` interface for PostgreSQL.
  */
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { BackendBootstrapper } from "@rebasepro/types";
+import { BackendBootstrapper, type RealtimeChannelsConfig } from "@rebasepro/types";
 import { PostgresBackendDriver } from "./PostgresBackendDriver";
 import { RealtimeService } from "./services/realtimeService";
 import { DatabasePoolManager } from "./databasePoolManager";
@@ -25,6 +25,16 @@ export interface PostgresDriverConfig {
      * (BaaS mode). Defaults to `public`.
      */
     introspectionSchema?: string;
+    /**
+     * Realtime options, both opt-in:
+     *
+     *  - `channels` — retention. Without rules no channel keeps any history and
+     *    broadcast stays fire-and-forget. See {@link ChannelRetentionRule}.
+     *  - `bus` — the cross-instance transport for channel broadcast and
+     *    presence. Defaults to in-process only, which is correct for a single
+     *    instance and wrong for two. See {@link ChannelBusConfig}.
+     */
+    realtime?: RealtimeChannelsConfig;
 }
 /**
  * Opaque internals bag that PostgresBootstrapper stores during `initializeDriver()`

package/dist/auth/services.d.ts

@@ -1,6 +1,6 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { RebasePgTable } from "../types";
-import { UserRepository, TokenRepository, MfaRepository, AuthRepository, UserData, CreateUserData, RoleData, CreateRoleData, RefreshTokenInfo, PasswordResetTokenInfo, MagicLinkTokenInfo, UserIdentityData, ListUsersOptions, PaginatedUsersResult, MfaFactor, MfaChallengeInfo, RoleData as Role } from "@rebasepro/server";
+import { UserRepository, TokenRepository, MfaRepository, AuthRepository, UserData, CreateUserData, RoleData, CreateRoleData, RefreshTokenInfo, RefreshTokenSession, PasswordResetTokenInfo, MagicLinkTokenInfo, UserIdentityData, ListUsersOptions, PaginatedUsersResult, MfaFactor, MfaChallengeInfo, RoleData as Role } from "@rebasepro/server";
 export type { Role };
 export interface AuthSchemaTables {
     users: RebasePgTable;
@@ -23,7 +23,7 @@ export declare class UserService implements UserRepository {
      * Run a privileged auth write with an explicitly cleared RLS context.
      *
      * The auth services run on the base/owner connection, which by design
-     * carries a NULL `app.user_id` so the `auth.uid() IS NULL` server-escape
+     * carries a NULL `app.uid` so the `auth.uid() IS NULL` server-escape
      * in the default policies applies. That NULL is normally guaranteed by
      * `set_config(..., is_local = true)` resetting at transaction end — but a
      * GUC that survives on a pooled connection (or a connection role that
@@ -41,8 +41,8 @@ export declare class UserService implements UserRepository {
     getUserById(id: string): Promise<UserData | null>;
     getUserByEmail(email: string): Promise<UserData | null>;
     getUserByIdentity(provider: string, providerId: string): Promise<UserData | null>;
-    getUserIdentities(userId: string): Promise<UserIdentityData[]>;
-    linkUserIdentity(userId: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
+    getUserIdentities(uid: string): Promise<UserIdentityData[]>;
+    linkUserIdentity(uid: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
     updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
     deleteUser(id: string): Promise<void>;
     listUsers(): Promise<UserData[]>;
@@ -66,23 +66,23 @@ export declare class UserService implements UserRepository {
     /**
      * Get roles for a user from database (inline TEXT[] column)
      */
-    getUserRoles(userId: string): Promise<Role[]>;
+    getUserRoles(uid: string): Promise<Role[]>;
     /**
      * Get role IDs for a user
      */
-    getUserRoleIds(userId: string): Promise<string[]>;
+    getUserRoleIds(uid: string): Promise<string[]>;
     /**
      * Set roles for a user (replaces existing roles)
      */
-    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+    setUserRoles(uid: string, roleIds: string[]): Promise<void>;
     /**
      * Assign a specific role to new user (appends if not present)
      */
-    assignDefaultRole(userId: string, roleId: string): Promise<void>;
+    assignDefaultRole(uid: string, roleId: string): Promise<void>;
     /**
      * Get user with their roles
      */
-    getUserWithRoles(userId: string): Promise<{
+    getUserWithRoles(uid: string): Promise<{
         user: UserData;
         roles: Role[];
     } | null>;
@@ -90,13 +90,42 @@ export declare class UserService implements UserRepository {
 export declare class RefreshTokenService {
     private db;
     private refreshTokensTable;
+    private usersTable;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
-    createToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    /**
+     * Whether the table actually carries a column, so a host application that
+     * supplied its own `refresh_tokens` table — one that predates session
+     * grouping — degrades instead of throwing on every sign-in.
+     */
+    private has;
+    private col;
+    /** The columns to read back, narrowed to the ones this table has. */
+    private selection;
+    createToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
     findByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
+    /**
+     * Record that a token was rotated away, keeping the row.
+     *
+     * The row is what lets `/auth/refresh` distinguish "you already used this,
+     * here is a fresh one" from "no idea what this is". Deleting it — which is
+     * what this used to do — collapsed both into a 401 and signed the user out
+     * for the crime of losing a response.
+     */
+    markRotated(tokenHash: string): Promise<void>;
+    /** Final kill of one sign-in: logout, or revoking a device remotely. */
+    revokeSession(sessionId: string): Promise<void>;
+    /**
+     * Housekeeping: rotation would otherwise leave a row per refresh forever.
+     * Superseded rows are only needed for as long as a straggler might still
+     * present them, and expired ones are dead weight everywhere.
+     */
+    prune(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
+    getTokensValidAfter(uid: string): Promise<Date | null>;
+    setTokensValidAfter(uid: string, at: Date): Promise<void>;
     deleteByHash(tokenHash: string): Promise<void>;
-    deleteAllForUser(userId: string): Promise<void>;
-    listForUser(userId: string): Promise<RefreshTokenInfo[]>;
-    deleteById(id: string, userId: string): Promise<void>;
+    deleteAllForUser(uid: string): Promise<void>;
+    listForUser(uid: string): Promise<RefreshTokenInfo[]>;
+    deleteById(id: string, uid: string): Promise<void>;
 }
 /**
  * Password reset token service
@@ -109,12 +138,12 @@ export declare class PasswordResetTokenService {
     /**
      * Create a password reset token
      */
-    createToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     /**
      * Find a valid (not expired, not used) token by hash
      */
     findValidByHash(tokenHash: string): Promise<{
-        userId: string;
+        uid: string;
         expiresAt: Date;
     } | null>;
     /**
@@ -124,7 +153,7 @@ export declare class PasswordResetTokenService {
     /**
      * Delete all tokens for a user
      */
-    deleteAllForUser(userId: string): Promise<void>;
+    deleteAllForUser(uid: string): Promise<void>;
     /**
      * Clean up expired tokens
      */
@@ -139,7 +168,7 @@ export declare class MagicLinkTokenService {
     private magicLinkTokensTable;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedTableName;
-    createToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidByHash(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
     markAsUsed(tokenHash: string): Promise<void>;
 }
@@ -153,18 +182,23 @@ export declare class PostgresTokenRepository implements TokenRepository {
     private passwordResetTokenService;
     private magicLinkTokenService;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
-    createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
+    markRefreshTokenRotated(tokenHash: string): Promise<void>;
+    revokeRefreshTokenSession(sessionId: string): Promise<void>;
+    pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
+    getTokensValidAfter(uid: string): Promise<Date | null>;
+    setTokensValidAfter(uid: string, at: Date): Promise<void>;
     findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
     deleteRefreshToken(tokenHash: string): Promise<void>;
-    deleteAllRefreshTokensForUser(userId: string): Promise<void>;
-    listRefreshTokensForUser(userId: string): Promise<RefreshTokenInfo[]>;
-    deleteRefreshTokenById(id: string, userId: string): Promise<void>;
-    createPasswordResetToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    deleteAllRefreshTokensForUser(uid: string): Promise<void>;
+    listRefreshTokensForUser(uid: string): Promise<RefreshTokenInfo[]>;
+    deleteRefreshTokenById(id: string, uid: string): Promise<void>;
+    createPasswordResetToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
     markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
-    deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
+    deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
     deleteExpiredTokens(): Promise<void>;
-    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createMagicLinkToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
     markMagicLinkTokenUsed(tokenHash: string): Promise<void>;
 }
@@ -182,8 +216,8 @@ export declare class PostgresAuthRepository implements AuthRepository {
     getUserById(id: string): Promise<UserData | null>;
     getUserByEmail(email: string): Promise<UserData | null>;
     getUserByIdentity(provider: string, providerId: string): Promise<UserData | null>;
-    getUserIdentities(userId: string): Promise<UserIdentityData[]>;
-    linkUserIdentity(userId: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
+    getUserIdentities(uid: string): Promise<UserIdentityData[]>;
+    linkUserIdentity(uid: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
     updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
     deleteUser(id: string): Promise<void>;
     listUsers(): Promise<UserData[]>;
@@ -192,11 +226,11 @@ export declare class PostgresAuthRepository implements AuthRepository {
     setEmailVerified(id: string, verified: boolean): Promise<void>;
     setVerificationToken(id: string, token: string | null): Promise<void>;
     getUserByVerificationToken(token: string): Promise<UserData | null>;
-    getUserRoles(userId: string): Promise<RoleData[]>;
-    getUserRoleIds(userId: string): Promise<string[]>;
-    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
-    assignDefaultRole(userId: string, roleId: string): Promise<void>;
-    getUserWithRoles(userId: string): Promise<{
+    getUserRoles(uid: string): Promise<RoleData[]>;
+    getUserRoleIds(uid: string): Promise<string[]>;
+    setUserRoles(uid: string, roleIds: string[]): Promise<void>;
+    assignDefaultRole(uid: string, roleId: string): Promise<void>;
+    getUserWithRoles(uid: string): Promise<{
         user: UserData;
         roles: RoleData[];
     } | null>;
@@ -205,37 +239,42 @@ export declare class PostgresAuthRepository implements AuthRepository {
     createRole(_data: CreateRoleData): Promise<RoleData>;
     updateRole(id: string, data: Partial<Omit<RoleData, "id">>): Promise<RoleData | null>;
     deleteRole(_id: string): Promise<void>;
-    createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
+    markRefreshTokenRotated(tokenHash: string): Promise<void>;
+    revokeRefreshTokenSession(sessionId: string): Promise<void>;
+    pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
+    getTokensValidAfter(uid: string): Promise<Date | null>;
+    setTokensValidAfter(uid: string, at: Date): Promise<void>;
     findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
     deleteRefreshToken(tokenHash: string): Promise<void>;
-    deleteAllRefreshTokensForUser(userId: string): Promise<void>;
-    listRefreshTokensForUser(userId: string): Promise<RefreshTokenInfo[]>;
-    deleteRefreshTokenById(id: string, userId: string): Promise<void>;
-    createPasswordResetToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    deleteAllRefreshTokensForUser(uid: string): Promise<void>;
+    listRefreshTokensForUser(uid: string): Promise<RefreshTokenInfo[]>;
+    deleteRefreshTokenById(id: string, uid: string): Promise<void>;
+    createPasswordResetToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
     markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
-    deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
+    deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
     deleteExpiredTokens(): Promise<void>;
-    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createMagicLinkToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
     markMagicLinkTokenUsed(tokenHash: string): Promise<void>;
     private _mfaService;
     private getMfaService;
-    createMfaFactor(userId: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
-    getMfaFactors(userId: string): Promise<MfaFactor[]>;
+    createMfaFactor(uid: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    getMfaFactors(uid: string): Promise<MfaFactor[]>;
     getMfaFactorById(factorId: string): Promise<(MfaFactor & {
         secretEncrypted: string;
     }) | null>;
     verifyMfaFactor(factorId: string): Promise<void>;
-    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    deleteMfaFactor(factorId: string, uid: string): Promise<void>;
     createMfaChallenge(factorId: string, ipAddress?: string): Promise<MfaChallengeInfo>;
     getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null>;
     verifyMfaChallenge(challengeId: string): Promise<void>;
-    createRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
-    useRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
-    getUnusedRecoveryCodeCount(userId: string): Promise<number>;
-    deleteAllRecoveryCodes(userId: string): Promise<void>;
-    hasVerifiedMfaFactors(userId: string): Promise<boolean>;
+    createRecoveryCodes(uid: string, codeHashes: string[]): Promise<void>;
+    useRecoveryCode(uid: string, codeHash: string): Promise<boolean>;
+    getUnusedRecoveryCodeCount(uid: string): Promise<number>;
+    deleteAllRecoveryCodes(uid: string): Promise<void>;
+    hasVerifiedMfaFactors(uid: string): Promise<boolean>;
 }
 /**
  * PostgreSQL implementation of MfaRepository.
@@ -246,21 +285,21 @@ export declare class MfaService implements MfaRepository {
     private schemaName;
     constructor(db: NodePgDatabase, schemaName?: string);
     private qualify;
-    createMfaFactor(userId: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
-    getMfaFactors(userId: string): Promise<MfaFactor[]>;
+    createMfaFactor(uid: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    getMfaFactors(uid: string): Promise<MfaFactor[]>;
     getMfaFactorById(factorId: string): Promise<(MfaFactor & {
         secretEncrypted: string;
     }) | null>;
     verifyMfaFactor(factorId: string): Promise<void>;
-    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    deleteMfaFactor(factorId: string, uid: string): Promise<void>;
     createMfaChallenge(factorId: string, ipAddress?: string): Promise<MfaChallengeInfo>;
     getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null>;
     verifyMfaChallenge(challengeId: string): Promise<void>;
-    createRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
-    useRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
-    getUnusedRecoveryCodeCount(userId: string): Promise<number>;
-    deleteAllRecoveryCodes(userId: string): Promise<void>;
-    hasVerifiedMfaFactors(userId: string): Promise<boolean>;
+    createRecoveryCodes(uid: string, codeHashes: string[]): Promise<void>;
+    useRecoveryCode(uid: string, codeHash: string): Promise<boolean>;
+    getUnusedRecoveryCodeCount(uid: string): Promise<number>;
+    deleteAllRecoveryCodes(uid: string): Promise<void>;
+    hasVerifiedMfaFactors(uid: string): Promise<boolean>;
 }
 /** PostgreSQL user repository implementation */
 export type PostgresUserRepository = UserService;

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

@@ -0,0 +1,23 @@
+/**
+ * Replay a `pg_dumpall --globals-only` script one statement at a time,
+ * tolerating per-statement failures. On a same-cluster restore the roles
+ * usually already exist (`CREATE ROLE` → "already exists") and on a managed
+ * provider an `ALTER ROLE <superuser>` may be refused; neither should abort
+ * recreation of the roles that *are* missing. Returns how many statements
+ * applied vs were skipped.
+ *
+ * `runStatement` executes one SQL statement and rejects on error.
+ */
+export declare function applyGlobalsWith(runStatement: (sql: string) => Promise<void>, globalsSql: string, log?: (message: string) => void): Promise<{
+    applied: number;
+    skipped: number;
+}>;
+/**
+ * Delete each pruned dump together with its `.globals.sql` roles sidecar, so
+ * pruning never orphans the roles file. The sidecar is best-effort — older
+ * backups predate it, so a missing-sidecar failure is swallowed while a
+ * failure deleting the dump itself propagates.
+ *
+ * `deleteObject` removes one key and rejects if it cannot (e.g. not found).
+ */
+export declare function pruneWith(keys: string[], deleteObject: (key: string) => Promise<void>): Promise<void>;

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

@@ -5,8 +5,8 @@ export declare class BackupToolError extends Error {
     readonly hint?: string | undefined;
     constructor(message: string, hint?: string | undefined);
 }
-/** Locate `pg_dump` / `pg_restore`, honouring an env override. */
-export declare function resolvePgBinary(tool: "pg_dump" | "pg_restore", env?: Record<string, string | undefined>): string | null;
+/** Locate `pg_dump` / `pg_restore` / `pg_dumpall`, honouring an env override. */
+export declare function resolvePgBinary(tool: "pg_dump" | "pg_restore" | "pg_dumpall", env?: Record<string, string | undefined>): string | null;
 /** Run `<bin> --version` and extract the major version. */
 export declare function detectToolMajor(bin: string): Promise<number | null>;
 /** Query the server for its major version via `server_version_num`. */
@@ -27,11 +27,22 @@ export interface BackupResult {
     localFile: string;
     fileName: string;
     sizeBytes: number;
+    /**
+     * Absolute path of the `.globals.sql` sidecar holding cluster-wide roles
+     * (present unless globals capture was disabled or unavailable).
+     */
+    globalsFile?: string;
+    globalsSizeBytes?: number;
 }
 /**
  * Produce a custom-format dump on local disk. When `outDir` is omitted the
  * file is written to the OS temp directory (used by the upload path, which
  * cleans it up afterwards).
+ *
+ * Alongside the `-Fc` dump it writes a `<name>.globals.sql` sidecar via
+ * `pg_dumpall --globals-only` so the roles the dump's GRANT/RLS statements
+ * depend on can be recreated on restore. Set `includeGlobals: false` to skip
+ * it (e.g. when the caller has no privilege to read cluster globals).
  */
 export declare function createDump(opts: {
     connectionString: string;
@@ -41,19 +52,50 @@ export declare function createDump(opts: {
     excludeSchemas?: string[];
     noOwner?: boolean;
     inheritStdio?: boolean;
+    includeGlobals?: boolean;
     env?: Record<string, string | undefined>;
 }): Promise<BackupResult>;
+/**
+ * Cheap integrity check on a freshly written dump: it must be non-empty and
+ * `pg_restore --list` must parse its table of contents without error. Used
+ * before pruning older backups so a corrupt-but-exit-0 dump never becomes
+ * the reason the last good backup is deleted.
+ */
+export declare function validateDump(localFile: string, env?: Record<string, string | undefined>): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+/**
+ * Replay a `pg_dumpall --globals-only` script to recreate cluster roles
+ * before a restore, so the dump's GRANT/RLS statements (which reference
+ * `rebase_user` and any owner roles) actually apply. Runs statement by
+ * statement and tolerates per-statement failures — on a same-cluster restore
+ * the roles usually already exist (`CREATE ROLE` → "already exists"), and on
+ * a managed provider an `ALTER ROLE <superuser>` may be refused; neither
+ * should abort role recreation. Returns how many statements applied vs were
+ * skipped.
+ */
+export declare function applyGlobals(connectionString: string, globalsSql: string, log?: (message: string) => void): Promise<{
+    applied: number;
+    skipped: number;
+}>;
 /**
  * Restore a custom-format dump into the database named by
  * `connectionString`. Destructive when `clean` is set (drops objects
  * first). Never called automatically — the CLI gates it behind explicit
  * confirmation.
+ *
+ * Runs with `--exit-on-error` by default: a restore that logs-and-continues
+ * past a failed GRANT (because a role was missing) reports success with RLS
+ * un-enforced. Callers should recreate roles first (see {@link applyGlobals})
+ * and only set `exitOnError: false` deliberately.
  */
 export declare function restoreDump(opts: {
     connectionString: string;
     inputFile: string;
     clean?: boolean;
     noOwner?: boolean;
+    exitOnError?: boolean;
     inheritStdio?: boolean;
     env?: Record<string, string | undefined>;
 }): Promise<void>;

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

@@ -99,10 +99,50 @@ export declare function buildPgRestoreArgs(opts: {
     inputFile: string;
     /** Drop objects before recreating them (destructive but idempotent). */
     clean?: boolean;
-    /** Continue past individual errors instead of aborting. */
+    /**
+     * Abort on the first error instead of logging and continuing. Defaults
+     * ON: a restore that silently skips failed GRANT/RLS statements (because
+     * a role is missing) "succeeds" with RLS un-enforced — a security hole.
+     * Fail loudly instead so the operator knows the restore is incomplete.
+     */
     exitOnError?: boolean;
     noOwner?: boolean;
 }): string[];
+/**
+ * Assemble the `pg_restore --list` argument vector. Reading a dump's table
+ * of contents parses the whole archive without touching a database, so it is
+ * a cheap integrity check that the file isn't truncated or corrupt.
+ */
+export declare function buildPgRestoreListArgs(inputFile: 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
+ * `pg_dump` omits them. Without the `rebase_user` role the RLS GRANT
+ * statements in the main dump fail on restore and RLS is silently lost — so
+ * every backup captures the globals into a sidecar `.globals.sql`.
+ *
+ * `--no-role-passwords` keeps role secrets out of the artifact (backups may
+ * be shipped off-box); roles are recreated password-less and re-secured by
+ * the operator.
+ */
+export declare function buildPgDumpallGlobalsArgs(opts: {
+    connectionString: string;
+    outFile: string;
+}): string[];
+/**
+ * Derive the globals sidecar path/key for a given `.dump` file. Keeps the
+ * two artifacts adjacent so listing, uploading and pruning can find one from
+ * the other. A name that doesn't end in `.dump` is returned unchanged with a
+ * `.globals.sql` suffix appended.
+ */
+export declare function globalsFileForDump(dumpPath: string): string;
+/**
+ * Split a `pg_dumpall --globals-only` script into individual statements.
+ * Used when replaying globals on restore so each `CREATE ROLE` / `GRANT`
+ * can run independently and a benign "role already exists" on one doesn't
+ * abort the rest. Drops `--` comment lines and blank statements.
+ */
+export declare function splitGlobalsStatements(sql: string): string[];
 /**
  * Resolve the Postgres connection string the backup commands should use,
  * mirroring the precedence the branch command already relies on.

package/dist/chunk-DSJWtz9O.js

@@ -0,0 +1,40 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+const require = __createRequire(import.meta.url);
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+});
+//#endregion
+export { __toESM as i, __exportAll as n, __require as r, __commonJSMin as t };

package/dist/cli-helpers.d.ts

@@ -4,4 +4,36 @@ export declare function getTableIncludesFromCollections(collections: CollectionC
 export declare function getTableIncludes(collectionsPath: string): Promise<string[]>;
 export declare function getDevDatabaseUrl(databaseUrl: string): string;
 export declare function ensureDevDatabaseExists(databaseUrl: string, devDatabaseUrl: string): Promise<void>;
-export declare function getTableExcludes(databaseUrl: string, collectionsPath: string): Promise<string[]>;
+/**
+ * Query the live database for every user table/view outside the system
+ * catalogs. Separated from {@link getTableExcludes} so its failure mode can
+ * be handled explicitly (fail closed) and so tests can inject a stub.
+ */
+export declare function queryExistingTables(databaseUrl: string): Promise<string[]>;
+/**
+ * Raised when the exclude list could not be built. `db push` MUST abort on
+ * this rather than continue: the exclude list is the only thing shielding
+ * non-collection (user/system) tables from the auto-approved declarative
+ * apply. A partial list — the old fail-open behaviour — meant a transient
+ * introspection hiccup dropped every table not present in `schema.sql`.
+ */
+export declare class ExcludeIntrospectionError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Build the `--exclude` list that protects tables Rebase doesn't manage from
+ * the declarative apply. Anything not backing a collection (or its M2M
+ * junctions) is excluded so Atlas never drops it.
+ *
+ * Fails **closed**: if the database can't be introspected we cannot know
+ * which tables to protect, so we throw {@link ExcludeIntrospectionError}
+ * instead of returning a near-empty list and letting the caller drop
+ * everything.
+ *
+ * `deps` is injectable for tests; production uses the real pg-backed queries.
+ */
+export declare function getTableExcludes(databaseUrl: string, collectionsPath: string, deps?: {
+    queryExistingTables?: (databaseUrl: string) => Promise<string[]>;
+    getIncludes?: (collectionsPath: string) => Promise<string[]>;
+}): Promise<string[]>;