questdb

package module
v1.0.5 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2023 License: Apache-2.0 Imports: 16 Imported by: 6

README

GoDoc reference

go-questdb-client

Golang client for QuestDB's Influx Line Protocol over TCP.

Features:

  • Context-aware API.
  • Optimized for batch writes.
  • Supports TLS encryption and ILP authentication.
  • Tested against QuestDB 6.4.1 and newer versions.

Documentation is available here.

Usage

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	qdb "github.com/questdb/go-questdb-client"
)

func main() {
	ctx := context.TODO()
	// Connect to QuestDB running on 127.0.0.1:9009
	sender, err := qdb.NewLineSender(ctx)
	if err != nil {
		log.Fatal(err)
	}
	// Make sure to close the sender on exit to release resources.
	defer sender.Close()
	// Send a few ILP messages.
	err = sender.
		Table("trades").
		Symbol("name", "test_ilp1").
		Float64Column("value", 12.4).
		AtNow(ctx)
	if err != nil {
		log.Fatal(err)
	}
	err = sender.
		Table("trades").
		Symbol("name", "test_ilp2").
		Float64Column("value", 11.4).
		At(ctx, time.Now().UnixNano())
	if err != nil {
		log.Fatal(err)
	}
	// Make sure that the messages are sent over the network.
	err = sender.Flush(ctx)
	if err != nil {
		log.Fatal(err)
	}
}

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidMsg = errors.New("invalid message")

ErrInvalidMsg indicates a failed attempt to construct an ILP message, e.g. duplicate calls to Table method or illegal chars found in table or column name.

Functions

This section is empty.

Types

type LineSender

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

LineSender allows you to insert rows into QuestDB by sending ILP messages.

Each sender corresponds to a single TCP connection. A sender should not be called concurrently by multiple goroutines.

func NewLineSender

func NewLineSender(ctx context.Context, opts ...LineSenderOption) (*LineSender, error)

NewLineSender creates new InfluxDB Line Protocol (ILP) sender. Each sender corresponds to a single TCP connection. Sender should not be called concurrently by multiple goroutines.

func (*LineSender) At

func (s *LineSender) At(ctx context.Context, ts int64) error

At sets the timestamp in Epoch nanoseconds and finalizes the ILP message. A negative ts value gets ignored making this call behave in the same way as AtNow.

If the underlying buffer reaches configured capacity, this method also sends the accumulated messages.

func (*LineSender) AtNow

func (s *LineSender) AtNow(ctx context.Context) error

AtNow omits the timestamp and finalizes the ILP message. The server will insert each message using the system clock as the row timestamp.

If the underlying buffer reaches configured capacity, this method also sends the accumulated messages.

func (*LineSender) BoolColumn

func (s *LineSender) BoolColumn(name string, val bool) *LineSender

BoolColumn adds a boolean column value to the ILP message.

Column name cannot contain any of the following characters: '\n', '\r', '?', '.', ',', ”', '"', '\', '/', ':', ')', '(', '+', '-', '*' '%%', '~', or a non-printable char.

func (*LineSender) Close

func (s *LineSender) Close() error

Close closes the underlying TCP connection. Does not flush in-flight messages, so make sure to call Flush first.

func (*LineSender) Float64Column

func (s *LineSender) Float64Column(name string, val float64) *LineSender

Float64Column adds a 64-bit float (double) column value to the ILP message.

Column name cannot contain any of the following characters: '\n', '\r', '?', '.', ',', ”', '"', '\', '/', ':', ')', '(', '+', '-', '*' '%%', '~', or a non-printable char.

func (*LineSender) Flush

func (s *LineSender) Flush(ctx context.Context) error

Flush flushes the accumulated messages to the underlying TCP connection. Should be called periodically to make sure that all messages are sent to the server.

For optimal performance, this method should not be called after each ILP message. Instead, the messages should be written in batches followed by a Flush call. Optimal batch size may vary from 100 to 1,000 messages depending on the message size and configured buffer capacity.

func (*LineSender) Int64Column

func (s *LineSender) Int64Column(name string, val int64) *LineSender

Int64Column adds a 64-bit integer (long) column value to the ILP message.

Column name cannot contain any of the following characters: '\n', '\r', '?', '.', ',', ”', '"', '\\', '/', ':', ')', '(', '+', '-', '*' '%%', '~', or a non-printable char.

func (*LineSender) Long256Column

func (s *LineSender) Long256Column(name string, val *big.Int) *LineSender

Long256Column adds a 256-bit unsigned integer (long256) column value to the ILP message.

Only non-negative numbers that fit into 256-bit unsigned integer are supported and any other input value would lead to an error.

Column name cannot contain any of the following characters: '\n', '\r', '?', '.', ',', ”', '"', '\\', '/', ':', ')', '(', '+', '-', '*' '%%', '~', or a non-printable char.

func (*LineSender) Messages

func (s *LineSender) Messages() string

Messages returns a copy of accumulated ILP messages that are not flushed to the TCP connection yet. Useful for debugging purposes.

func (*LineSender) StringColumn

func (s *LineSender) StringColumn(name, val string) *LineSender

StringColumn adds a string column value to the ILP message.

Column name cannot contain any of the following characters: '\n', '\r', '?', '.', ',', ”', '"', '\', '/', ':', ')', '(', '+', '-', '*' '%%', '~', or a non-printable char.

func (*LineSender) Symbol

func (s *LineSender) Symbol(name, val string) *LineSender

Symbol adds a symbol column value to the ILP message. Should be called before any Column method.

Symbol name cannot contain any of the following characters: '\n', '\r', '?', '.', ',', ”', '"', '\\', '/', ':', ')', '(', '+', '-', '*' '%%', '~', or a non-printable char.

func (*LineSender) Table

func (s *LineSender) Table(name string) *LineSender

Table sets the table name (metric) for a new ILP message. Should be called before any Symbol or Column method.

Table name cannot contain any of the following characters: '\n', '\r', '?', ',', ”', '"', '\', '/', ':', ')', '(', '+', '*', '%', '~', starting '.', trailing '.', or a non-printable char.

func (*LineSender) TimestampColumn

func (s *LineSender) TimestampColumn(name string, ts int64) *LineSender

TimestampColumn adds a timestamp column value to the ILP message. Timestamp is Epoch microseconds.

Negative timestamp value is not allowed and any attempt to set a negative value will cause an error to be returned on subsequent At() or AtNow() calls.

Column name cannot contain any of the following characters: '\n', '\r', '?', '.', ',', ”', '"', '\\', '/', ':', ')', '(', '+', '-', '*' '%%', '~', or a non-printable char.

type LineSenderOption

type LineSenderOption func(*LineSender)

LineSenderOption defines line sender option.

func WithAddress

func WithAddress(address string) LineSenderOption

WithAddress sets address to connect to. Should be in the "host:port" format. Defaults to "127.0.0.1:9009".

func WithAuth

func WithAuth(tokenId, token string) LineSenderOption

WithAuth sets token (private key) used for ILP authentication.

func WithBufferCapacity

func WithBufferCapacity(capacity int) LineSenderOption

WithBufferCapacity sets desired buffer capacity in bytes to be used when sending ILP messages. Defaults to 128KB.

This setting is a soft limit, i.e. the underlying buffer may grow larger than the provided value, but will shrink on a At, AtNow, or Flush call.

func WithFileNameLimit

func WithFileNameLimit(limit int) LineSenderOption

WithFileNameLimit sets maximum file name length in chars allowed by the server. Affects maximum table and column name lengths accepted by the sender. Should be set to the same value as on the server. Defaults to 127.

func WithTls

func WithTls() LineSenderOption

WithTls enables TLS connection encryption.

func WithTlsInsecureSkipVerify

func WithTlsInsecureSkipVerify() LineSenderOption

WithTls enables TLS connection encryption, but skips server certificate verification. Useful in test environments with self-signed certificates. Do not use in production environments.

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL