questdb

README

questdb-go

The QuestDB Go library for reading/writing data from/to QuestDB. Refer to Go documentation above.

Documentation

Index

• Variables
• func IsSerializableType(v interface{}) bool
• func ScanInto(row *sql.Row, dest interface{}) (err error)
• func ScanRows(rows *sql.Rows, dest interface{}) (err error)
• func WithTableName(tableName string) option
• type Bytes
  • func (b Bytes) QDBValue() (Value, error)
  • func (b *Bytes) Scan(src interface{}) error
  • func (b Bytes) Value() (driver.Value, error)
• type Client
  • func Default() *Client
  • func New(config Config) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Connect() error
  • func (c *Client) CreateTableIfNotExists(v interface{}, options ...option) error
  • func (c *Client) DB() *sql.DB
  • func (c *Client) Write(a interface{}, options ...option) error
  • func (c *Client) WriteBatch(rows []interface{}, options ...option) error
  • func (c *Client) WriteMessage(message []byte) error
• type Config
• type CreateTableOptioner
• type CreateTableOptions
  • func (c *CreateTableOptions) String() string
• type Model
  • func NewModel(a interface{}) (*Model, error)
  • func (m *Model) Columns() string
  • func (m *Model) CreateTableIfNotExistStatement() string
  • func (m *Model) MarshalLine() (msg []byte)
• type PartitionOption
• type QBDValuer
• type QuestDBType
• type Scanner
• type TableNamer
• type Value

Variables

var (
	ErrILPNetDial           = errors.New("could not dial ilp host")
	ErrILPTLSDial           = errors.New("could not dial tls host")
	ErrILPNetTCPAddrResolve = errors.New("could not resolve ilp host address")
	ErrPGOpen               = errors.New("could not open postgres db")
)

Functions

func IsSerializableType

func IsSerializableType(v interface{}) bool

isSerializableType takes a v interface{} and returns a bool which represents whether or not v can be serialized into Influx line protocol message value.

func ScanInto

func ScanInto(row *sql.Row, dest interface{}) (err error)

ScanInto func is a helper function which takes a *sql.Row and a dest (an valid qdb model struct) and scans the row values into dest. This will typically be used in conjunction with a select statement which has used (Model).Columns() to specify the columns for selecting.

func ScanRows

func ScanRows(rows *sql.Rows, dest interface{}) (err error)

ScanInto func is a helper function which takes a *sql.Row and a dest (an valid qdb model struct) and scans the row values into dest. This will typically be used in conjunction with a select statement which has used (Model).Columns() to specify the columns for selecting.

func WithTableName

func WithTableName(tableName string) option

WithTableName func should allow you to set a model's table name for different client operations

Types

type Bytes

type Bytes []byte

Bytes is an alias for []byte. It is used to provide a []byte type that can serialized into questdb Value by implementing the QDBValuer interface.

As it stands, QuestDB cannot ingest BYTEA type via Postgres Wire Protocol nor can byte slice(s) be serialized into an Influx Line Protocol message. The current work around is to convert byte slice(s) to a base64 encoded string and save that to QuestDB. Once QuestDB supports byte slice(s) natively via Influx Line Protocol or Postgres Wire protocol, this type will just act as an alias to []byte type and the base64 encoding behaviour will be removed.

func (Bytes) QDBValue

func (b Bytes) QDBValue() (Value, error)

Value func implements the QDBValuer interface

func (*Bytes) Scan

func (b *Bytes) Scan(src interface{}) error

Scan func implements the sql.Scanner interface

func (Bytes) Value

func (b Bytes) Value() (driver.Value, error)

Value func implements the driver.Valuer interface

type Client

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

Client struct represents a QuestDB client connection. This encompasses the InfluxDB Line protocol net.TCPConn as well as the Postgres wire *sql.DB connection. Methods on this client are primarily used to read/write data to QuestDB.

func Default

func Default() *Client

Default func returns a *Client with the default config as specified by QuestDB docs

func New

func New(config Config) (*Client, error)

New func returns a *Client and an optional error given a Config

func (*Client) Close

func (c *Client) Close() error

Close func closes both the Influx line protocol TCP connection as well as the PG sql database connection

func (*Client) Connect

func (c *Client) Connect() error

Connect func dials and connects both the Influx line protocol TCP connection as well as the underlying sql PG database connection.

func (*Client) CreateTableIfNotExists

func (c *Client) CreateTableIfNotExists(v interface{}, options ...option) error

CreateTableIfNotExists func takes a valid 'qdb' tagged struct v and attempts to create the table (via the PG wire) in QuestDB and returns an possible error. You can optionally pass a custom table name.

func (*Client) DB

func (c *Client) DB() *sql.DB

DB func returns the underlying *sql.DB struct for DB operations over the Postgres wire protocol

func (*Client) Write

func (c *Client) Write(a interface{}, options ...option) error

Write takes a valid struct with qdb tags and writes it to the underlying InfluxDB line protocol

func (*Client) WriteBatch

func (c *Client) WriteBatch(rows []interface{}, options ...option) error

func (*Client) WriteMessage

func (c *Client) WriteMessage(message []byte) error

WriteMessage func takes a message and writes it to the underlying InfluxDB line protocol

type Config

type Config struct {
	ILPHost           string
	ILPAuthPrivateKey string
	ILPAuthKid        string
	PGConnStr         string
	TLSConfig         *tls.Config
}

Config is a struct which holds Client's config fields

type CreateTableOptioner

type CreateTableOptioner interface {
	CreateTableOptions() CreateTableOptions
}

CreateTableOptioner is an interface which has a single method CreateTableOptions which returns the CreateTableOptions struct. This is used when specifying specific options for creating a table in QuestDB world.

type CreateTableOptions

type CreateTableOptions struct {
	PartitionBy PartitionOption
	// Deprecated: QuestDB >= v7.0.0 no longer requires this option
	MaxUncommittedRows int
	// Deprecated: QuestDB >= v7.0.0 no longer requires this option
	CommitLag string
}

CreateTableOptions struct is a struct which specifies options for creating a QuestDB table

func (*CreateTableOptions) String

func (c *CreateTableOptions) String() string

String func prints out the CreateTableOptions in string format which would be appended to the sql create table statement

type Model

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

Model represents a struct's model

func NewModel

func NewModel(a interface{}) (*Model, error)

NewModel func takes a struct and returns the Model representation of that struct or an optional error

func (*Model) Columns

func (m *Model) Columns() string

Columns func will take return all the model's fields in column format i.e. "column_1, column_2, column_3, ..."

func (*Model) CreateTableIfNotExistStatement

func (m *Model) CreateTableIfNotExistStatement() string

CreateTableIfNotExistStatement func returns the sql create table statement for the Model

func (*Model) MarshalLine

func (m *Model) MarshalLine() (msg []byte)

MarshalLine func marshals Model's underlying struct values into Influx Line Protocol message serialization format to be written to the QuestDB ILP port for ingestion.

type PartitionOption

type PartitionOption string

PartitionOption is a string which is used in CreateTableOptions struct for specifying the partition by strategy

const (
	None  PartitionOption = "NONE"
	Year  PartitionOption = "YEAR"
	Month PartitionOption = "MONTH"
	Day   PartitionOption = "DAY"
	Hour  PartitionOption = "HOUR"
)

type QBDValuer

type QBDValuer interface {
	// QDBValue returns a questdb Value.
	// QDBValue must not panic.
	QDBValue() Value
}

QBDValuer is the interface providing the QDBValue method.

Types implementing QBDValuer interface are able to convert themselves to a questdb Value.

type QuestDBType

type QuestDBType string

QuestDBType is string which represents a type in the QuestDb world

var (
	// boolean (true or false)
	Boolean QuestDBType = "boolean"
	// 8 bit signed integer (-128 to 127)
	Byte QuestDBType = "byte"
	// 16-bit signed integer (-32768 to 32767)
	Short QuestDBType = "short"
	// 16-bit unicode character
	Char QuestDBType = "char"
	// 32-bit signed integer (0x80000000 to 0x7fffffff)
	Int QuestDBType = "int"
	// 32-bit float (float32 - single precision IEEE 754)
	Float QuestDBType = "float"
	// variable length string (see QuestDB docs)
	Symbol QuestDBType = "symbol"
	// variable length string
	String QuestDBType = "string"
	// variable length JSON string
	JSON QuestDBType = "json"
	// type that implements EncoderDecoder interface
	Encoded QuestDBType = "encoded"
	// 64-bit signed integer (0x8000000000000000L to 0x7fffffffffffffffL)
	Long QuestDBType = "long"
	// 64-bit signed offset in milliseconds from Unix Epoch
	Date QuestDBType = "date"
	// 64-bit signed offset in microseconds from Unix Epoch
	Timestamp QuestDBType = "timestamp"
	// 64-bit float (float64 - double precision IEEE 754)
	Double QuestDBType = "double"
	// byte array
	Binary QuestDBType = "binary"
	// hyphenated uuid string
	UUID QuestDBType = "uuid"
	// 256-bit unsigned integer
	//		unsupported
	Long256 QuestDBType = "long256"
	// Geohash
	// 		unsupported
	Geohash QuestDBType = "geohash"
)

type Scanner

type Scanner interface {
	QDBScan(src interface{}) error
}

Scanner interface has one method QDBScan which scans a value from QuestDB into the type implementing Scanner

type TableNamer

type TableNamer interface {
	TableName() string
}

TableNamer is an interface which has a single method, TableName, which returns a string representing the struct's table name in QuestDB.

type Value

type Value interface{}

SerializableValue is a value that is one of the following types:

int
uint
int16
uint16
int32
uint32
int64
float64
float32
bool
string
time.Time
Bytes