@tableland/sdk

A D1Database client and helpers for the Tableland network

Table of Contents

• @tableland/sdk
• Table of Contents
• Background
• Usage
• Install
• Development
• Contributing
• License

Background

The @tableland/sdk library provides a minimal client and SDK that implements the D1Database interface on top of the Tableland network. It can be used as a drop-in replacement to work with many community-created D1 tools and libraries. It also comes with a set of helper utilities for working with Tableland.

Usage

See the API documentation for details.

import { Database } from "@tableland/sdk";
import { providers } from "ethers";

// A Web3Provider wraps a standard Web3 provider, which is
// what MetaMask injects as window.ethereum into each page
const provider = new providers.Web3Provider(window.ethereum);

// MetaMask requires requesting permission to connect users accounts
await provider.send("eth_requestAccounts", []);

// The MetaMask plugin also allows signing transactions to
// pay for gas when calling smart contracts like the @tableland
// registry...
const signer = provider.getSigner();
const db = new Database({ signer });

// Prepared statements allow users to reuse query logic by binding values
const stmt = db.prepare("SELECT name, age FROM users_80001_1 LIMIT ?").bind(3);
const { results } = await stmt.all();
console.log(results);
/*
[
  {
     name: "John",
     age: 42,
  },
   {
     name: "Anthony",
     age: 37,
  },
    {
     name: "Dave",
     age: 29,
  },
 ]
*/

Build Tools

The Tableland SDK uses an optimized WASM build of our SQL parser under the hood. Unfortunately, some build systems such as Vite require an adjustment to their configuration to support this feature. To temporarily work around this issue, simply add @tableland/sqlparser to the excluded list under optimizeDeps in your vite.config.ts file:

...
optimizeDeps: {
    exclude: [
      "@tableland/sqlparser"
    ]
  }
...

See our own Rigs project for an example of using this in production.

Full library documentation available on GitHub, and general docs, examples, and more available on our docs site.

Install

You can install via npm/yarn:

npm i @tableland/sdk
# yarn add @tableland/sdk

Or directly via GitHub:

npm i tablelandnetwork/js-tableland

Development

Get started by cloning, installing, building, and testing the project:

git clone git@github.com:tablelandnetwork/js-tableland.git
cd js-tableland
npm install
npm run build
npm test

To run tests in a few of the common browser environments we are using Playwright. Once your code changes are finished you can run the brower tests by doing:

• cd test/browser/server
• npm install
• cd ../../
• npm run test:browser

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT AND Apache-2.0, © 2021-2022 Tableland Network Contributors