neo-client

neo-client is the Go client module for Machbase Neo.

It provides:

• machgo: the main client package used by applications
• machbase: the standard database/sql driver package
• api: shared interfaces, options, and helper types
• machnet: lower-level protocol and transport implementation used by machgo

The examples in this module show how to connect to a Machbase Neo server, execute queries, append time-series records, and use the standard database/sql API.

Requirements

• Go 1.22 or later
• A reachable Machbase Neo server
• A valid user account, such as sys / manager in a local development environment

The examples in this repository use the native TCP endpoint, usually 127.0.0.1:5656.

Install

go get github.com/machbase/neo-client

Package Layout

machgo

Use this package for normal application code. It exposes the database handle, connection management, query execution, prepared statements, and append operations.

api

This package contains interfaces such as Database, Conn, Rows, and Appender, plus options like api.WithPassword, api.WithFetchRows, and api.WithStatementCache.

machbase

This package provides a standard Go database/sql driver on top of the native TCP client. Use it when you want to integrate Machbase Neo with libraries or application code that already expect the standard database/sql interfaces.

machnet

This is the lower-level client implementation used internally by machgo. Most application code should not need to import it directly.

Quick Start

Connect and Query

The following example connects to a server and reads from the M$SYS_TABLES system table.

package main

import (
	"context"
	"fmt"

	"github.com/machbase/neo-client/api"
	"github.com/machbase/neo-client/machgo"
)

func main() {
	db, err := machgo.NewDatabase(&machgo.Config{
		Host:        "127.0.0.1",
		Port:        5656,
		MaxOpenConn: -1,
	})
	if err != nil {
		panic(err)
	}
	defer db.Close()

	ctx := context.Background()
	conn, err := db.Connect(ctx, api.WithPassword("sys", "manager"))
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	rows, err := conn.Query(ctx, `SELECT NAME, ID, TYPE FROM M$SYS_TABLES ORDER BY NAME`)
	if err != nil {
		panic(err)
	}
	defer rows.Close()

	for rows.Next() {
		var (
			name string
			id   int64
			typ  int
		)
		if err := rows.Scan(&name, &id, &typ); err != nil {
			panic(err)
		}
		fmt.Println(name, id, typ)
	}

	if err := rows.Err(); err != nil {
		panic(err)
	}
}

Append Rows

The append example assumes a tag table named EXAMPLE exists with NAME, TIME, and VALUE columns.

CREATE TAG TABLE IF NOT EXISTS example (
    name VARCHAR(100) PRIMARY KEY,
    time DATETIME BASETIME,
    value DOUBLE
);

Then append rows with conn.Appender:

package main

import (
	"context"
	"time"

	"github.com/machbase/neo-client/api"
	"github.com/machbase/neo-client/machgo"
)

func main() {
	db, err := machgo.NewDatabase(&machgo.Config{
		Host:        "127.0.0.1",
		Port:        5656,
		MaxOpenConn: -1,
	})
	if err != nil {
		panic(err)
	}
	defer db.Close()

	ctx := context.Background()
	conn, err := db.Connect(ctx, api.WithPassword("sys", "manager"))
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	appender, err := conn.Appender(ctx, "EXAMPLE")
	if err != nil {
		panic(err)
	}

	ts := time.Now()
	for i := 0; i < 10; i++ {
		if err := appender.Append(
			"example-client",
			ts.Add(time.Duration(i)*time.Second),
			3.14*float64(i),
		); err != nil {
			panic(err)
		}
	}

	success, fail, err := appender.Close()
	if err != nil {
		panic(err)
	}

	println("Append finished.", "success:", success, "fail:", fail)
}

Use the Standard database/sql Driver

If your application already uses database/sql, import github.com/machbase/neo-client for driver registration and connect with sql.Open.

package main

import (
	"context"
	"database/sql"
	"fmt"

	_ "github.com/machbase/neo-client"
)

func main() {
	dsn := "server=tcp://sys:manager@127.0.0.1:5656;fetch_rows=777;statement_cache=off;io_metrics=true"

	db, err := sql.Open("machbase", dsn)
	if err != nil {
		panic(err)
	}
	defer db.Close()

	ctx := context.Background()
	rows, err := db.QueryContext(ctx, `SELECT * FROM M$SYS_TABLES ORDER BY NAME`)
	if err != nil {
		panic(err)
	}
	defer rows.Close()

	cols, err := rows.Columns()
	if err != nil {
		panic(err)
	}
	fmt.Println("Columns:", cols)
	for rows.Next() {
		// scan values here
	}
	if err := rows.Err(); err != nil {
		panic(err)
	}
}

Supported DSN keys for the standard driver include:

• server: server address such as tcp://sys:manager@127.0.0.1:5656
• host, port, user, password: explicit connection fields
• fetch_rows: fetch batch size
• statement_cache: auto, on, or off
• io_metrics: true or false
• alternative_servers: alternative server list such as 127.0.0.2:5656

The standard driver follows database/sql pooling through sql.DB. Explicit transaction statements are not supported by Machbase Neo, so Begin and BeginTx return an error. LastInsertId is also not supported.

Running the Included Examples

Four runnable examples are included under _example/.

Run the query example:

go run ./_example/query.go -s 127.0.0.1:5656 -u sys -p manager

Run the append example:

go run ./_example/append.go -s 127.0.0.1:5656 -u sys -p manager

Run the standard driver query example:

go run ./_example/driver_query.go -s 127.0.0.1:5656 -u sys -p manager

Run the standard driver insert example:

go run ./_example/driver_insert.go -s 127.0.0.1:5656 -u sys -p manager

Common Connection Options

• api.WithPassword(user, password): connect with explicit credentials
• api.WithFetchRows(n): override the default fetch batch size for a connection
• api.WithStatementCache(mode): control query statement reuse
• api.WithIOMetrics(true): enable I/O metrics collection on the connection

Notes

• Always close Rows, Stmt, Appender, and Conn objects after use.
• Appender.Close() returns success and failure counts for the append session.
• For regular application usage, prefer machgo over importing machnet directly.
• Use machbase when you need compatibility with database/sql and its connection pooling.
• The standard driver does not support explicit transactions or LastInsertId.

See Also

• _example/query.go
• _example/append.go
• _example/driver_query.go
• _example/driver_insert.go