Client API

Client is the top-level interface in Linked QL. Each instance implements the following methods:

API	Description
client.query()	Run an arbitrary query.
client.createDatabase()	Programmatically perform a CREATE DATABASE operation.
client.renameDatabase()	Programmatically perform a RENAME DATABASE operation.
client.alterDatabase()	Programmatically perform an ALTER DATABASE operation.
client.dropDatabase()	Programmatically perform a DROP DATABASE operation.
client.hasDatabase()	Programmatically see if a database exists.
client.databases()	Get the list of databases.
client.database()	Obtain a Database instance.
client.schema()	Obtain the root schema instance.
client.listen()	Bind an event listener.
client.getPID()	Get your client connection ID.

Usage

Obtain the Linked QL client for your database as shown in the getting started guide.

client.query():

Run any SQL query.

client.query(sql: string, options?: Options): Promise<Savepoint | Array<object>>

⚙️ Spec:

• sql (string): an SQL query.
• options (Options, optional): extra parameters for the query.
• Return value: a Savepoint instance when it's a CREATE, ALTER, or DROP operation, an array (the result set) when it's a SELECT query or when it's an INSERT, UPDATE, or DELETE operation that has a RETURNING clause, but a number (indicating number of rows processed by the query) when not having a RETURNING clause. Null in all other cases.

⚽️ Usage:

Run a CREATE, ALTER, or DROP operation and get back a reference to the savepoint associated with it:

const savepoint = await client.query('ALTER TABLE users RENAME TO accounts');
console.log(savepoint.versionTag); // number

await savepoint.rollback(); // true

or a SELECT query, and get back a result set:

const rows = await client.query('SELECT * FROM users WHERE id = 4');
console.log(rows.length); // 1

or an INSERT, UPDATE, or DELETE operation with a RETURNING clause, and get back a result set:

const rows = await client.query('INSERT INTO users SET name = \'John Doe\' RETURNING id');
console.log(rows.length); // 1

or an INSERT, UPDATE, or DELETE operation without a RETURNING clause, and ge back a number indicating the number of rows processed by the query:

const rowCount = await client.query('INSERT INTO users SET name = \'John Doe\'');
console.log(rowCount); // 1

Some additional parameters via options:

• dialect (string, optional): the SQL dialect in use: postgres (the default) or mysql. (Details soon as to how this is treated by Linked QL.)

  // Unlock certain dialect-specific clauses or conventions
  const rows = await client.query('ALTER TABLE users MODIFY COLUMN id int', { dialect: 'mysql' });

• values ((string | number | boolean | null | Date | object | any[])[], optional): the values for parameters in the query.

  const rows = await client.query('SELECT * FROM users WHERE id = $1', { values: [4] });

• description (string, optional): the description for a CREATE, ALTER, DROP operation and for the underlying savepoint they create.

  const savepoint = await client.query('DROP DATABASE test', { description: 'No longer needed' });

• noCreateSavepoint (boolean, optional): a flag to disable savepoint creation on a CREATE, ALTER, DROP operation.

  await client.query('DROP DATABASE test', { noCreateSavepoint: true });

client.createDatabase():

Dynamically run a CREATE DATABASE operation.

client.createDatabase(databaseNameOrJson: string | DatabaseSchemaSpec, options?: Options): Promise<Savepoint>

⚙️ Spec:

• databaseNameOrJson (string | DatabaseSchemaSpec): the database name, or an object specifying the intended database structure to create.
• options (Options, optional): as described in query().
• Return value: a Savepoint instance.

⚽️ Usage:

Specify database by name:

const savepoint = await client.createDatabase('database_1', { description: 'Just testing database creation' });

or by a schema object, with an optional list of tables to be created along with it. (Each listed table corresponding to TableSchemaSpec (in schema.json).):

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

Some additional parameters via options:

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

  const savepoint = await client.createDatabase('database_1', { ifNotExists: true, description: 'Just testing database creation' });

client.alterDatabase():

Dynamically run an ALTER DATABASE operation.

client.alterDatabase(databaseNameOrJson: string | { name: string, tables?: string[] }, callback: (databaseSchemaApi: DatabaseSchemaAPI) => void, options?: Options): Promise<Savepoint>

⚙️ Spec:

• databaseNameOrJson (string | { name: string, tables?: string[] }): the database name, or an object with the name and, optionally, a list of tables to be altered along with it.
• callback ((databaseSchemaApi: DatabaseSchemaAPI) => void): a function that is called with the requested schema. This can be async.
• options (Options, optional): as described in query().
• Return value: a Savepoint instance.

⚽️ Usage:

Specify database by name:

const savepoint = await client.alterDatabase('database_1', databaseSchemaApi => {
    databaseSchemaApi.name('database_1_new');
}, { description: 'Renaming for testing purposes' });

or by an object, with an optional list of tables to be altered along with it:

const savepoint = await client.alterDatabase({ name: 'database_1', tables: ['table_1'] }, databaseSchemaApi => {
    databaseSchemaApi.name('database_1_new');
    databaseSchemaApi.table('table_1').column('column_1').name('column_1_new');
    databaseSchemaApi.table('table_1').column('column_2').type('varchar');
}, { description: 'Renaming for testing purposes' });

client.dropDatabase():

Dynamically run a DROP DATABASE operation.

client.dropDatabase(databaseName: string, options?: Options): Promise<Savepoint>

⚙️ Spec:

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

⚽️ Usage:

const savepoint = await client.dropDatabase('database_1', { description: 'Dropping for testing purposes' });

Some additional parameters via options:

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

  const savepoint = await client.dropDatabase('database_1', { ifExists: true, description: 'Dropping for testing purposes' });

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

  const savepoint = await client.dropDatabase('database_1', { cascade: true, description: 'Dropping for testing purposes' });

client.hasDatabase():

Check if a database exists.

client.hasDatabase(databaseName: string): Promise<Boolean>

⚙️ Spec:

• databaseName (string): the database name.
• Return value: Boolean.

⚽️ Usage:

const exists = await client.hasDatabase('database_1');

client.databases():

Get a list of available databases.

client.databases(): Promise<Array<string>>

⚙️ Spec:

• Return value: an array of database names.

⚽️ Usage:

const databases = await client.databases();
console.log(databases); // ['public', 'database_1', ...]

client.database():

Obtain a Database instance.

client.database(databaseName: string): Database

⚙️ Spec:

• databaseName (string): the database name.
• Return value: a Database instance.

⚽️ Usage:

const database = client.database('database_1');