pg-test-util

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

- Synopsis
- Details
- API
- Table of contents
- Classes
- Interfaces
- Type aliases
- Type aliases
- EntityInfo
- SequenceInfo
- Classes
- Class: Database
- Table of contents
- Properties
- Accessors
- Methods
- Properties
- client
- drop
- Accessors
- name
- Methods
- connect
- disconnect
- getMaterializedViews
- getPartitionedTables
- getSequences
- getTables
- getViews
- query
- queryFile
- refresh
- syncSequences
- truncate
- Class: default
- Table of contents
- Methods
- Methods
- cleanup
- copyDatabase
- createDatabase
- createUser
- disconnect
- disconnectAll
- dropAll
- dropAllDatabases
- dropAllUsers
- dropConnections
- dropDatabase
- dropUser
- fetchAllDatabaseNames
- getDatabase
- getUserNames
- query
- new
- Interfaces
- Interface: Options
- Table of contents
- Properties
- Properties
- baseName
- cleanupOnError
- database
- safe

Synopsis

``ts
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

Table of contents

$3

- Database
- default

$3

- Options

$3

- EntityInfo
- SequenceInfo

Type aliases

$3

Ƭ 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

---

$3

Ƭ 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.

Table of contents

$3

- client
- drop

$3

- name

$3

- connect
- disconnect
- getMaterializedViews
- getPartitionedTables
- getSequences
- getTables
- getViews
- query
- queryFile
- refresh
- syncSequences
- truncate

Properties

$3

• Readonly client: Client

node-postgres client

#### Defined in

database.ts:35

---

$3

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

#### Type declaration

▸ (): Promise<void\>

Drops the database.

##### Returns

Promise<void\>

#### Defined in

database.ts:38

Accessors

$3

• get name(): string

Name of the database

#### Returns

string

#### Defined in

database.ts:62

Methods

$3

▸ connect(): Promise<void\>

Connects to database.

#### Returns

Promise<void\>

#### Defined in

database.ts:67

---

$3

▸ disconnect(): Promise<void\>

Disconnects from database.

#### Returns

Promise<void\>

#### Defined in

database.ts:78

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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.

Table of contents

$3

- cleanup
- copyDatabase
- createDatabase
- createUser
- disconnect
- disconnectAll
- dropAll
- dropAllDatabases
- dropAllUsers
- dropConnections
- dropDatabase
- dropUser
- fetchAllDatabaseNames
- getDatabase
- getUserNames
- query
- new

Methods

$3

▸ cleanup(): Promise<void\>

#### Returns

Promise<void\>

#### Defined in

pg-test-util.ts:310

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ disconnect(): Promise<void\>

Disconnects admin client.

#### Returns

Promise<void\>

#### Defined in

pg-test-util.ts:109

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ dropAllUsers(): Promise<void\>

Drops all users created by this instance.

#### Returns

Promise<void\>

#### Defined in

pg-test-util.ts:295

---

$3

▸ dropConnections(databaseName): Promise<void\>

#### Parameters

| Name | Type |
| :------------- | :------- |
| databaseName | string |

#### Returns

Promise<void\>

#### Defined in

pg-test-util.ts:235

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

---

$3

▸ 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

Table of contents

$3

- baseName
- cleanupOnError
- database
- safe

Properties

$3

• Optional baseName: string

Prefix to be used when creating new databases.

#### Defined in

pg-test-util.ts:12

---

$3

• Optional cleanupOnError: boolean

Whether to drop all created objects if error is thorwn.

#### Defined in

pg-test-util.ts:14

---

$3

• 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

---

$3

• Optional safe: boolean`

Drop only objects created by this instance.

#### Defined in

pg-test-util.ts:10

<%_ } _%>