Skip to content

Latest commit

 

History

History
150 lines (101 loc) · 4.44 KB

MIGRATING.md

File metadata and controls

150 lines (101 loc) · 4.44 KB

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 luke@kwil.com.

Migrating from @trufnetwork/kwil-js@0.8 to @trufnetwork/kwil-js@0.9

Below is a list of all key changes from the @trufnetwork/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.