v1

README

Tableland Client

Tableland Client is a convenient wrapper around validator's HTTP APIs. Here is the list of public APIs.

APIs

• Create
• Write
• Version
• GetTable
• Receipt
• Read
• Validate
• Hash
• CheckHealth

Usage

Following are few example usage of these APIs.

First, we instantiate the client:

import (

// ...
// ...

  clientV1 "github.com/textileio/go-tableland/pkg/client/v1"
  "github.com/textileio/go-tableland/pkg/wallet"
)

// create the wallet from the given private key
wallet, _ := wallet.NewWallet("PRIVATE_KEY")
ctx := context.Background()

// create the new client
client, _ := clientV1.NewClient(
    ctx, wallet, clientV1.[]NewClientOption{}...)

Checkout the available client options here.

Create

Create a new table with the schema and options. Schema should be a valid SQL DDL as a string.

tableID, fullTableName := client.Create(
    ctx, "(id int, name text)",
    clientV1.WithPrefix("foo"))

Write

Write will execute an mutation query, returning the txn hash. Additional options can be passed in.

  // Create a new table
  tableID, fullTableName := client.Create(
    ctx, "(id int, name text)",
    clientV1.WithPrefix("foo"))

  // Update the table
  query := fmt.Sprintf(
    "update %s set name = alice where id = 1", fullTableName)
  hash := client.Write(ctx, query)

  // Alter table to rename a column
  query := fmt.Sprintf(
    "alter table %s rename name to username", fullTableName)
  hash := client.Write(ctx, query)

Receipt

Receipt will get the transaction receipt given the transaction hash. Additional configuration is possible with options.

    txHash := "0xabcd"
    receipt, ok, err := client.Receipt(
      ctx, txnHash, clientV1.WaitFor(cp.receiptTimeout))

Read

Read runs a read SQL query with the provided options.

    // Create a new table: `myTable`
    client.Create(ctx, "(counter int)", clientV1.WithPrefix("myTable"))

    // Insert a row in `myTable`
    client.write(ctx, "insert into myTable (counter) values(42)")

    // Read it into the `target` struct
    result := map[string]interface{}{}
    client.Read(
        ctx, "select counter from myTable",
        result, clientV1.ReadExtract())

GetTable

The GetTable API will return the Table struct given the table id.

    // create a new table 
    tableID, fullTableName := client.Create(
        ctx, "(bar text DEFAULT 'foo',zar int, CHECK (zar>0))",
	    WithPrefix("foo"), WithReceiptTimeout(time.Second*10))
	
    // get the table using tableID
    table, err := client.GetTable(ctx, tableID)

Documentation

Index

• Variables
• type Client
  • func NewClient(ctx context.Context, wallet *wallet.Wallet, opts ...NewClientOption) (*Client, error)
  • func (c *Client) CheckHealth(ctx context.Context) (bool, error)
  • func (c *Client) Create(ctx context.Context, schema string, opts ...CreateOption) (TableID, string, error)
  • func (c *Client) GetTable(ctx context.Context, tableID TableID) (*apiv1.Table, error)
  • func (c *Client) Hash(statement string) (string, error)
  • func (c *Client) Read(ctx context.Context, query string, queryParams []string, target interface{}, ...) error
  • func (c *Client) Receipt(ctx context.Context, txnHash string, options ...ReceiptOption) (*apiv1.TransactionReceipt, bool, error)
  • func (c *Client) Validate(statement string) (TableID, error)
  • func (c *Client) Version(ctx context.Context) (*apiv1.VersionInfo, error)
  • func (c *Client) Write(ctx context.Context, query string, opts ...WriteOption) (string, error)
• type CreateOption
  • func WithPrefix(prefix string) CreateOption
  • func WithReceiptTimeout(timeout time.Duration) CreateOption
• type NewClientOption
  • func NewClientAlchemyAPIKey(key string) NewClientOption
  • func NewClientAnkrAPIKey(key string) NewClientOption
  • func NewClientChain(chain client.Chain) NewClientOption
  • func NewClientContractBackend(backend bind.ContractBackend) NewClientOption
  • func NewClientGlifAPIKey(key string) NewClientOption
  • func NewClientInfuraAPIKey(key string) NewClientOption
  • func NewClientLocal() NewClientOption
• type Output
• type ReadOption
  • func ReadExtract() ReadOption
  • func ReadFormat(output Output) ReadOption
  • func ReadUnwrap() ReadOption
• type ReceiptOption
  • func WaitFor(timeout time.Duration) ReceiptOption
• type TableID
  • func NewTableID(strID string) (TableID, error)
  • func (tid TableID) String() string
  • func (tid TableID) ToBigInt() *big.Int
• type WriteConfig
• type WriteOption
  • func WithEstimatedGasLimitMultiplier(m float64) WriteOption
  • func WithSuggestedPriceMultiplier(m float64) WriteOption

Variables

var ErrTableNotFound = errors.New("table not found")

ErrTableNotFound is returned if the provided table ID isn't found in the network.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the Tableland client.

func NewClient

func NewClient(ctx context.Context, wallet *wallet.Wallet, opts ...NewClientOption) (*Client, error)

NewClient creates a new Client.

func (*Client) CheckHealth

func (c *Client) CheckHealth(ctx context.Context) (bool, error)

CheckHealth returns true if the targeted validator endpoint is considered healthy, and false otherwise.

func (*Client) Create

func (c *Client) Create(ctx context.Context, schema string, opts ...CreateOption) (TableID, string, error)

Create creates a new table on the Tableland.

func (*Client) GetTable

func (c *Client) GetTable(ctx context.Context, tableID TableID) (*apiv1.Table, error)

GetTable returns the table information given its ID. If the table ID doesn't exist, it returns ErrTableNotFound.

func (*Client) Hash

func (c *Client) Hash(statement string) (string, error)

Hash validates the provided create table statement and returns its hash.

func (*Client) Read

func (c *Client) Read(
	ctx context.Context, query string, queryParams []string, target interface{}, opts ...ReadOption,
) error

Read runs a read query with the provided opts and unmarshals the results into target.

func (*Client) Receipt

func (c *Client) Receipt(
	ctx context.Context,
	txnHash string,
	options ...ReceiptOption,
) (*apiv1.TransactionReceipt, bool, error)

Receipt gets a transaction receipt.

func (*Client) Validate

func (c *Client) Validate(statement string) (TableID, error)

Validate validates a write query, returning the table id.

func (*Client) Version

func (c *Client) Version(ctx context.Context) (*apiv1.VersionInfo, error)

Version returns the validator version information.

func (*Client) Write

func (c *Client) Write(ctx context.Context, query string, opts ...WriteOption) (string, error)

Write initiates a write query, returning the txn hash.

type CreateOption

type CreateOption func(*createConfig)

CreateOption controls the behavior of Create.

func WithPrefix

func WithPrefix(prefix string) CreateOption

WithPrefix allows you to specify an optional table name prefix where the final table name will be <prefix>_<chain-id>_<tableid>.

func WithReceiptTimeout

func WithReceiptTimeout(timeout time.Duration) CreateOption

WithReceiptTimeout specifies how long to wait for the Tableland receipt that contains the table id.

type NewClientOption

type NewClientOption func(*config)

NewClientOption controls the behavior of NewClient.

func NewClientAlchemyAPIKey

func NewClientAlchemyAPIKey(key string) NewClientOption

NewClientAlchemyAPIKey specifies an Alchemy API to use when creating an EVM backend.

func NewClientAnkrAPIKey

func NewClientAnkrAPIKey(key string) NewClientOption

NewClientAnkrAPIKey specifies an Ankr API to use when creating an EVM backend.

func NewClientChain

func NewClientChain(chain client.Chain) NewClientOption

NewClientChain specifies chaininfo.

func NewClientContractBackend

func NewClientContractBackend(backend bind.ContractBackend) NewClientOption

NewClientContractBackend specifies a custom EVM backend to use.

func NewClientGlifAPIKey

func NewClientGlifAPIKey(key string) NewClientOption

NewClientGlifAPIKey specifies a Glif API to use when creating an EVM backend.

func NewClientInfuraAPIKey

func NewClientInfuraAPIKey(key string) NewClientOption

NewClientInfuraAPIKey specifies an Infura API to use when creating an EVM backend.

func NewClientLocal

func NewClientLocal() NewClientOption

NewClientLocal specifies that a local EVM backend should be used.

type Output

type Output string

Output is used to control the output format of a Read using the ReadOutput option.

const (
	// Table returns the query results as a JSON object with columns and rows properties.
	Table Output = "table"
	// Objects returns the query results as a JSON array of JSON objects. This is the default.
	Objects Output = "objects"
)

type ReadOption

type ReadOption func(*readQueryParameters)

ReadOption controls the behavior of Read.

func ReadExtract

func ReadExtract() ReadOption

ReadExtract specifies whether or not to extract the JSON object from the single property of the surrounding JSON object. Default is false.

func ReadFormat

func ReadFormat(output Output) ReadOption

ReadFormat sets the output format. Default is Objects.

func ReadUnwrap

func ReadUnwrap() ReadOption

ReadUnwrap specifies whether or not to unwrap the returned JSON objects from their surrounding array. Default is false.

type ReceiptOption

type ReceiptOption func(*receiptConfig)

ReceiptOption controls the behavior of calls to Receipt.

func WaitFor

func WaitFor(timeout time.Duration) ReceiptOption

WaitFor causes calls to Receipt to wait for the specified duration.

type TableID

type TableID big.Int

TableID is the ID of a Table.

func NewTableID

func NewTableID(strID string) (TableID, error)

NewTableID creates a TableID from a string representation of the uint256.

func (TableID) String

func (tid TableID) String() string

String returns a string representation of the TableID.

func (TableID) ToBigInt

func (tid TableID) ToBigInt() *big.Int

ToBigInt returns a *big.Int representation of the TableID.

type WriteConfig

type WriteConfig struct {
	// contains filtered or unexported fields
}

WriteConfig contains configuration attributes to call Write.

type WriteOption

type WriteOption func(*WriteConfig) error

WriteOption changes the behavior of the Write method.

func WithEstimatedGasLimitMultiplier

func WithEstimatedGasLimitMultiplier(m float64) WriteOption

WithEstimatedGasLimitMultiplier allows to modify the gas limit to be used with respect with the estimated gas. For example, if `m=1.2` then the gas limit to be used will be `estimatedGas * 1.2`.

func WithSuggestedPriceMultiplier

func WithSuggestedPriceMultiplier(m float64) WriteOption

WithSuggestedPriceMultiplier allows to modify the gas priced to be used with respect with the suggested gas price. For example, if `m=1.2` then the gas price to be used will be `suggestedGasPrice * 1.2`.