import type { StorageController } from "@rebasepro/server";
import { BackupDestination, type RowSecurityIdentity, VersionCompatibility } from "./pg-tools";
import { BackupObject, RetentionOptions } from "./retention";
/**
 * Remove a dump artifact abandoned by a failed tool run. See
 * {@link discardPartialDumpWith} for why this exists and why the logic lives
 * in the execa-free module.
 */
export declare function discardPartialDump(file: string): void;
export declare class BackupToolError extends Error {
    readonly hint?: string | undefined;
    constructor(message: string, hint?: string | undefined);
}
/** 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`. */
export declare function getServerVersionMajor(connectionString: string): Promise<number | null>;
export interface PreflightResult extends VersionCompatibility {
    bin: string;
    toolMajor: number | null;
    serverMajor: number | null;
}
/**
 * Verify the requested client tool exists and its major version is
 * compatible with the live server. Throws {@link BackupToolError} — with a
 * doctor-style hint — when the binary is missing.
 */
export declare function preflight(tool: "pg_dump" | "pg_restore", connectionString: string, env?: Record<string, string | undefined>): Promise<PreflightResult>;
export interface BackupResult {
    /** Absolute path of the produced dump file on local disk. */
    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;
    dbName: string;
    outDir?: string;
    fileName?: string;
    excludeSchemas?: string[];
    noOwner?: boolean;
    inheritStdio?: boolean;
    includeGlobals?: boolean;
    env?: Record<string, string | undefined>;
    /**
     * Dump with row security left on, reading as this identity.
     *
     * The escape hatch for a managed Postgres, where the dumping role owns
     * nothing and has no `BYPASSRLS`. Off by default, and deliberately so: with
     * row security on, `pg_dump` stops erroring on rows it cannot see and
     * simply omits them. See {@link RowSecurityIdentity}.
     */
    rowSecurity?: RowSecurityIdentity;
}): 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>;
/**
 * Create a database (if absent) by connecting to the maintenance
 * `postgres` database. Used by `restore --create-db`.
 */
export declare function ensureDatabaseExists(adminConnectionString: string, dbName: string): Promise<boolean>;
/**
 * Upload a local dump to object storage under the destination's prefix.
 * Backups may contain secrets/PII, so the object is written with a
 * private/octet-stream content type; bucket-level ACLs must stay private.
 */
export declare function uploadBackup(storage: StorageController, localFile: string, dest: Extract<BackupDestination, {
    kind: "s3" | "gcs";
}>): Promise<{
    key: string;
    storageUrl: string;
}>;
/**
 * List existing backups at a destination. For local destinations reads the
 * directory; for object storage lists the prefix via the controller.
 */
export declare function listBackups(dest: BackupDestination, storage?: StorageController): Promise<BackupObject[]>;
/**
 * Apply a retention policy to a destination, deleting the backups selected
 * by {@link selectBackupsToPrune}. Returns the keys that were removed.
 */
export declare function pruneBackups(dest: BackupDestination, options: RetentionOptions, storage?: StorageController): Promise<string[]>;