Unofficial Go client SDK for Apache Fluss 0.9.x.

This repository is building a Go-native Fluss client without requiring Java in the application runtime path.

The SDK is real, working, and actively developed, but it is not production-ready yet.

Today it already includes:

• direct TCP client connectivity to Fluss
• admin APIs for database, table, schema, and partition operations
• lake snapshot admin APIs including latest, readable, and by-ID lookup
• data operations for append, upsert, partial update, delete, lookup, prefix lookup, fetch log, and limit scan
• public row/schema/type helpers for the currently implemented data types
• Arrow log fetch/projection support on Fluss ARROW log tables
• buffered AppendWriter and UpsertWriter with explicit Flush(ctx) and flush-on-close behavior
• a lightweight Fluss-only development stack and host-run validation harness under demo/fluss-dev/README.md
• a real Fluss + Paimon container demo used as the canonical end-to-end support check

The communication layer itself is now production-ready enough to serve as the SDK foundation: bootstrap rotation, metadata-driven coordinator/tablet routing, route refresh/retry, endpoint cooldown handling, preferred-listener selection, background metadata refresh, and connection recycling under failure are all implemented and verified locally plus against the real demo/fluss-dev stack. The broader SDK still has non-transport gaps before the whole project should be called production-ready.

High level:

• Fluss 0.9.x
• Go-native admin workflows
• lake snapshot metadata workflows aligned with the upstream Java client
• log-table writes and reads
• primary-key upsert, lookup, partial update, delete, prefix lookup, and limit scan
• implemented scalar and composite Fluss data types in the current row helpers
• validation against a Fluss deployment configured with Paimon-backed lakehouse infrastructure, including the lake snapshot admin path used by Fluss lake tables and a manual-style hot+cold query inspection step in the demo stack

For the detailed support matrix, see the public docs site:

• support matrix: https://chiqors.github.io/fluss-go-client/project/support-matrix

Important gaps still remain:

• production-grade scanner abstractions
• broader snapshot batch-scan portability across additional filesystem backends and cluster layouts beyond the current canonical real-cluster demo path
• hardened retry/reconnect behavior under failure is in progress, with bootstrap rotation, route refresh retries, endpoint cooldown tracking, and background metadata refresh now implemented
• secured-cluster auth and token workflows beyond the basic hook surface
• metrics and tracing hooks
• full compatibility/regression coverage across more cluster scenarios
• polished examples and final public API documentation

The main reasons are:

• some public surfaces are still low-level compared with the upstream Java client
• writer ergonomics have started, and the communication layer now has a stronger retry/reroute foundation, but broader failover proof, observability, and secured-environment coverage still need more work
• scanner ergonomics are not finished yet
• real-cluster coverage is good for the current support-contract flows, but not broad enough for production confidence
• observability and secured-environment support are still incomplete

The Go SDK only requires bootstrap endpoint(s) in client configuration, but successful bootstrap does not guarantee later table/admin RPC success by itself.

After bootstrap, Fluss metadata provides the coordinator and tablet endpoints that the client should use. Those advertised endpoints must be reachable from the client network. In containerized or multi-network deployments, that means cluster-side listener/advertised-listener configuration still matters even though the SDK does not ask callers to configure tablet endpoints directly.

The long-lived roadmap is in GRAND_PLAN.md.

Install:

go get github.com/chiqors/fluss-go-client@latest

Connect and list databases:

package main

import (
	"context"
	"log"

	"github.com/chiqors/fluss-go-client/client"
)

func main() {
	ctx := context.Background()

	cli, err := client.Dial(ctx, client.Config{
		Endpoints: []string{"127.0.0.1:9123"},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer cli.Close()

	names, summaries, err := cli.Admin().ListDatabases(ctx, true)
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("database names: %v", names)
	log.Printf("database summaries: %v", summaries)
}

Get table metadata:

table := cli.Table(client.TablePath{
	DatabaseName: "fluss",
	TableName:    "orders",
})

info, err := table.Info(ctx)
if err != nil {
	log.Fatal(err)
}

schema, err := table.Schema(ctx, nil)
if err != nil {
	log.Fatal(err)
}

_, _ = info, schema

For contributor onboarding and the local SDK development loop, start with:

• CONTRIBUTING.md
• demo/fluss-dev/README.md

Useful docs:

• GRAND_PLAN.md: roadmap and project memory
• website/: Docusaurus docs site for the Go SDK, including the public support matrix and architecture docs
• AGENTS.md: repo working rules
• CONTRIBUTING.md: contribution workflow
• demo/fluss-dev/README.md: local contributor/dev stack
• demo/fluss-paimon/README.md: real-cluster demo contract

Public docs site:

• GitHub Pages target: https://chiqors.github.io/fluss-go-client/
• support matrix: https://chiqors.github.io/fluss-go-client/project/support-matrix
• architecture overview: https://chiqors.github.io/fluss-go-client/project/architecture-overview
• website toolchain: bun install then bun run build from website/
• local preview: bun run serve from website/

Useful local checks:

gofmt -w $(find . -name '*.go' -not -path './.git/*')
go test ./...
go build ./...

The upstream Java client at apache/fluss is the behavioral reference for overlapping semantics. This repo keeps the public API Go-native while using upstream Java behavior and Fluss protocol definitions as the source of truth.

Contributions are welcome.

Please read CONTRIBUTING.md first, and keep these expectations in mind:

• preserve Go-native public APIs
• use the upstream Java client as a behavioral reference, not as a package-structure template
• update docs and GRAND_PLAN.md when meaningful progress or blockers change
• verify changes with tests proportional to risk

This repository is licensed under the Apache License 2.0. See LICENSE.