feat: read managed database passwords from secrets

README.md

@@ -7,7 +7,7 @@ PawSQL is a TLS-terminating PostgreSQL router. It accepts PostgreSQL clients on
 - Go 1.24 or later to build and run PawSQL natively.
 - Docker Engine and a usable `docker` CLI to build the PawSQL image. PawSQL also needs them in its own execution environment when it manages PostgreSQL containers.
 - Optional: a TLS certificate and private key readable by PawSQL. Omit the `tls` block to serve plaintext PostgreSQL; with TLS, the certificate must cover every hostname clients use for SNI routing.
-- Docker Engine access for each `postgres` route. Managed database images are limited to `postgres:16`, `postgres:17`, and `postgres:18`.
+- Docker Engine access for each `postgres` route. Managed database images are limited to `postgres:16`, `postgres:17`, and `postgres:18`; each route also requires a mounted Docker secret file.
 
 ## Build, configure, and run
 
@@ -38,6 +38,7 @@ docker run --rm --publish 5432:5432 \
   --volume "$PWD/Barkfile:/etc/pawsql/Barkfile:ro" \
   --volume "$PWD/tls:/etc/pawsql/tls:ro" \
   --volume /var/run/docker.sock:/var/run/docker.sock \
+  --volume "$PWD/secrets:/run/secrets:ro" \
   pawsql
 ```
 
@@ -66,7 +67,7 @@ pawsql {
         postgres {
             image postgres:17
             volume pawsql-application-data
-            password_env APPLICATION_POSTGRES_PASSWORD
+            password_secret application_postgres_password
             idle_timeout 10m
             traffic_idle_timeout 1h
         }
@@ -76,7 +77,15 @@ pawsql {
 
 `listen` is PawSQL's TCP address. `cert` and `key` identify the client-facing TLS certificate and key. `hostname` is optional; it is used only for SNI routing. `upstream` is the address of an existing PostgreSQL server.
 
-For a managed `postgres` route, `image`, `volume`, and `password_env` are required. On first use, PawSQL reads the named environment variable to create the database container and configures the database and PostgreSQL user with the route's database name. The named Docker volume preserves its data. Set the password environment variable in PawSQL's environment, not in the Barkfile.
+For a managed `postgres` route, `image`, `volume`, and `password_secret` are required. `password_secret` is a short lowercase reference; PawSQL reads it from `/run/secrets/barkstack_<reference>`. The example therefore reads `/run/secrets/barkstack_application_postgres_password`. On first use, PawSQL uses that value to configure the database and PostgreSQL user with the route's database name. The named Docker volume preserves its data.
+
+Create the Docker Swarm secret before running `barkstack init`; Barkstack verifies that every referenced secret exists and mounts it into the PawSQL service:
+
+```sh
+docker secret create barkstack_application_postgres_password /secure/path/application-postgres-password
+```
+
+For a standalone PawSQL container, mount a directory containing the equivalently named file at `/run/secrets`, as shown above. Never put the password value in the Barkfile.
 
 See [`examples/Barkfile`](examples/Barkfile) and its accompanying [`examples/docker-compose.yml`](examples/docker-compose.yml) for a two-route external PostgreSQL example with locally generated development certificates:
 

cmd/pawsql/main.go

@@ -14,7 +14,7 @@ import (
 	"syscall"
 	"time"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 	"github.com/barkstack/pawsql/internal/adminui"
 	"github.com/barkstack/pawsql/internal/postgres"
 	"github.com/barkstack/pawsql/internal/router"

go.mod

@@ -2,4 +2,4 @@ module github.com/barkstack/pawsql
 
 go 1.24
 
-require cloud.campbellwireless.net/git/barkstack/barkfile-parser v1.1.0
+require cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2 v2.0.0

go.sum

@@ -1,2 +1,2 @@
-cloud.campbellwireless.net/git/barkstack/barkfile-parser v1.1.0 h1:ULdpvY1VC1d5M8VHx8SqacVLmk5SgvDYABDuzewebjc=
+cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2 v2.0.0 h1:oXVNd8wwR06OaBMDPCVr4zAWZw6L0VBCODkXaHeMI/I=
-cloud.campbellwireless.net/git/barkstack/barkfile-parser v1.1.0/go.mod h1:UnKTlB8ifO3cmsrkh2LDAM+Y2ipaCrBeiURwrSRPPe4=
+cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2 v2.0.0/go.mod h1:um5p/9XtFqZqhh087AlPB2nr4NxhrQxw5sxe32uMbzw=

internal/postgres/provisioner.go

@@ -9,10 +9,11 @@ import (
 	"net"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 	"time"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 )
 
 const managedDatabaseLabel = "io.barkstack.pawsql.database"
@@ -21,6 +22,7 @@ const managedDatabaseLabel = "io.barkstack.pawsql.database"
 // loopback-published PostgreSQL address to PawSQL's static router.
 type Provisioner struct {
 	DockerPath      string
+	SecretDirectory string
 	Logger          *slog.Logger
 }
 
@@ -29,7 +31,7 @@ func NewProvisioner(logger *slog.Logger) *Provisioner {
 	if logger == nil {
 		logger = slog.Default()
 	}
-	return &Provisioner{DockerPath: "docker", Logger: logger}
+	return &Provisioner{DockerPath: "docker", SecretDirectory: "/run/secrets", Logger: logger}
 }
 
 // Ensure provisions each PostgreSQL-backed database and returns configuration
@@ -65,13 +67,13 @@ func (p *Provisioner) EnsureDatabase(ctx context.Context, database string, postg
 		return "", err
 	}
 	if !exists {
-		password, ok := os.LookupEnv(postgres.PasswordEnv)
+		password, err := p.readSecret(postgres.PasswordSecret)
-		if !ok || password == "" {
+		if err != nil {
-			return "", fmt.Errorf("environment variable %q is required to create the container", postgres.PasswordEnv)
+			return "", err
 		}
 		p.Logger.Info("creating PostgreSQL container", "database", database, "container", name, "image", postgres.Image, "volume", postgres.Volume)
 		mount := postgresDataMount(postgres.Image)
-		_, err := p.run(ctx, []string{"POSTGRES_PASSWORD=" + password},
+		_, err = p.run(ctx, []string{"POSTGRES_PASSWORD=" + password},
 			"container", "create",
 			"--name", name,
 			"--label", managedDatabaseLabel+"="+database,
@@ -110,6 +112,26 @@ func (p *Provisioner) EnsureDatabase(ctx context.Context, database string, postg
 	return address, nil
 }
 
+func (p *Provisioner) readSecret(reference string) (string, error) {
+	if !config.ValidSecretReference(reference) {
+		return "", fmt.Errorf("invalid password secret reference %q", reference)
+	}
+	directory := p.SecretDirectory
+	if directory == "" {
+		directory = "/run/secrets"
+	}
+	name := config.DockerSecretName(reference)
+	contents, err := os.ReadFile(filepath.Join(directory, name))
+	if err != nil {
+		return "", fmt.Errorf("read Docker secret %q: %w", name, err)
+	}
+	password := strings.TrimRight(string(contents), "\r\n")
+	if password == "" {
+		return "", fmt.Errorf("Docker secret %q is empty", name)
+	}
+	return password, nil
+}
+
 // StopDatabase stops a managed PostgreSQL container without removing its data volume.
 func (p *Provisioner) StopDatabase(ctx context.Context, database string) error {
 	name := containerName(database)

internal/postgres/provisioner_integration_test.go

@@ -5,20 +5,26 @@ package postgres
 import (
 	"context"
 	"net"
+	"os"
+	"path/filepath"
 	"testing"
 	"time"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 )
 
 func TestProvisionerCreatesPersistentPostgres18(t *testing.T) {
 	const (
 		database  = "pawsql_integration_test"
 		volume    = "pawsql-integration-test-data"
-		envName  = "PAWSQL_INTEGRATION_POSTGRES_PASSWORD"
+		secretRef = "integration_postgres_password"
 	)
-	t.Setenv(envName, "integration-test-password")
+	secretDirectory := t.TempDir()
+	if err := os.WriteFile(filepath.Join(secretDirectory, config.DockerSecretName(secretRef)), []byte("integration-test-password"), 0o600); err != nil {
+		t.Fatal(err)
+	}
 	provisioner := NewProvisioner(nil)
+	provisioner.SecretDirectory = secretDirectory
 	defer func() {
 		_, _ = provisioner.run(context.Background(), nil, "container", "rm", "--force", containerName(database))
 		_, _ = provisioner.run(context.Background(), nil, "volume", "rm", "--force", volume)
@@ -29,7 +35,7 @@ func TestProvisionerCreatesPersistentPostgres18(t *testing.T) {
 		Postgres: &config.PostgresConfig{
 			Image:          "postgres:18",
 			Volume:         volume,
-			PasswordEnv: envName,
+			PasswordSecret: secretRef,
 		},
 	}}}
 	resolved, err := provisioner.Ensure(context.Background(), cfg)

internal/postgres/provisioner_test.go

@@ -1,6 +1,13 @@
 package postgres
 
-import "testing"
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
+)
 
 func TestPostgresDataMount(t *testing.T) {
 	tests := []struct {
@@ -17,3 +24,41 @@ func TestPostgresDataMount(t *testing.T) {
 		}
 	}
 }
+
+func TestReadSecretUsesPrefixedDockerName(t *testing.T) {
+	directory := t.TempDir()
+	path := filepath.Join(directory, config.DockerSecretName("application_password"))
+	if err := os.WriteFile(path, []byte("correct horse battery staple\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	provisioner := &Provisioner{SecretDirectory: directory}
+	password, err := provisioner.readSecret("application_password")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if password != "correct horse battery staple" {
+		t.Fatalf("password = %q", password)
+	}
+}
+
+func TestReadSecretRejectsUnsafeReference(t *testing.T) {
+	provisioner := &Provisioner{SecretDirectory: t.TempDir()}
+	_, err := provisioner.readSecret("../../etc/passwd")
+	if err == nil || !strings.Contains(err.Error(), "invalid password secret reference") {
+		t.Fatalf("readSecret() error = %v", err)
+	}
+}
+
+func TestReadSecretRejectsMissingAndEmptySecret(t *testing.T) {
+	directory := t.TempDir()
+	provisioner := &Provisioner{SecretDirectory: directory}
+	if _, err := provisioner.readSecret("missing"); err == nil || !strings.Contains(err.Error(), "barkstack_missing") {
+		t.Fatalf("missing secret error = %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(directory, config.DockerSecretName("empty")), []byte("\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := provisioner.readSecret("empty"); err == nil || !strings.Contains(err.Error(), "is empty") {
+		t.Fatalf("empty secret error = %v", err)
+	}
+}

internal/postgres/resolver.go

@@ -6,7 +6,7 @@ import (
 	"sync"
 	"time"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 	"github.com/barkstack/pawsql/internal/router"
 )
 

internal/postgres/resolver_test.go

@@ -6,14 +6,14 @@ import (
 	"testing"
 	"time"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 	"github.com/barkstack/pawsql/internal/router"
 )
 
 func TestResolverDefersManagedDatabaseStartup(t *testing.T) {
 	routes, err := router.NewStaticResolver([]config.DatabaseConfig{
 		{Name: "external", Upstream: "192.0.2.1:5432"},
-		{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD"}},
+		{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password"}},
 	})
 	if err != nil {
 		t.Fatal(err)
@@ -21,7 +21,7 @@ func TestResolverDefersManagedDatabaseStartup(t *testing.T) {
 	ensurer := &fakeEnsurer{addresses: map[string]string{"managed": "127.0.0.1:55432"}}
 	resolver := NewResolver(routes, []config.DatabaseConfig{
 		{Name: "external", Upstream: "192.0.2.1:5432"},
-		{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD"}},
+		{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password"}},
 	}, ensurer)
 
 	backend, err := resolver.ResolveDatabase(context.Background(), "external")
@@ -42,12 +42,12 @@ func TestResolverDefersManagedDatabaseStartup(t *testing.T) {
 }
 
 func TestResolverSerializesManagedStartup(t *testing.T) {
-	routes, err := router.NewStaticResolver([]config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD"}}})
+	routes, err := router.NewStaticResolver([]config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password"}}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	ensurer := &fakeEnsurer{addresses: map[string]string{"managed": "127.0.0.1:55432"}, gate: make(chan struct{}), started: make(chan struct{})}
-	resolver := NewResolver(routes, []config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD"}}}, ensurer)
+	resolver := NewResolver(routes, []config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password"}}}, ensurer)
 
 	var wg sync.WaitGroup
 	for range 2 {
@@ -69,12 +69,12 @@ func TestResolverSerializesManagedStartup(t *testing.T) {
 }
 
 func TestResolverStopsDatabaseAfterIdleTimeout(t *testing.T) {
-	routes, err := router.NewStaticResolver([]config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD", IdleTimeout: 20 * time.Millisecond}}})
+	routes, err := router.NewStaticResolver([]config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password", IdleTimeout: 20 * time.Millisecond}}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	controller := &fakeEnsurer{addresses: map[string]string{"managed": "127.0.0.1:55432"}, stopped: make(chan string, 1)}
-	resolver := NewResolver(routes, []config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD", IdleTimeout: 20 * time.Millisecond}}}, controller)
+	resolver := NewResolver(routes, []config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password", IdleTimeout: 20 * time.Millisecond}}}, controller)
 
 	if _, err := resolver.ResolveDatabase(context.Background(), "managed"); err != nil {
 		t.Fatal(err)
@@ -91,12 +91,12 @@ func TestResolverStopsDatabaseAfterIdleTimeout(t *testing.T) {
 }
 
 func TestResolverCancelsIdleStopForNewConnection(t *testing.T) {
-	routes, err := router.NewStaticResolver([]config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD", IdleTimeout: 40 * time.Millisecond}}})
+	routes, err := router.NewStaticResolver([]config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password", IdleTimeout: 40 * time.Millisecond}}})
 	if err != nil {
 		t.Fatal(err)
 	}
 	controller := &fakeEnsurer{addresses: map[string]string{"managed": "127.0.0.1:55432"}, stopped: make(chan string, 1)}
-	resolver := NewResolver(routes, []config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordEnv: "MANAGED_PASSWORD", IdleTimeout: 40 * time.Millisecond}}}, controller)
+	resolver := NewResolver(routes, []config.DatabaseConfig{{Name: "managed", Postgres: &config.PostgresConfig{Image: "postgres:18", Volume: "managed-data", PasswordSecret: "managed_password", IdleTimeout: 40 * time.Millisecond}}}, controller)
 
 	if _, err := resolver.ResolveDatabase(context.Background(), "managed"); err != nil {
 		t.Fatal(err)
@@ -122,7 +122,7 @@ func TestResolverMetersTrafficAndStopsTrafficIdleSession(t *testing.T) {
 	postgres := &config.PostgresConfig{
 		Image:              "postgres:18",
 		Volume:             "managed-data",
-		PasswordEnv:        "MANAGED_PASSWORD",
+		PasswordSecret:     "managed_password",
 		TrafficIdleTimeout: 100 * time.Millisecond,
 	}
 	routes, err := router.NewStaticResolver([]config.DatabaseConfig{{Name: "managed", Postgres: postgres}})

internal/router/routes.go

@@ -7,7 +7,7 @@ import (
 	"fmt"
 	"strings"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 )
 
 var (

internal/router/routes_test.go

@@ -5,7 +5,7 @@ import (
 	"errors"
 	"testing"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 )
 
 func TestStaticResolverRoutesCaseInsensitiveHostnames(t *testing.T) {

internal/server/server_test.go

@@ -14,7 +14,7 @@ import (
 	"testing"
 	"time"
 
-	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser"
+	config "cloud.campbellwireless.net/git/barkstack/barkfile-parser/v2"
 	"github.com/barkstack/pawsql/internal/pgwire"
 	"github.com/barkstack/pawsql/internal/router"
 )