Reference

local-postgres

Functions

`startPostgres`

Starts a local PostgreSQL server and returns connection details.

The data directory is created and initialized when needed, the server is started, readiness is verified, optional superuser/database setup is applied, and the returned stop() function shuts the process down.

export function startPostgres(options: StartPostgresOptions): Promise<LocalPostgresServer>;

^{🔍 startPostgres on GitHub}

import { Writable } from "node:stream";

Classes

`LocalPostgresError`

Error type used for operational failures reported by local-postgres.

export class LocalPostgresError extends Error {
  /** Bounded Postgres process output captured while an operation was failing. */
  readonly diagnostics?: string;
  constructor(message: string, options?: ErrorOptions & {
    diagnostics?: string;
  });
}

^{🔍 LocalPostgresError on GitHub}

`PostgresDataDirInUseError`

Indicates that a data directory's postmaster.pid belongs to a live process.

export class PostgresDataDirInUseError extends LocalPostgresError {
  readonly dataDir: string;
  readonly pid: number;
  constructor(dataDir: string, pid: number);
}

^{🔍 PostgresDataDirInUseError on GitHub}

Constants

`DEFAULT_POSTGRES_CACHE_DIR`

Default directory used to cache managed Postgres binary packages.

export const DEFAULT_POSTGRES_CACHE_DIR: string;

^{🔍 DEFAULT_POSTGRES_CACHE_DIR on GitHub}

Types

`LocalPostgresEnv`

Environment values for clients and child processes that should connect to the server.

export interface LocalPostgresEnv {
  PGDATA: string;
  PGDATABASE: string;
  PGHOST: string;
  PGPORT: string;
  DATABASE_URL: string;
  PGUSER?: string;
  PGPASSWORD?: string;
}

Properties

PGDATA Data directory used by the server.
PGDATABASE Database exposed by the returned connection details.
PGHOST TCP host or Unix socket directory used by clients.
PGPORT Server port formatted for environment variables.
DATABASE_URL PostgreSQL connection URL for the returned server.
PGUSER Superuser name when superuser was provided.
PGPASSWORD Superuser password when superuser was provided.

^{🔍 LocalPostgresEnv on GitHub}

`LocalPostgresLogger`

Receives lifecycle messages from local-postgres.

export interface LocalPostgresLogger {
  info(message: string): void;
  warn(message: string): void;
  error(message: string): void;
}

Properties

info Called for normal lifecycle progress messages.
warn Called when a recoverable fallback or unusual condition occurs.
error Called when the managed Postgres process exits unexpectedly.

^{🔍 LocalPostgresLogger on GitHub}

`LocalPostgresServer`

Running server returned by startPostgres.

export interface LocalPostgresServer {
  dataDir: string;
  database: string;
  listen: ResolvedPostgresListenOptions;
  host: string;
  port: number;
  socketDir?: string;
  user?: string;
  password?: string;
  pid?: number;
  connectionString: string;
  env: LocalPostgresEnv;
  stop(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>;
}

Properties

dataDir Data directory passed to startPostgres.
database Database exposed to callers.
listen Normalized listen configuration used by the server.
host Client host, or socket directory in socket mode.
port Server port.
socketDir Socket directory when the server is listening on a Unix socket.
user Superuser name when superuser was provided.
password Superuser password when superuser was provided.
pid Child process id reported by Node.js when available.
connectionString PostgreSQL connection URL with database and optional credentials encoded.
env Environment values for clients and child processes.
stop Stops the server process. Safe to call more than once.
[Symbol.asyncDispose] Supports await using by delegating to stop().

^{🔍 LocalPostgresServer on GitHub}

`LocalPostgresSuperuser`

Superuser role that should exist before startPostgres resolves.

export interface LocalPostgresSuperuser {
  name: string;
  password: string;
}

Properties

name Role name to create or update with LOGIN SUPERUSER.
password Password assigned to the role and returned in connection details.

^{🔍 LocalPostgresSuperuser on GitHub}

`PostgresBinaryOptions`

Options that control which postgres and initdb binaries are used.

export interface PostgresBinaryOptions {
  version?: string;
  strategy?: PostgresBinaryStrategy;
  cacheDir?: string;
}

Properties

version Required Postgres version. A major version such as 18 accepts any matching major version. More specific values require matching components.
strategy How local binaries and managed downloads should be resolved.

Defaults to prefer-local when this object is provided. When postgres is omitted, local-only preserves the package's original behavior.
cacheDir Directory for downloaded npm package tarballs and extracted binaries.

Defaults to path.join(os.homedir(), ".local-postgres").

^{🔍 PostgresBinaryOptions on GitHub}

`PostgresBinaryStrategy`

Strategy for resolving local or managed Postgres binaries.

export type PostgresBinaryStrategy = 'local-only' | 'prefer-local' | 'prefer-download' | 'download-only';

^{🔍 PostgresBinaryStrategy on GitHub}

`PostgresConfigValue`

Value type accepted when appending PostgreSQL settings to postgresql.conf.

export type PostgresConfigValue = string | number | boolean;

^{🔍 PostgresConfigValue on GitHub}

`PostgresListenOptions`

Listen configuration for TCP or Unix socket Postgres servers.

export type PostgresListenOptions = {
  type: 'tcp'; /** TCP host passed to `postgres -h`. Defaults to `127.0.0.1`. */
  host?: string; /** TCP port. When omitted, an available local port is selected. */
  port?: number;
} | {
  type: 'socket'; /** Directory passed to `postgres -k` and used as the client host. */
  socketDir: string; /** Socket port component. Defaults to PostgreSQL's `5432`. */
  port?: number;
};

Properties

type Start a TCP listener.
type Start a Unix socket listener.

^{🔍 PostgresListenOptions on GitHub}

`PostgresOutputTarget`

Destination for Postgres process stdout and stderr. on-error keeps a bounded in-memory tail quiet during successful startup and adds it to a LocalPostgresError when startup fails.

export type PostgresOutputTarget = 'ignore' | 'inherit' | 'on-error' | {
  filePath: string;
} | Writable;

Properties

filePath File path that receives appended Postgres stdout and stderr output.

^{🔍 PostgresOutputTarget on GitHub}

`ResolvedPostgresListenOptions`

Normalized listen configuration returned after defaults are applied.

export type ResolvedPostgresListenOptions = {
  type: 'tcp'; /** Concrete TCP host used by the server and clients. */
  host: string; /** Concrete TCP port used by the server and clients. */
  port: number;
} | {
  type: 'socket'; /** Concrete socket directory used by the server and clients. */
  socketDir: string; /** Concrete socket port component. */
  port: number;
};

Properties

type TCP listener.
type Unix socket listener.

^{🔍 ResolvedPostgresListenOptions on GitHub}

`StartPostgresOptions`

Options for the high-level startPostgres lifecycle helper.

export interface StartPostgresOptions {
  dataDir: string;
  database?: string;
  port?: number;
  host?: string;
  listen?: PostgresListenOptions;
  config?: Record<string, PostgresConfigValue>;
  superuser?: LocalPostgresSuperuser;
  postgresOutput?: PostgresOutputTarget;
  postgres?: PostgresBinaryOptions;
  logger?: Partial<LocalPostgresLogger>;
  readinessTimeoutMs?: number;
  readinessIntervalMs?: number;
  stopTimeoutMs?: number;
}

Properties

dataDir Directory containing the Postgres data cluster. The directory is created and initialized when it does not already contain a PG_VERSION file.
database Database to create if needed and expose in connection details.

Defaults to postgres.
port Port for the Postgres TCP server. When omitted, an available local port is selected before the server starts. Fixed ports are probed before startup.
host TCP host for the Postgres server.

Defaults to 127.0.0.1.
listen Lower-level listen configuration. When omitted, the friendly API starts a TCP server using host and port. Do not combine this with host or port.
config PostgreSQL configuration values appended after a new cluster is initialized. Existing clusters are left untouched.
superuser Superuser role to create or update after the server is ready. When set, returned connection details include this role's credentials.
postgresOutput Where raw stdout and stderr from the postgres server process should go.

Defaults to ignore. Use on-error for quiet successful startup with captured failure diagnostics. File targets create parent directories when needed.
postgres Postgres binary resolution behavior. Omit this for local-only PATH based behavior. Provide it to enable version checks and managed downloads.
logger Optional lifecycle logger. Missing methods are treated as no-ops.
readinessTimeoutMs Maximum time to wait for Postgres to accept bootstrap connections.

Defaults to 3000ms.
readinessIntervalMs Delay between readiness checks.

Defaults to 100ms.
stopTimeoutMs Maximum time to wait after each shutdown signal.

Defaults to 5000ms.

^{🔍 StartPostgresOptions on GitHub}