Client API

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

See content

• client.query()
• client.createDatabase()
• client.renameDatabase()
• client.alterDatabase()
• client.dropDatabase()
• client.hasDatabase()
• client.databases()
• client.database()
• client.schema()

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');