Go Client Library for InfluxDB 3.0

By Community / Developer
Dec 04, 2024

In a world driven by data, efficient time series data management is a growing concern. APIs play a significant role in automating tasks, especially in cloud-based environments. Go, with its high performance and concurrency, is quickly becoming one of the standard languages for writing cloud infrastructure and utilities for managing streams of data. InfluxDB’s Go client library helps developers work with time series data inside their Go applications, making it indispensable for anyone working with real-time analytics, IoT, or monitoring systems.

InfluxDB 3.0 is a high-performance, scalable time series database designed for real-time analytics. It’s equipped with rich functionality, such as data ingestion management, querying, and visualization of huge amounts of time series data, making it the perfect tool for industrial use cases requiring real-time insights, IoT, monitoring, etc.

In this tutorial, you’ll learn how to

• Set up InfluxDB Cloud (Serverless or Dedicated)
• Install and configure the Go client library
• Write and query time series data
• Develop efficient and scalable security best practices

Let’s dive in.

Prerequisites

To get the most out of this tutorial, you need to:

• Have a basic understanding of RESTful APIs
• Be familiar with time series databases (concepts like measurements, tags, and fields)

Before we get started, please have the following software requirements set up:

• InfluxDB 3.0 Cloud (Serverless or Dedicated)
• Go
• InfluxDB CLI (optional but handy for interacting with the database directly)
• Postman or cURL (optional for testing API endpoints)

Setting up InfluxDB 3.0

The demonstrations in this tutorial will use InfluxDB Cloud Serverless. So, let’s start by setting it up.

Installation

Since we’re using InfluxDB Cloud Serverless, there’s no need for local installations. You’ll only need to create an account by following the steps below:

1. Go to the InfluxDB Cloud signup page. Choose subscribe through InfluxData and create an account.

1. Enter your account and organization name, select your preferred region for your AWS store, agree to the terms and conditions, and click on the Continue button.

1. Select your preferred plan to continue.

1. Select how you want to use InfluxDB; check all the options that apply to your use case.

Configuration

Before using the InfluxDB Go client, you’ll want to create a database, set up your authentication, and identify your InfluxDB instance. Here’s how you can do this:

1. Create a new bucket (database): From your InfluxDB dashboard, navigate to Load Data > Buckets using the left navigation bar. Enter a name for your bucket, select your data retention preference (I selected one hour because I want to delete it after this tutorial), and click the Create button.

1. Create an API token: Click on API Tokens, then click the Generate API TOKEN button to set up a new All-Access API Token, which is able to read, create, update, delete, and write access for your bucket and organization. You can also choose to create a custom API Token and customize the access the way you want.

1. Find your InfluxDB cloud URL: You’ll need this to connect your Go client. Just head to the Sources tab. Then, under Client Libraries on the dashboard, select Go.

Overview of InfluxDB 3.0’s APIs

InfluxDB 3.0 provides an array of APIs to facilitate handling time series data in different programming languages. Below is a list of client libraries that are available and how they authenticate.

API Types

InfluxDB 3.0 provides dedicated client libraries for several languages, each optimized to work smoothly within its specific environment, so developers can efficiently write and query data:

• C# (.NET): influxdb3-csharp is written in C#, and it provides data interaction for C# applications.
• Go: influxdb3-go is optimized for Go applications, and it’s also an efficient data management tool.
• Java: The influxdb3-java library is available to support Java apps for managing reliable data operations.
• JavaScript: The influxdb3-js library supports JavaScript and hence can be easily adapted for web-based applications.
• Python: influxdb3-python is built for Python to handle the data in scripts without any hitches.

These libraries allow you to write batch data over HTTP APIs and to perform SQL and InfluxQL queries using the Arrow Flight protocol over gRPC. They can also convert data formats to InfluxDB line protocol. For this tutorial, our focus is on the influxdb3-go client.

Authentication

To access data securely, InfluxDB 3.0 uses token-based authentication:

• Users create a database token within the GUI of the InfluxDB Cloud.
• Use the token in the Authorization header in every API request as a bearer token.

This configuration provides only relevant access to the database and makes authentication secure and easy with all the supported client libraries.

Using the Go client library

Now, let’s go through the core steps of using the InfluxDB Go client Library to interact with your data.

Installing the Go Client Library

First, we need to create a new Go module with the command below:

mkdir -p influxdb_go_client_demo
cd influxdb_go_client_demo
go mod init influxdb_go_client_demo
touch main.go

Then, run the command below to install the Go client library for InfluxDB 3.0.

go get github.com/InfluxCommunity/influxdb3-goz

This will download and install the necessary package to interact with InfluxDB Cloud.

Importing the Package

After installation, import the package in your Go project:

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

Initializing the Client

The client class serves as your primary interface for interacting with InfluxDB. InfluxDB Cloud uses tokens to authenticate API access, so you need to save the all-access token you created earlier as an environment variable with the command below:

export INFLUXDB_TOKEN=<YOUR_API_TOKEN>

Replace <YOUR_API_TOKEN> with your actual API token. Next, initialize the Go client with the server URL and token to set up the initial connection to InfluxDB. This client has functions WritePoints and Query. Paste the following code in your main.go file:

package main

import (
    "context"
    "fmt"
    "time"

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

func main() {
    // Create client
    url := "https://us-east-1-1.aws.cloud2.influxdata.com"
    token := os.Getenv("INFLUXDB_TOKEN")

// Create a new client using an InfluxDB server base URL and an authentication token
    client, err := influxdb3.New(influxdb3.ClientConfig{
      Host:  url,
      Token: token,
    })

      if err != nil {
      panic(err)
    }
    // Close client at the end and escalate error if present
    defer func (client *influxdb3.Client)  {
      err := client.Close()
      if err != nil {
        panic(err)
      }
    }(client)

    database := "testDB"
}

The influxdb3.New function is used to create a new client instance. It takes a ClientConfig struct as an argument, which includes two elements:

• host (string): the InfluxDB Cloud server URL
• token (string): your API token for authenticating requests

Replace testDB with your bucket name.

Writing Data to InfluxDB

Writing data is straightforward. First, create a data point with relevant measurements, tags, and fields, then send it to InfluxDB.

package main
import (

    //...
     "context"
    "time"
  )

func writeData(database string, client *influxdb3.Client) {
	data := map[string]map[string]interface{}{
		"post1": {
			"title":    "InfluxDB Basics",
			"author":   "Alice",
			"views":    150,
			"category": "Databases",
		},
		"post2": {
			"title":    "Go Client Libraries for InfluxDB",
			"author":   "Bob",
			"views":    200,
			"category": "Programming",
		},
		"post3": {
			"title":    "Understanding Time Series Data",
			"author":   "Alice",
			"views":    175,
			"category": "Data Science",
		},
		"post4": {
			"title":    "Getting Started with Flux",
			"author":   "Charlie",
			"views":    220,
			"category": "Databases",
		},
		"post5": {
			"title":    "Optimizing Queries in InfluxDB",
			"author":   "Alice",
			"views":    180,
			"category": "Databases",
		},
	}

	// Write blog data to InfluxDB
	options := influxdb3.WriteOptions{
		Database: database,
	}

	for key := range data {
		point := influxdb3.NewPointWithMeasurement("blog_views").
			AddTag("author", data[key]["author"].(string)).
			AddTag("category", data[key]["category"].(string)).
			AddField("views", data[key]["views"].(int)).
			AddField("title", data[key]["title"].(string))

		if err := client.WritePointsWithOptions(context.Background(), &options, point); err != nil {
			panic(err)
		}

		time.Sleep(1 * time.Second) // separate points by 1 second
	}
}

func main() {
   //...
   writeData(database, client)
}

In the above code, we used six functions:

• Client.WritePoint() writes a single data point to InfluxDB. It takes a database name.
• NewPointWithMeasurement() creates a new data point with a specified measurement name.
• AddTag() adds metadata to a point as a key-value pair.
• AddField() adds the actual data values to a point as a key-value pair.
• WritePointsWithOptions() writes points to InfluxDB with specific configuration options.
• WriteOptions defines struct configuration settings for writing data to InfluxDB.

This writes blog data into your bucket. Now, run the program with the command below:

go run ./main.go

Querying Data From InfluxDB

Querying data is as simple as using the Query function from the Go client. InfluxDB runs queries using SQL. Now, let’s add a new function to query your bucket and get all the blog data inserted earlier.

package main

import (
    //...
    "fmt"
)

func queryBlogs(database string, client *influxdb3.Client) {
	query := `SELECT *
              FROM 'blog_views'
              WHERE time >= now() - interval '1 hour'

	queryOptions := influxdb3.QueryOptions{
		Database: database,
	}
	iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query)
	if err != nil {
		panic(err)
	}

	for iterator.Next() {
		value := iterator.Value()
		title := value["title"]
		author := value["author"]
		views := value["views"]
		category := value["category"]
		fmt.Printf("%s by %s has %d views in category %s\\n", title, author, views, category)
	}

}

func main() {
  //...

  queryBlogs(database, client)
}

The above code retrieves the blog’s records within a specific time range and prints the values.

• QueryWithOptions() executes an SQL query with specific database options.
• Value() returns the current record as a map of field names to values.
• Next() advances the iterator to the next record in the results.
• QueryOptions specifies configuration options for the query execution.

Now, run the program again to execute the query.

Best practices

Here are some best practices to consider to get the most out of your InfluxDB integration. These recommendations will help you maintain a secure, efficient, and highly scalable solution.

Security

Keep your data protected and ensure secure access to your InfluxDB instance:

• Always connect to InfluxDB using a secure HTTPS connection.
• Rotate your tokens regularly to reduce security risks.
• Store API tokens and sensitive data in environment variables.

Efficiency

You can also significantly enhance the performance of your application by optimizing your data writes and queries. Here are some tips for doing so efficiently:

• For high-throughput applications, batch your write operations to reduce network overhead.
• Use the appropriate precision of your times. It could be nanoseconds or seconds, depending on your needs. Doing so minimizes storage and improves performance.

Scalability

As your data grows, you’ll want to ensure your InfluxDB setup can scale. Here are a few scalability considerations:

• Use retention policies to automatically delete old data and control the cost of storage.
• InfluxDB Cloud Dedicated is more suitable for enterprise applications and offers higher throughput and scalability.

Wrapping up

In this tutorial, we covered some of the fundamentals of using the InfluxDB 3.0 Go client library, including how to do the following:

• Set up and configure InfluxDB Cloud.
• Write and query data using the Go client library.
• Impose best practices for security, efficiency, and scalability.

Now that you’ve learned how to use the InfluxDB Go client library, it’s time to do it! Sign up for InfluxDB Cloud Serverless or dig deeper into an enterprise solution with InfluxDB Cloud Dedicated.

Further reading

To learn more about InfluxDB, here are some extra resources:

• InfluxDB Go Client Documentation
• InfluxDB Cloud API Reference