InfluxDB Client Go

If you are using InfluxDB 1.8.0 or later, you can use this client to interact with it via the InfluxDB 2.0 API endpoints. When using this compatibility mode, follow these mapping rules for parameters:

1. Authentication Token: Use the format username:password. If the server does not require authentication, use an empty string ("").
2. Organization: The organization parameter is not used in 1.8. Use an empty string ("") where an organization is required.
3. Bucket: Use the format database/retention-policy. To use the default retention policy, provide only the database name (e.g., telegraf).

Available compatible APIs:

• WriteAPI / WriteAPIBlocking: Writes data to /api/v2/write.
• QueryAPI: Queries data via /api/v2/query (requires the flux-enabled option to be enabled on the InfluxDB server).
• Health(): Checks instance health via /health.

// Example of compatibility mapping:
// Token: "my-user:my-password"
// Org: ""
// Bucket: "telegraf/autogen"
client := influxdb2.NewClient("http://localhost:8086", "my-user:my-password")
writeAPI := client.WriteAPIBlocking("", "telegraf/autogen")

The non-blocking WriteAPI is recommended for frequent, periodic writes. It uses implicit batching to improve performance.

Key Behaviors:

• Batching: Data is buffered and sent when the BatchSize (default 5000) is reached or the flush interval (default 1s) expires.
• Retries: Automatically retries on connection failures or HTTP status codes $\ge$ 429. It uses a random exponential backoff strategy.
• Flushing: Use writeAPI.Flush() to ensure all pending writes are sent before closing.
• Cleanup: Always call client.Close() to stop background processes.

Configuring Batch Size:

client := influxdb2.NewClientWithOptions("http://localhost:8086", "my-token",
    influxdb2.DefaultOptions().SetBatchSize(20))
writeAPI := client.WriteAPI("my-org", "my-bucket")

package main

import (
    "fmt"
    "math/rand"
    "time"

    "github.com/influxdata/influxdb-client-go/v2"
)

func main() {
    client := influxdb2.NewClientWithOptions("http://localhost:8086", "my-token",
        influxdb2.DefaultOptions().SetBatchSize(20))
    writeAPI := client.WriteAPI("my-org","my-bucket")

    for i := 0; i < 100; i++ {
        p := influxdb2.NewPoint(
            "system",
            map[string]string{
                "id":       fmt.Sprintf("rack_%v", i%10),
                "vendor":   "AWS",
                "hostname": fmt.Sprintf("host_%v", i%100),
            },
            map[string]interface{}{
                "temperature": rand.Float64() * 80.0,
                "disk_free":   rand.Float64() * 1000.0,
                "disk_total":  (i/10 + 1) * 1000000,
                "mem_total":   (i/100 + 1) * 10000000,
                "mem_free":    rand.Uint64(),
            },
            time.Now())
        writeAPI.WritePoint(p)
    }
    writeAPI.Flush()
    client.Close()
}

The InfluxDB Go Client is thread-safe and designed for concurrent environments.

Best Practices:

• Single Client Instance: Use a single Client instance per server URL to optimize resource usage and reuse HTTP connections.
• Sub-client Reuse: The client ensures a single instance of each API sub-client (e.g., one WriteAPI per org/bucket pair, one QueryAPI per org). These sub-clients can be used concurrently.
• Custom HTTP Client: For efficient resource reuse across multiple client instances, create a single http.Client and pass it to all clients using Options.SetHTTPClient().

// Create a shared HTTP client
httpClient := &http.Client{
    Transport: &http.Transport{
        MaxIdleConns: 100,
        MaxIdleConnsPerHost: 100,
    },
}

// Use the same client for different server connections
client1 := influxdb2.NewClientWithOptions("https://server1:8086", "token1", influxdb2.DefaultOptions().SetHTTPClient(httpClient))
client2 := influxdb2.NewClientWithOptions("https://server2:8086", "token2", influxdb2.DefaultOptions().SetHTTPClient(httpClient))

Proxy Configuration

You can configure a proxy in two ways:

1. Environment Variables: Set HTTP_PROXY or HTTPS_PROXY.
2. Custom HTTP Client: Create an http.Client with a configured Transport.Proxy and pass it via SetHTTPClient().

Handling Redirects

The client follows up to 10 consecutive redirects by default. However, for security, the Authorization header is not forwarded when a redirect leads to a different domain. To bypass this, provide a custom CheckRedirect handler in your http.Client that manually re-adds the token.

token := "my-token"

// Custom redirect handler to preserve Authorization header
httpClient := &http.Client{
    CheckRedirect: func(req *http.Request, via []*http.Request) error {
        req.Header.Add("Authorization", "Token " + token)
        return nil
    },
}
client := influxdb2.NewClientWithOptions("http://localhost:8086", token, influxdb2.DefaultOptions().SetHTTPClient(httpClient))

This example demonstrates the full lifecycle: creating a client, writing points using both the full constructor and the fluent style, writing via Line Protocol, and querying data back using Flux.

Key methods used:

• influxdb2.NewClient(url, token): Initializes the client.
• client.WriteAPIBlocking(org, bucket): Provides a synchronous write API.
• client.QueryAPI(org): Provides the query interface.
• client.Close(): Ensures background processes finish.

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/influxdata/influxdb-client-go/v2"
)

func main() {
    client := influxdb2.NewClient("http://localhost:8086", "my-token")
    writeAPI := client.WriteAPIBlocking("my-org", "my-bucket")
    
    // Write using full params constructor
    p := influxdb2.NewPoint("stat",
        map[string]string{"unit": "temperature"},
        map[string]interface{}{"avg": 24.5, "max": 45.0},
        time.Now())
    writeAPI.WritePoint(context.Background(), p)

    // Write using fluent style
    p = influxdb2.NewPointWithMeasurement("stat").
        AddTag("unit", "temperature").
        AddField("avg", 23.2).
        AddField("max", 45.0).
        SetTime(time.Now())
    err := writeAPI.WritePoint(context.Background(), p)
    if err != nil {
        panic(err)
    }

    // Write directly via Line Protocol
    line := fmt.Sprintf("stat,unit=temperature avg=%f,max=%f", 23.5, 45.0)
    err = writeAPI.WriteRecord(context.Background(), line)
    if err != nil {
        panic(err)
    }

    queryAPI := client.QueryAPI("my-org")
    result, err := queryAPI.Query(context.Background(), `from(bucket:"my-bucket")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`)
    if err == nil {
        for result.Next() {
            if result.TableChanged() {
                fmt.Printf("table: %s\n", result.TableMetadata().String())
            }
            fmt.Printf("row: %s\n", result.Record().String())
        }
        if result.Err() != nil {
            fmt.Printf("Query error: %s\n", result.Err().Error())
        }
    } else {
        panic(err)
    }
    client.Close()
}