v1

package
v1.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 22, 2023 License: MIT, Apache-2.0 Imports: 21 Imported by: 0

README

Tableland Client

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

APIs

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

Constants

This section is empty.

Variables

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

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

Functions

This section is empty.

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, 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 added in v1.2.0 

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 added in v1.6.0 

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 added in v1.0.1 

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

WriteConfig contains configuration attributes to call Write.

type WriteOption added in v1.0.1 

type WriteOption func(*WriteConfig) error

WriteOption changes the behavior of the Write method.

func WithEstimatedGasLimitMultiplier added in v1.0.1 

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 added in v1.0.1 

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`.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.