client

Documentation

Overview

Package client is a golang sql driver implementation to interact with SQLess.

Index

• Constants
• Variables
• func Create(meta ResourceMeta) (txHash hash.Hash, dsn string, err error)
• func Drop(dsn string) (txHash hash.Hash, err error)
• func ExecuteInTx(tx driver.Tx, fn func() error) (err error)
• func ExecuteTx(ctx context.Context, db *sql.DB, txopts *sql.TxOptions, fn func(*sql.Tx) error) error
• func GetTokenBalance(tt types.TokenType) (balance uint64, err error)
• func Init(configFile string, masterKey []byte) (err error)
• func TransferToken(targetUser proto.AccountAddress, amount uint64, tokenType types.TokenType) (txHash hash.Hash, err error)
• func UpdatePermission(targetUser proto.AccountAddress, targetChain proto.AccountAddress, ...) (txHash hash.Hash, err error)
• func WaitBPDatabaseCreation(ctx context.Context, dbID proto.DatabaseID, db *sql.DB, period time.Duration) (err error)
• func WaitDBCreation(ctx context.Context, dsn string) (err error)
• func WaitTxConfirmation(ctx context.Context, txHash hash.Hash) (state interfaces.TransactionState, err error)
• func WithReceipt(ctx context.Context) context.Context
• type Config
  • func NewConfig() *Config
  • func ParseDSN(dsn string) (cfg *Config, err error)
  • func (cfg *Config) FormatDSN() string
• type Receipt
  • func GetReceipt(ctx context.Context) (rec *Receipt, ok bool)
• type ResourceMeta

Constants

const (
	// DBScheme defines the dsn scheme.
	DBScheme = "cqlprotocol"
	// DBSchemeAlias defines the alias dsn scheme.
	DBSchemeAlias = "cql"
	// DefaultGasPrice defines the default gas price for new created database.
	DefaultGasPrice = 1
	// DefaultAdvancePayment defines the default advance payment for new created database.
	DefaultAdvancePayment = 20000000
)

Variables

var (
	// PeersUpdateInterval defines peers list refresh interval for client.
	PeersUpdateInterval = time.Second * 5

	// DefaultConfigFile is the default path of config file
	DefaultConfigFile = "~/.cql/config.yaml"
)

var (
	// ErrQueryInTransaction represents a read query is presented during user transaction.
	ErrQueryInTransaction = errors.New("only write is supported during transaction")
	// ErrNotInitialized represents the driver is not initialized yet.
	ErrNotInitialized = errors.New("driver not initialized")
	// ErrAlreadyInitialized represents the driver is already initialized.
	ErrAlreadyInitialized = errors.New("driver already initialized")
	// ErrInvalidRequestSeq defines invalid sequence no of request.
	ErrInvalidRequestSeq = errors.New("invalid request sequence applied")
	// ErrInvalidProfile indicates the SQLChain profile is invalid.
	ErrInvalidProfile = errors.New("invalid sqlchain profile")
	// ErrNoSuchTokenBalance indicates no such token balance in chain.
	ErrNoSuchTokenBalance = errors.New("no such token balance")
)

Various errors the driver might returns.

Functions

func Create

func Create(meta ResourceMeta) (txHash hash.Hash, dsn string, err error)

Create sends create database operation to block producer.

func Drop

func Drop(dsn string) (txHash hash.Hash, err error)

Drop sends drop database operation to block producer.

func ExecuteInTx

func ExecuteInTx(tx driver.Tx, fn func() error) (err error)

ExecuteInTx runs fn inside tx which should already have begun.

func ExecuteTx

func ExecuteTx(
	ctx context.Context, db *sql.DB, txopts *sql.TxOptions, fn func(*sql.Tx) error,
) error

ExecuteTx starts a transaction, and runs fn in it.

func GetTokenBalance

func GetTokenBalance(tt types.TokenType) (balance uint64, err error)

GetTokenBalance get the token balance of current account.

func Init

func Init(configFile string, masterKey []byte) (err error)

Init defines init process for client.

func TransferToken

func TransferToken(targetUser proto.AccountAddress, amount uint64, tokenType types.TokenType) (
	txHash hash.Hash, err error,
)

TransferToken send Transfer transaction to chain.

func UpdatePermission

func UpdatePermission(targetUser proto.AccountAddress,
	targetChain proto.AccountAddress, perm *types.UserPermission) (txHash hash.Hash, err error)

UpdatePermission sends UpdatePermission transaction to chain.

func WaitBPDatabaseCreation

func WaitBPDatabaseCreation(
	ctx context.Context,
	dbID proto.DatabaseID,
	db *sql.DB,
	period time.Duration,
) (err error)

WaitBPDatabaseCreation waits for database creation complete.

func WaitDBCreation

func WaitDBCreation(ctx context.Context, dsn string) (err error)

WaitDBCreation waits for database creation complete.

func WaitTxConfirmation

func WaitTxConfirmation(
	ctx context.Context, txHash hash.Hash) (state interfaces.TransactionState, err error,
)

WaitTxConfirmation waits for the transaction with target hash txHash to be confirmed. It also returns if any error occurs or a final state is returned from BP.

func WithReceipt

func WithReceipt(ctx context.Context) context.Context

WithReceipt returns a context who holds a *atomic.Value. A *Receipt will be set to this value after the query succeeds.

Note that this context is safe for concurrent queries, but the value may be reset in another goroutines. So if you want to make use of Receipt in several goroutines, you should call this method to get separated child context in each goroutine.

Types

type Config

type Config struct {
	DatabaseID string

	// UseLeader use leader nodes to do queries
	UseLeader bool

	// UseFollower use follower nodes to do queries
	UseFollower bool

	// UseDirectRPC use direct RPC to access the miner
	UseDirectRPC bool
}

Config is a configuration parsed from a DSN string.

func NewConfig

func NewConfig() *Config

NewConfig creates a new config with default value.

func ParseDSN

func ParseDSN(dsn string) (cfg *Config, err error)

ParseDSN parse the DSN string to a Config.

func (*Config) FormatDSN

func (cfg *Config) FormatDSN() string

FormatDSN formats the given Config into a DSN string which can be passed to the driver.

type Receipt

type Receipt struct {
	RequestHash hash.Hash
}

Receipt defines a receipt of SQLess query request.

func GetReceipt

func GetReceipt(ctx context.Context) (rec *Receipt, ok bool)

GetReceipt tries to get *Receipt from context.

type ResourceMeta

type ResourceMeta struct {
	// copied fields from types.ResourceMeta
	TargetMiners           []proto.AccountAddress `json:"target-miners,omitempty"`        // designated miners
	Node                   uint16                 `json:"node,omitempty"`                 // reserved node count
	Space                  uint64                 `json:"space,omitempty"`                // reserved storage space in bytes
	Memory                 uint64                 `json:"memory,omitempty"`               // reserved memory in bytes
	LoadAvgPerCPU          float64                `json:"load-avg-per-cpu,omitempty"`     // max loadAvg15 per CPU
	EncryptionKey          string                 `json:"encrypt-key,omitempty"`          // encryption key for database instance
	UseEventualConsistency bool                   `json:"eventual-consistency,omitempty"` // use eventual consistency replication if enabled
	ConsistencyLevel       float64                `json:"consistency-level,omitempty"`    // customized strong consistency level
	IsolationLevel         int                    `json:"isolation-level,omitempty"`      // customized isolation level

	GasPrice       uint64 `json:"gas-price"`       // customized gas price
	AdvancePayment uint64 `json:"advance-payment"` // customized advance payment
}

ResourceMeta defines new database resources requirement descriptions.