API

PgDolly.connect(options?)

Connects to the server, and drops what earlier runs left behind (see Cleanup).

import { PgDolly } from 'pg-dolly';

const dolly = await PgDolly.connect({ prefix: 'app_test', retainMs: 60 * 60_000 });

Returns Promise<PgDolly>.

Throws PgDollyMissingUrlError without url or DATABASE_URL, and PgDollyPrefixError for an invalid prefix.

Options

Option	Type	Default	Description
url	string	process.env.DATABASE_URL	Server to connect to, as a postgres:// URL, as a user that can create databases. The URLs of clones differ from it only in the database name.
prefix	string	'pg_dolly'	Start of every database name it creates: 1-20 lowercase letters, digits and underscores, starting with a letter.
settings	Record<string, string | string[]>	defaultSettings	Settings of every database, as ALTER DATABASE … SET. A list is a setting that takes several values (search_path: ['app', 'public']). Names are case-insensitive, as in Postgres. Merged over the exported defaultSettings, which pin what initdb takes from the machine: TimeZone: 'UTC', DateStyle: 'ISO, MDY', lc_monetary, lc_numeric and lc_time: 'C', and default_text_search_config: 'pg_catalog.simple'. Templates are built with them, and they are part of the template's hash.
retainMs	number	86_400_000 (a day)	How long a template no run has used is kept, and a clone kept from a failed test.

dolly.template(sql, options?)

Gets the template for a schema, building it unless an earlier run already did. Calls with the same SQL share one template, and templates are built one at a time.

Parameter	Type	Description
sql	string	The schema, e.g. a committed schema.sql. An empty string gives an empty database, e.g. to run migrations in.
options.seed	string	SQL run after the schema, for data every test starts from. Part of the hash. See Data every test needs.

Returns Promise<DollyTemplate>:

Property	Type	Description
name	string	<prefix>_t_<hash>.
hash	string	Hash of the SQL: the schema, and the seed if any.
clone()	() => Promise<DollyDatabase>	See below.

Rejects with the error from Postgres if the SQL fails. Nothing is left behind, and the next call tries again. After close(), with PgDollyClosedError.

template.clone()

Creates a fresh database from the template, for one test.

Returns Promise<DollyDatabase>:

Property	Type	Description
name	string	Database name, starting with the prefix.
url	string	Connection URL: the server's, with this database's name.
keep()	() => void	Keeps the database when close() drops the rest, and prints its name. A later run drops it once retainMs has passed. Throws PgDollyClosedError once close() is called.

Rejects after close(), with PgDollyClosedError.

dolly.close()

Drops this run's clones, except those kept, and closes the connection. Calling it again does nothing.

Close every connection to the clones first: dropping a database ends any left open.

Returns Promise<void>.

dumpSchema(url, options?)

Dumps a database's schema with pg_dump --schema-only, normalized so the same schema always gives the same text: no version comments, no \restrict lines, and no owners, privileges or tablespaces. See dumpSchema.

Parameter	Type	Description
url	string	Database to dump, as a postgres:// URL.
options.data	string[]	Tables to dump the rows of too, after the schema, as pg_dump --table patterns. As INSERTs, with the sequences they own set to match. For a migration tool's own table, so a database built from the dump knows its migrations ran.

Needs pg_dump on the PATH, at least the server's major version.

Returns Promise<string>, which can be passed to template() as it is.

Rejects if pg_dump fails.

Errors

Every error pg-dolly throws extends PgDollyError.

Error	When
PgDollyMissingUrlError	Neither url nor DATABASE_URL is set.
PgDollyPrefixError	The prefix can't start a database name. Has prefix.
PgDollyClosedError	Used after close().

import { PgDolly, PgDollyPrefixError } from 'pg-dolly';

try {
    await PgDolly.connect({ prefix: 'Not-Valid' });
} catch (error) {
    if (error instanceof PgDollyPrefixError) {
        error.prefix;
               
PgDollyPrefixError.prefix: string
    }
}

Types

PgDollyOptions, DollyTemplate and DollyDatabase are exported as types.