Skip to main content

Kwil-JS Migration Guide

This document contains important information for migrating between Kwil-JS versions.

For migrations guides between earlier versions, please look for this document in the corresponding release tag.

If you have any questions on a migration, please reach out to [email protected].

Migrating from @kwilteam/[email protected] to @kwilteam/[email protected]​

Below is a list of all key changes from the @kwilteam/kwil-js v0.8 SDK to the v0.9

Note that kwil-js v0.9 must be used with kwil-db v0.10.0.

New Features​

Execute ad-hoc CREATE/INSERT/UPDATE/DELETE/ALTER SQL queries with kwil.execSql()​

New to kwil-db v0.10, database owners and wallets with relevant permissions can execute ad-hoc SQL queries. In kwil-js, this is done with the kwil.execSql() method.

Example:

await kwil.execSql(
    'INSERT INTO table (column1, column2) VALUES ($value1, $value2)', 
    { $value1: 'value1', $value2: 'value2' },
    kwilSigner, // signer 
    true // wait for transaction to be included in a block
);

Positional Arguments to kwil.call() and kwil.execute()​

You can now pass positional arguments to kwil.call() and kwil.execute() as a tuple. This can be used as an alternative to named parameters.

Example:

await kwil.call({
    namespace: 'some_namespace',
    action: 'action_name',
    inputs: [ 'first_param_val',  'second_param_val' ]
});

await kwil.execute({
    namespace: 'some_namespace',
    name: 'action_name',
    inputs: [
        // multiple sets of inputs will bulk execute the action
        [ 'first_param_val',  'second_param_val' ],
        [ 'first_param_val',  'second_param_val' ]
    ]
}, kwilSigner);

Breaking Changes​

The inputs field on Kwil.call() only takes a single input​

Previously, the inputs field on the ActionBody interface took an array of inputs. Now, the inputs field only takes a single input, and it is no longer an array.

Old Version​
await kwil.call({
    dbid: 'some_dbid',
    action: 'action_name',
    inputs: [ {$param1: 'some_param'} ]
});
New Version​
await kwil.call({
    namespace: 'some_namespace',
    action: 'action_name',
    inputs: {$param1: 'some_param'}
});

The dbid field on kwil.call() and kwil.execute() has been renamed to namespace​

Consistent with the change in kwil-db v0.10 to use namespace instead of dbid, the dbid field on the ActionBody interface has been renamed to namespace.

Old Version​
await kwil.execute({
    dbid: 'some_dbid',
    name: 'action_name',
    inputs: [ 'inputs' ]
}, kwilSigner);
New Version​
await kwil.execute({
    namespace: 'some_namespace',
    name: 'action_name',
    inputs: [ 'inputs' ]
}, kwilSigner);

The kwil.selectQuery() method signature has changed.​

The kwil.selectQuery() method signature has changed to take a a query string and parameters as arguments. Previously, it took a dbid and query string as arguments.

Old Version​
await kwil.selectQuery('some_dbid', 'SELECT * FROM table');
New Version​
await kwil.selectQuery('SELECT * FROM table WHERE id = $id', { $id: 1 });

Deprecations​

The kwil.getDBID() method is deprecated​

The kwil.getDBID() method has been deprecated, as Kwil v0.10 uses namespaces instead of dbids.

The kwil.getSchema() method is deprecated​

The kwil.getSchema() method has been deprecated. To retrieve schema information, query the info namespace with kwil.selectQuery(). Learn more about the info namespace here. For example:

await kwil.selectQuery('SELECT * FROM info.actions');

The kwil.deploy() method is deprecated​

The kwil.deploy() method is deprecated. Use kwil.execSql() to create namespaces, tables, actions, etc.

The kwil.drop() method is deprecated​

The kwil.drop() method is deprecated. Use kwil.execSql() to drop namespaces, tables, actions, etc.

The kwil.listDatabases() method is deprecated​

The kwil.listDatabases() method is deprecated. Use kwil.selectQuery() to query the info namespace for database information.

The ActionInput class is deprecated​

The ActionInput class is deprecated. Pass inputs to actions as an object instead.