influxdb3-go

README

InfluxDB 3 Go Client

The go package that provides an easy and convenient way to interact with InfluxDB 3. This package supports both writing data to InfluxDB and querying data using the FlightSQL client, which allows you to execute SQL queries against InfluxDB IOx.

Installation

Add the latest version of the client package to your project dependencies:

go get github.com/InfluxCommunity/influxdb3-go

Usage

Client can be instantiated using

• influxb3.ClientConfig
• environment variables
• connection string

Environment variables

Set environment variables:

• INFLUX_URL region of your influxdb cloud e.g. https://us-east-1-1.aws.cloud2.influxdata.com/
• INFLUX_TOKEN read/write token generated in cloud
• INFLUX_DATABASE name of database e.g .my-database

linux/macos

export INFLUX_URL="<url>"
export INFLUX_TOKEN="<token>"
export INFLUX_DATABASE="<database>"

windows

setx INFLUX_URL "<url>"
setx INFLUX_TOKEN "<token>"
setx INFLUX_DATABASE "<database>"

To get started with influxdb client import influxdb3-go package.

import (
  "context"
  "encoding/json"
  "fmt"
  "os"

  "github.com/InfluxCommunity/influxdb3-go/influxdb3"
)

Create influxdb3.Client with New function. Make sure to Close the client at the end.

// Create a new client using INFLUX_* environment variables
client, err := influxdb3.New()

// Close client at the end and escalate an error if occurs
defer func ()  {
    err := client.Close()
    if err != nil {
        panic(err)
    }
}()

Write data

The client can insert data using line-protocol:

line := "stat,location=Paris temperature=23.5,humidity=45i"
err = client.Write(context.Background(), []byte(line))

The client can also write points

p1 := influxdb3.Point{
    influxdb3.NewPoint("stat",
        map[string]string{
            "location": "Paris",
        },
        map[string]any{
            "temperature": 24.5,
            "humidity":    40,
        },
        time.Now(),
    ),
}
points := []*influxdb3.Point{p1}
err = client.WritePoints(context.Background(), points)

and/or annotated structs

s1 := struct {
    Measurement string    `lp:"measurement"`
    Sensor      string    `lp:"tag,location"`
    Temp        float64   `lp:"field,temperature"`
    Hum         int       `lp:"field,humidity"`
    Time        time.Time `lp:"timestamp"`
    Description string    `lp:"-"`
}{
    "stat",
    "Paris",
    23.5,
    55,
    time.Now(),
    "Paris weather conditions",
}
data := []any{s1}
err = client.WriteData(context.Background(), data)

Query

Use FlightSQL to query and print result.

query := `
    SELECT *
    FROM stat
    WHERE
        time >= now() - interval '5 minute'
        AND
        location IN ('Paris')
`

iterator, err := client.Query(context.Background(), query)
if err != nil {
    panic(err)
}

for iterator.Next() {
    value := iterator.Value()

    fmt.Printf("temperature in Paris is %f\n", value["temperature"])
    fmt.Printf("humidity in Paris is %d%%\n", value["humidity"])
}

Queries can be parameterized:

query := `
    SELECT *
    FROM stat
    WHERE
        time >= now() - interval '5 minute'
        AND
        location = $location
`
parameters := influxdb3.QueryParameters{
    "location": "Paris",
}

iterator, err := client.QueryWithParameters(context.Background(), query, parameters)

// process result

Examples

Prepare environment like in Usage and check 'examples' folder.

Feedback

If you need help, please use our Community Slack or Community Page.

New features and bugs can be reported on GitHub: https://github.com/InfluxCommunity/influxdb3-go

Contribution

If you would like to contribute code you can do through GitHub by forking the repository and sending a pull request into the main branch.

License

The InfluxDB 3 Go Client is released under the MIT License. which allows you to execute SQL queries on InfluxDB IOx.