v0.1.0

The first release of dbimp. It holds one driver, for Couchbase, and the code that every later driver shares.

The Couchbase driver

github.com/xo/dbimp/couchbase is a database/sql driver for the Couchbase query service and SQL++. It replaces github.com/couchbase/go_n1ql and xo/n1ql. It uses the Go standard library and github.com/cockroachdb/apd/v3, and it needs no cgo.

import (
	"database/sql"

	_ "github.com/xo/dbimp/couchbase"
)

db, err := sql.Open("couchbase", "couchbase://user:pass@localhost:8093/")

• It registers one name, couchbase, and takes only a couchbase:// URL. The keys of the URL are tls, query_context, scan_consistency, timeout, durability_level and txtimeout. An unknown key or a repeated key is an error.
• The server binds each argument. ?, $1 and sql.Named all work.
• A row keeps the order of the columns that the server sends, and each value is a Go value: int64, float64, string, bool, []any, map[string]any, or nil for NULL and MISSING. An integer too large for an int64 is a *apd.Decimal.
• A string scans into a []byte as base64, and as its own bytes when it is not base64.
• It reads a result one token at a time as it arrives, and it never holds the whole result in memory.
• database/sql transactions map onto the transactions of the query service. On a server with one node, set durability_level=none, because the default durability cannot commit there. The server ends a transaction after 15 seconds unless txtimeout is longer.
• WithOptions and the Option functions set the options of one statement or one transaction. WithParameter sets any parameter of the request by its name.
• A failed response is a *couchbase.ResponseError, and errors.As finds each couchbase.Error in it, with its code.
• It stops a query when its context ends.

It is tested on Couchbase 7.2.9, 7.6.12 and 8.0.3, as an administrator and as an ordinary user. The tests cover CRUD, each native type, and each feature in testdata/couchbase/features.json. docs/COUCHBASE.md holds every fact that was measured.

What a consumer changes

• The scheme is couchbase, not n1ql. dburl keeps n1ql as an alias.
• A value is a decoded Go value, not JSON text, so code that called strconv.Unquote on a value no longer needs it.
• The columns keep the order that the server sends. Couchbase 7.2 sends them in the order of their names.
• LastInsertId returns an error, and RowsAffected returns the count of mutations.

For the authors of drivers

• The root package dbimp holds the HTTP client, the readers of rows, the decoders of values and the parser of placeholders.
• dbimptest holds the helpers for the tests of a driver: recorded exchanges, the contract suite, the round trip of a type, and the survey of features.
• docs/DRIVER.md holds every step to add a driver, and the gates in gates_test.go hold the steps.