dbfwd connects a program such as usql to a database that runs on
Kubernetes. It reads a URL such as k+cnpg://pg.prod/app or
k://pg-rw.prod/, finds the database, starts a port-forward, and gives back
an ordinary URL for a local port. The URL that the caller writes holds no
password, because dbfwd reads the password from the cluster.
dbfwd picks the pod it forwards to and watches it. When the pod goes, such
as after a restart or a failover, dbfwd forwards to a new pod on the same
local port, and the URL keeps working.
It supports every tier 1 operator in docs/OPERATORS.md,
and a database with no operator, through its Service, StatefulSet,
Deployment, Helm release or pod. It is an early implementation for
Kubernetes. docs/PLAN.md says where it stands.
The package:
go get github.com/xo/dbfwdThe command, which runs the native client of a database or usql through a
forward:
go install github.com/xo/dbfwd/cmd/dbfwd@latestdbfwd runs kubectl, so kubectl must be on the path, with a kubeconfig
that reaches the cluster.
Run the client of a database through a forward:
dbfwd k+cnpg://pg.prod/From Go, Resolve returns a Forward, which holds the local URL and stops
the forward when it closes:
import (
"github.com/xo/dbfwd"
_ "github.com/xo/dbfwd/k8s"
"github.com/xo/dburl"
)
u, err := dburl.Parse("k+cnpg://pg.prod/app")
if err != nil {
return err
}
fwd, err := dbfwd.Resolve(ctx, u)
if err != nil {
return err
}
defer fwd.Close()
local, err := fwd.URL(ctx)
if err != nil {
return err
}
db, err := sql.Open(local.Driver, local.DSN)docs/API.md holds the API, and docs/CLI.md
holds the command.
| Document | What it holds |
|---|---|
docs/PLAN.md |
The aim, where the work stands, what other projects give, and the next steps |
docs/API.md |
The Go API of the package |
docs/URL.md |
The URL that dbfwd reads |
docs/LOOKUP.md |
How dbfwd finds a database from a name, with or without an operator |
docs/OPERATORS.md |
What each supported operator creates, and where dbfwd reads it |
docs/CLI.md |
The dbfwd command, which runs a native client or usql through a forward |
docs/LIST.md |
Listing the databases of a cluster, for dbfwd list and the \k command of usql |
docs/TESTING.md |
How dbfwd is tested, locally and in CI |
docs/decisions/ |
Every decision, one file each |
AGENTS.md |
The rules for a coding agent. Every rule applies to a person too |
CONTRIBUTING.md |
How to send a change |
dbfwd is one of a set of packages that each do one part of the job, so that
a client can take the parts it needs.
usqlis a command line client for many databases. It callsdbfwdfor ak8sURL and holds theForwardfor the session.dburlparses a database URL, including thek8sscheme and its aliases.dbfwdreads the URL thatdburlparsed, and never parses one.dbmetareads database metadata. Itsdbrunstarts the kind cluster that the tests ofdbfwdrun in, and its client table names the native client that thedbfwdcommand runs.
Read AGENTS.md first. It holds the rules, including the ones
that are not obvious: the standard library and dburl only in what usql
imports, no cgo, no build constraint on an operating system or an
architecture, and no password in a log, an error or the arguments of a child
process.
Run the checks before you send a change, with the same flags CI uses:
gofmt -l . && go vet ./... && go build ./... && go test -race -count=2 ./...Tests in the root module never need a cluster. They run against a fake
kubectl, or replay what a real cluster returned, from testdata/. The
cluster tests are in the test module, and
docs/TESTING.md says how to run them.
MIT. See LICENSE.