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

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

Classes

• Database
• default

Interfaces

• Options

Type aliases

• EntityInfo
• SequenceInfo

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.

Table of contents

Properties

• client
• drop

Accessors

• name

Methods

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

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.

Table of contents

Methods

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

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

Table of contents

Properties

• baseName
• cleanupOnError
• database
• safe

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

<%_ } _%>