Pg-test-util NPM

pg-test-util

PostgreSQL administrative utilities such as creating and dropping tables, users etc.

Synopsis

import PgTestUtil from "../src/index";

let pgTestUtil: PgTestUtil;

beforeAll(async () => {
  pgTestUtil = await PgTestUtil.new({ user: "user", password: "password" });
});

afterAll(async () => {
  await pgTestUtil.cleanup();
});

describe("pg-test-util", () => {
  it("should create database", async () => {
    const sql = `CREATE TABLE public.member ( id SERIAL NOT NULL, name TEXT NOT NULL, PRIMARY KEY(id))`;
    const database = await pgTestUtil.createDatabase({ sql });
    expect(await database.query("SELECT * FROM member")).toEqual([]);
  });
});

Details

<% if (typedoc) { %>

API

Classes

Interfaces

Options

Type aliases

EntityInfo

Ƭ EntityInfo: Object

Type to store entity details.

Type declaration

Name	Type	Description
`name`	`string`	Entity name
`schema`	`string`	Schema name of the entity.

Defined in

types.ts:2

SequenceInfo

Ƭ SequenceInfo: Object

Type declaration

Name	Type	Description
`column`	`string`	Column name which sequence is related to.
`name`	`string`	Name of the sequence
`schema`	`string`	Schema name of the table sequence is defined.
`table`	`string`	Table name of the sequence.

Defined in

types.ts:9

Classes

pg-test-util / Database

Class: Database

Execute tasks related to individual database such as connecting, querying, getting tables, getting sequences etc.

Properties

Accessors

name

Methods

Properties

client

• Readonly client: Client

node-postgres client

Defined in

database.ts:35

drop

• Readonly drop: () => Promise<void>

Type declaration

▸ (): Promise<void>

Drops the database.

Returns

Promise<void>

Defined in

database.ts:38

Accessors

name

• get name(): string

Name of the database

Returns

string

Defined in

database.ts:62

Methods

connect

▸ connect(): Promise<void>

Connects to database.

Returns

Promise<void>

Defined in

database.ts:67

disconnect

▸ disconnect(): Promise<void>

Disconnects from database.

Returns

Promise<void>

Defined in

database.ts:78

getMaterializedViews

▸ getMaterializedViews(): Promise<EntityInfo[]>

Returns materialized views from database. Uses cache for fast results. Use refresh() method to refresh the cache.

Returns

Promise<EntityInfo[]>

Defined in

database.ts:136

getPartitionedTables

▸ getPartitionedTables(): Promise<EntityInfo[]>

Returns partitioned tables from database. Uses cache for fast results. Use refresh() method to refresh the cache.

Returns

Promise<EntityInfo[]>

Defined in

database.ts:142

getSequences

▸ getSequences(): Promise<SequenceInfo[]>

Returns sequences from database. Uses cache for fast results. Use refresh() method to refresh the cache.

Returns

Promise<SequenceInfo[]>

Defined in

database.ts:148

getTables

▸ getTables(): Promise<EntityInfo[]>

Returns tables from database. Uses cache for fast results. Use refresh() method to refresh the cache.

Returns

Promise<EntityInfo[]>

Defined in

database.ts:124

getViews

▸ getViews(): Promise<EntityInfo[]>

Returns views from database. Uses cache for fast results. Use refresh() method to refresh the cache.

Returns

Promise<EntityInfo[]>

Defined in

database.ts:130

query

▸ query<T>(sql, params?): Promise<T[]>

Executes given SQL and returns result rows.

Type parameters

Name	Type	Description
`T`	`any`	is type for single row returned by SQL query.

Parameters

Name	Type	Description
`sql`	`string`	is sql query.
`params?`	`any`[]	are array of parameters to pass query.

Returns

Promise<T[]>

result rows of the SQL query.

Defined in

database.ts:207

queryFile

▸ queryFile<T>(file, params?): Promise<T[]>

Reads and executes SQL in given file and returns results.

Type parameters

Name	Type	Description
`T`	`any`	is type for single row returned by SQL query.

Parameters

Name	Type	Description
`file`	`string`	is file to read SQL from.
`params?`	`any`[]	are array of parameters to pass query.

Returns

Promise<T[]>

result rows of the SQL query.

Defined in

database.ts:228

refresh

▸ refresh(): Promise<void>

Fetches database objects (i.e. tables, sequences) from database and refreshes the cache of the object. If you create new tables etc., you should refresh.

Returns

Promise<void>

Defined in

database.ts:89

syncSequences

▸ syncSequences(): Promise<void>

Set current value of sequence for each column of all tables based on record with maximum number. If there are no record in the table, the value will be set to 1.

Returns

Promise<void>

Defined in

database.ts:154

truncate

▸ truncate(ignore?): Promise<void>

Truncates all tables and resets their sequences in the database.

Parameters

Name	Type	Description
`ignore`	`Object`	are the list of the tables to ignore.
`ignore.ignore?`	`string`[]	-

Returns

Promise<void>

Defined in

database.ts:180

pg-test-util / default

Class: default

PgTestUtil class is used to perform PostgreSQL operations related to unit testing such as create database, truncate database and drop database etc.

Methods

cleanup

▸ cleanup(): Promise<void>

Returns

Promise<void>

Defined in

pg-test-util.ts:310

copyDatabase

▸ copyDatabase(options): Promise<Database>

Copies a given database with a new name.

Parameters

Name	Type	Description
`options`	`Object`	is configuration.
`options.drop?`	`boolean`	is whether to drop target database before copy.
`options.safe?`	`boolean`	If true, only databases created by this instance is dropped.
`options.source?`	`string` \| `Database`	-
`options.target?`	`string` \| `Database`	-

Returns

Promise<Database>

Database object.

Defined in

pg-test-util.ts:189

createDatabase

▸ createDatabase(options?): Promise<Database>

Creates a database. If name is not provided generates a name using baseName from constructor and part of epoch time.

Parameters

Name	Type	Description
`options`	`Object`	is configuration
`options.drop?`	`boolean`	is whether to drop database before create command.
`options.encoding?`	`string`	is database encoding
`options.file?`	`string`	is SQL query file to execute on database after it is created.
`options.name?`	`string`	is database name
`options.safe?`	`boolean`	If true, only databases created by this instance is dropped.
`options.sql?`	`string`	is SQL query to execute on database after it is created.
`options.template?`	`string`	is database template to use.

Returns

Promise<Database>

Database object representing created database.

Defined in

pg-test-util.ts:148

createUser

▸ createUser(user, password): Promise<void>

Creates a new database user if it does not exist.

Parameters

Name	Type	Description
`user`	`string`	is the name of the user.
`password`	`string`	is the password for the user.

Returns

Promise<void>

Defined in

pg-test-util.ts:256

disconnect

▸ disconnect(): Promise<void>

Disconnects admin client.

Returns

Promise<void>

Defined in

pg-test-util.ts:109

disconnectAll

▸ disconnectAll(options?): Promise<void[]>

Disconnects all clients.

Parameters

Name	Type	Description
`options`	`Object`	are options.
`options.admin`	`undefined` \| `boolean`	whether to disconnect admin client.

Returns

Promise<void[]>

Defined in

pg-test-util.ts:123

dropAll

▸ dropAll(options?): Promise<void>

Drops all items created by this instance.

Parameters

Name	Type	Description
`options`	`Object`	are options.
`options.disconnect`	`undefined` \| `boolean`	is whether to disconnect admin client.

Returns

Promise<void>

Defined in

pg-test-util.ts:306

dropAllDatabases

▸ dropAllDatabases(options?): Promise<void>

Drops all databases created by this instance.

Parameters

Name	Type	Description
`options`	`Object`	are options.
`options.disconnect`	`undefined` \| `boolean`	is whether to disconnect admin client.

Returns

Promise<void>

Defined in

pg-test-util.ts:245

dropAllUsers

▸ dropAllUsers(): Promise<void>

Drops all users created by this instance.

Returns

Promise<void>

Defined in

pg-test-util.ts:295

dropConnections

▸ dropConnections(databaseName): Promise<void>

Parameters

Name	Type
`databaseName`	`string`

Returns

Promise<void>

Defined in

pg-test-util.ts:235

dropDatabase

▸ dropDatabase(database?, options?): Promise<void>

Drops given database. To ensure the task, drops all connections to the database beforehand. If dropOnlyCreated is true and database is not created by this instance, throws error.

Parameters

Name	Type	Description
`database`	`string` \| `Database`	is database name or Database instance to drop.
`options`	`Object`	are options
`options.safe`	`undefined` \| `boolean`	If true, only databases created by this instance is dropped.

Returns

Promise<void>

Defined in

pg-test-util.ts:217

dropUser

▸ dropUser(user, options?): Promise<void>

Drops database user.

Parameters

Name	Type	Description
`user`	`string`	is user name to drop.
`options`	`Object`	are options.
`options.safe`	`undefined` \| `boolean`	If true, only users created by this instance is dropped.

Returns

Promise<void>

Defined in

pg-test-util.ts:286

fetchAllDatabaseNames

▸ fetchAllDatabaseNames(onlyCreated?): Promise<string[]>

Fetches the list of all databases from server.

Parameters

Name	Type
`onlyCreated?`	`boolean`

Returns

Promise<string[]>

Defined in

pg-test-util.ts:130

getDatabase

▸ getDatabase(name?): Promise<Database>

Returns Database instance object for given database name. Also connects to database if it is not connected. If no connection details are provided, default database is returned using same connection parameters as master database.