local-postgres/tmp

import { StdioOptions } from "node:child_process";

Functions

initdb

Initializes a temporary PostgreSQL container.

The returned path is the outer container. The actual cluster is stored in its data child directory and can later be claimed by start().

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

^{🔍 initdb on GitHub}

start

Starts an isolated temporary PostgreSQL server and ensures a test database.

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

^{🔍 start on GitHub}

stop

Stops a server created by start() and removes its temporary container by default.

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

^{🔍 stop on GitHub}

Constants

PREFIX

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

export const PREFIX = "pg_tmp.";

^{🔍 PREFIX on GitHub}

Types

InitOptions

Options for initdb().

export type InitOptions = {
  postgres?: PostgresBinaryOptions; /** Only `'inherit'` is honored; other values keep successful initialization quiet. */
  stdio?: StdioOptions;
};

Properties

• postgres Binary resolution behavior.

^{🔍 InitOptions on GitHub}

PgTmp

Running temporary PostgreSQL server returned by start().

export type PgTmp = {
  dsn: string; /** Temporary container root. The actual cluster is in `dataDir/data`. */
  dataDir: string; /** Stops Postgres and removes the container unless `keep` is true. */
  stop(options?: StopOptions): Promise<void>; /** Stops Postgres and applies the configured cleanup policy. */
  [Symbol.asyncDispose](): Promise<void>;
};

Properties

• dsn Connection string for the test database.

^{🔍 PgTmp on GitHub}

StartOptions

Options for start().

export type StartOptions = {
  dataDir?: string; /** Use TCP when true or a host string is provided. Unix sockets are the default. */
  host?: string | boolean; /** TCP port. An available port is selected when omitted. */
  port?: number; /** Seconds before a detached worker stops the server. Defaults to `60`; non-positive disables it. */
  timeout?: number; /** Preserve the container when the detached worker or returned handle stops it. */
  keep?: boolean; /** Initialize another container in the background after claiming one. Defaults to `true`. */
  prewarm?: boolean; /** Binary resolution behavior, including opt-in managed Postgres downloads. */
  postgres?: PostgresBinaryOptions; /** Additional command-line options passed to `postgres`. */
  postgresOptions?: string;
};

Properties

• dataDir Temporary container root. When omitted, a prewarmed container may be claimed.

^{🔍 StartOptions on GitHub}

StopOptions

export type StopOptions = {
  keep?: boolean;
  timeout?: number; /** Seconds to wait before the first active-connection check. Defaults to `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 `@pg-nano/pg-tmp`. */
  stdio?: import('node:child_process').StdioOptions; /** Print lifecycle messages while waiting, stopping, and removing files. */
  verbose?: boolean;
};

Properties

• keep Preserve the temporary container after Postgres stops. Defaults to false.

• timeout Seconds to wait between active-connection checks. A non-positive value stops immediately. Defaults to 5.

^{🔍 StopOptions on GitHub}