@pg-nano/pg-tmp

import { StdioOptions } from 'node:child_process';

PREFIX

Prefix used for temporary root directories created under os.tmpdir().

Remarks

start() scans directories with this prefix when it looks for a prewarmed cluster that can be claimed with its NEW marker.

export const PREFIX = "pg_tmp.";

InitOptions

Options for initdb().

export type InitOptions = {
    /**
     * Controls `initdb` output.
     *
     * @remarks
     * Only `'inherit'` is honored. It forwards `initdb` output to the parent
     * process, which is useful when debugging local Postgres installation or
     * initialization failures.
     */
    stdio?: StdioOptions;
};

initdb

Initializes a temporary PostgreSQL root directory.

The returned directory is the pg-tmp container root. The actual PostgreSQL cluster is created in its data child directory, and the root receives a NEW marker so a later start() call can claim prewarmed clusters.

Parameters

• dataDir: Optional container root. When omitted or null, a new directory is created under os.tmpdir() with the PREFIX prefix.
• options: Initialization options.

Returns

The initialized container root.

Examples

import { initdb, start } from '@pg-nano/pg-tmp'
const dataDir = await initdb()
const pg = await start({ dataDir, timeout: 0 })
await pg.stop()

export function initdb(dataDir?: string | null, { stdio }?: InitOptions): Promise<string>;

StartOptions

Options for start().

export type StartOptions = {
    /**
     * pg-tmp container root.
     *
     * @remarks
     * If omitted, `start()` first tries to claim a prewarmed `pg_tmp.*` directory
     * with a compatible `data/PG_VERSION` file and a `NEW` marker. If no
     * compatible prewarmed root exists, it initializes a new one.
     */
    dataDir?: string;
    /**
     * Controls whether Postgres listens on TCP instead of the default Unix
     * socket.
     *
     * @remarks
     * Use `true` to listen on `127.0.0.1`, or pass a custom host address. When
     * omitted or `false`, pg-tmp uses a Unix socket in the `data` directory.
     *
     * @default false
     */
    host?: string | boolean;
    /**
     * TCP port to listen on when `host` is enabled.
     *
     * @remarks
     * When `host` is enabled and `port` is omitted, an unused local port is
     * selected. Socket mode ignores this option.
     */
    port?: number;
    /**
     * Delay (in seconds) before the PostgreSQL instance is
     * automatically stopped. If zero or negative, you are responsible
     * for stopping the database.
     *
     * Note that the instance won't be stopped if active connections
     * exist. In that case, the timeout is restarted and the database
     * continues to run.
     *
     * @default 60
     */
    timeout?: number;
    /**
     * Preserve the pg-tmp container root after the background or manual stop.
     *
     * @default false
     */
    keep?: boolean;
    /**
     * Extra options passed directly to the `postgres` process.
     *
     * @remarks
     * This string is split into process arguments before startup. Do not set
     * `listen_addresses` or `port`; pg-tmp configures those from `host` and
     * `port`.
     */
    postgresOptions?: string;
};

PgTmp

Running temporary PostgreSQL server returned by start().

export type PgTmp = {
    /**
     * Connection string for the `test` database.
     *
     * @remarks
     * Socket mode returns `postgresql:///test?host=...`. TCP mode returns
     * `postgresql://host:port/test`.
     */
    dsn: string;
    /**
     * pg-tmp container root. The actual PostgreSQL cluster is in `dataDir/data`.
     */
    dataDir: string;
    /**
     * Stops Postgres and removes the container root unless `keep` is true.
     */
    stop(options?: StopOptions): Promise<void>;
};

start

Starts a temporary PostgreSQL server and returns connection details.

start() claims or initializes a pg-tmp container root, starts Postgres, ensures the test database exists, and schedules a background stop process unless timeout is zero or negative.

Parameters

• options: Startup and lifecycle options.

Returns

A running server handle with a connection string, container root, and manual stop() method.

Examples

import { start } from '@pg-nano/pg-tmp'
const pg = await start({ timeout: 0 })
try {
 console.log(pg.dsn)
} finally {
 await pg.stop()
}

export function start(options?: StartOptions): Promise<PgTmp>;

StopOptions

Options for stop().

export type StopOptions = {
    /**
     * Preserve the pg-tmp container root after Postgres stops.
     *
     * @default false
     */
    keep?: boolean;
    /**
     * Delay (in seconds) before the PostgreSQL instance is stopped. If
     * zero or negative, the instance is stopped even if there are
     * active connections.
     *
     * Note that the instance won't be stopped if active connections
     * exist. In that case, the timeout is restarted and the database
     * continues to run.
     *
     * @default 5
     */
    timeout?: number;
    /**
     * Delay in seconds before the first active-connection check.
     *
     * @default 0
     */
    initialTimeout?: number;
    /**
     * Stop without waiting for active connections to finish.
     */
    force?: boolean;
    /**
     * TCP host used by a server started with `host`.
     */
    host?: string;
    /**
     * TCP port used by a server started with `host`.
     */
    port?: number;
    /**
     * Retained for compatibility with older pg-tmp releases.
     *
     * @deprecated `stop()` no longer invokes `pg_ctl` directly, so this option
     * has no effect.
     */
    stdio?: StdioOptions;
    /**
     * Print lifecycle messages while waiting for connections, stopping Postgres,
     * and removing the container root.
     */
    verbose?: boolean;
};

stop

Stops a running temporary PostgreSQL server.

By default, stop() waits for active connections to the test database to finish, stops Postgres, and removes the pg-tmp container root.

Parameters

• dataDir: pg-tmp container root returned by initdb() or start().
• options: Stop and cleanup options.

Examples

import { stop } from '@pg-nano/pg-tmp'
await stop('/tmp/pg_tmp.example', { force: true })

export function stop(dataDir: string, options?: StopOptions): Promise<void>;