pg-test-util

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

Synopsis
Details
API
- Table of contents
- Type aliases
  - EntityInfo
  - SequenceInfo
Classes
Class: Database
- Table of contents
- Properties
  - client
  - drop
- Accessors
  - name
- Methods
Class: default
- Table of contents
  - Methods
- Methods
Interfaces
Interface: Options
- Table of contents
  - Properties
- Properties
  - baseName
  - cleanupOnError
  - database
  - safe

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

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

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.

Parameters

Name	Type	Description
`name`	`string`	is database name to get instance for. `defaultDatabaseName` is used by default.

Returns

Promise<Database>

Database instance for given database name.

Defined in

pg-test-util.ts:96

getUserNames

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

Fetches database users from database.

Parameters

Name	Type	Default value	Description
`onlyCreated`	`boolean`	`false`	is whether to fetch users only created by this utility instance.

Returns

Promise<string[]>

array of usernames.

Defined in

pg-test-util.ts:273

query

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

Executes given SQL in admin clinet and returns result rows. Admin client can be used fro administration queries such as creating databases etc.

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

pg-test-util.ts:81

new

▸ Static new(connection, options?): Promise<default>

Create an instance.

Parameters

Name	Type	Description
`connection`	`string` \| `Client` \| `ClientConfig`	is the `pg.client` or connection parameters for `pg.client`.
`options`	`Options`	are options.

Returns

Promise<default>

Defined in

pg-test-util.ts:45

Interfaces

pg-test-util / Options

Interface: Options

Options

Properties

baseName

• Optional baseName: string

Prefix to be used when creating new databases.

Defined in

pg-test-util.ts:12

cleanupOnError

• Optional cleanupOnError: boolean

Whether to drop all created objects if error is thorwn.

Defined in

pg-test-util.ts:14

database

• Optional database: string

Admin database name to connect. To create other databases we need to connect a database.

Defined in

pg-test-util.ts:16

safe

• Optional safe: boolean

Drop only objects created by this instance.

Defined in

pg-test-util.ts:10

<%_ } _%>

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.github/workflows		.github/workflows
.husky		.husky
config		config
module-files		module-files
sql		sql
src		src
test		test
.commitlintrc		.commitlintrc
.czrc		.czrc
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
LICENSE		LICENSE
README.md		README.md
README.njk		README.njk
jest.config.js		jest.config.js
lint-staged.config.js		lint-staged.config.js
package-lock.json		package-lock.json
package.json		package.json
prettier.config.js		prettier.config.js
tsconfig.json		tsconfig.json

License

ozum/pg-test-util

Folders and files

Latest commit

History

Repository files navigation

pg-test-util

Synopsis

Details

API

Table of contents

Classes

Interfaces

Type aliases

Type aliases

EntityInfo

Type declaration

Defined in

SequenceInfo

Type declaration

Defined in

Classes

Class: Database

Table of contents

Properties

Accessors

Methods

Properties

client

Defined in

drop

Type declaration

Returns

Defined in

Accessors

name

Returns

Defined in

Methods

connect

Returns

Defined in

disconnect

Returns

Defined in

getMaterializedViews

Returns

Defined in

getPartitionedTables

Returns

Defined in

getSequences

Returns

Defined in

getTables

Returns

Defined in

getViews

Returns

Defined in

query

Type parameters

Parameters

Returns

Defined in

queryFile

Type parameters

Parameters

Returns

Defined in

refresh

Returns

Defined in

syncSequences

Returns

Defined in

truncate

Parameters

Returns

Defined in