Skip to content
xoPublic

About

Go package to forward remote database connections (k8s, ssh, ...)

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation


Unit Tests Go Reference Releases Discord Discussion

About

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.

Installing

The package:

go get github.com/xo/dbfwd

The command, which runs the native client of a database or usql through a forward:

go install github.com/xo/dbfwd/cmd/dbfwd@latest

dbfwd runs kubectl, so kubectl must be on the path, with a kubeconfig that reaches the cluster.

Using

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.

Documents

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

Related Projects

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.

  • usql is a command line client for many databases. It calls dbfwd for a k8s URL and holds the Forward for the session.
  • dburl parses a database URL, including the k8s scheme and its aliases. dbfwd reads the URL that dburl parsed, and never parses one.
  • dbmeta reads database metadata. Its dbrun starts the kind cluster that the tests of dbfwd run in, and its client table names the native client that the dbfwd command runs.

Contributing

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.

License

MIT. See LICENSE.


About

Go package to forward remote database connections (k8s, ssh, ...)

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages