Database API

Database is the API for database-level operations. This object is obtained via client.database()

See content

• database.name
• database.createTable()
• database.alterTable()
• database.dropTable()
• database.hasTable()
• database.tables()
• database.table()
• database.savepoint()
• database.schema()

database.name:

The name associated with the Database instance.

database.name: (string, readonly)

⚽️ Usage:

const database = client.database('test_db');
console.log(database.name); // test_db

database.createTable():

Dynamically run a CREATE TABLE operation.

database.createTable(tableJson: TableSchemaSpec, options?: Options): Promise<Savepoint>

⚙️ Spec:

• tableJson (TableSchemaSpec): an object specifying the intended table structure to create.
• options (Options, optional): as described in query().
• Return value: a Savepoint instance.

⚽️ Usage:

const savepoint = await database.createTable({
    name: 'table_1'
    columns: [
        { name: 'column_1', type: 'int' }, 
        { name: 'column_2', type: 'time' }
    ]
}, { description: 'Just testing table creation' });

Some additional parameters via options:

• ifNotExists (boolean, optional): a flag to conditionally create the table.

  const savepoint = await database.createTable({
      name: 'table_1'
      columns: [ ... ]
  }, { ifNotExists: true, description: 'Just testing table creation' });

database.alterTable():

Dynamically run an ALTER TABLE operation.

database.alterTable(tableName: string, callback: (tableSchemaApi: TableSchemaAPI) => void, options?: Options): Promise<Savepoint>

⚙️ Spec:

• tableName (string): the table name.
• callback ((tableSchemaApi: TableSchemaAPI) => void): a function that is called with the requested table schema. This can be async.
• options (Options, optional): as described in query().
• Return value: a Savepoint instance.

⚽️ Usage:

const savepoint = await database.alterTable('table_1', tableSchemaApi => {
    tableSchemaApi.name('table_1_new');
    tableSchemaApi.column('column_1').type('int');
    tableSchemaApi.column('column_2').drop();
}, { description: 'Renaming for testing purposes' });

database.dropTable():

Dynamically run a DROP TABLE operation.

database.dropTable(tableName: string, options?: Options): Promise<Savepoint>

⚙️ Spec:

• tableName (string): the table name.
• options (Options, optional): as described in query().
• Return value: a Savepoint instance.

⚽️ Usage:

const savepoint = await database.dropTable('table_1', { description: 'Dropping for testing purposes' });

Some additional parameters via options:

• ifExists (boolean, optional): a flag to conditionally drop the table.

  const savepoint = await database.dropTable('table_1', { ifExists: true, description: 'Dropping for testing purposes' });

• cascade (boolean, optional): a flag to force-drop the table along with its dependents.

  const savepoint = await database.dropTable('table_1', { cascade: true, description: 'Dropping for testing purposes' });

database.hasTable():

Check if a table exists.

database.hasTable(tableName: string): Promise<Boolean>

⚙️ Spec:

• tableName (string): the table name.
• Return value: Boolean.

⚽️ Usage:

const exists = await database.hasTable('table_1');

database.tables():

Get a list of available tables.

database.tables(): Promise<Array<string>>

⚙️ Spec:

• Return value: an array of table names.

⚽️ Usage:

const tables = await database.tables();
console.log(tables); // ['table_1', 'table_2', ...]

database.table():

Obtain a Table instance.

database.table(tableName: string): Table

⚙️ Spec:

• tableName (string): the table name.
• Return value: a Table instance.

⚽️ Usage:

const table = database.table('table_1');

database.savepoint():

Obtain the next available savepoint for given database.

database.savepoint(options?: { direction: string }): Savepoint

⚙️ Spec:

• options ({ direction: string }, optional): extra paramters for the method.
• Return value: a Savepoint instance.

⚽️ Usage:

const savepoint = await database.savepoint();
console.log(savepoint.versionTag); // number

await savepoint.rollback(); // true

Some additional parameters via options:

• direction (string, optional): the direction of lookup - either back in time: backward (the default), or forward in time: forward.

  const savepoint = await database.savepoint({ direction: 'forward' });
  console.log(savepoint.versionTag); // number
  
  await savepoint.rollback(); // true

database.schema():

Get the schema structure for a database. (From v0.12.0)

database.schema(tableList: string[] = ['*']): Promise<DatabaseSchemaAPI>

⚙️ Spec:

• tableList (string[] = ['*'], optional): an optional list of tables to include in the structure. Defaults to all tables.
• Return value: a DatabaseSchemaAPI instance; the requested schema.

⚽️ Usage:

const schema = await database.schema();
console.log(schema.name());
console.log(schema.tables());