fix(tests): stop racing a live broker daemon against direct-SQL tests

test-all/test-ci started the standalone pgsql-broker binary via
broker-start before running the Go integration suite, leaving its
background workers polling queue 1/2 against broker_test for the
whole run. TestBrokerWorkflow already starts its own in-process
broker and needs no external daemon, and nothing else in the suite
uses it. The redundant daemon's worker could steal-claim a job that
stage5_test.go's TestJobDependencies or
TestFailedJobRetriesThenCompletesWithoutStranding had just inserted
before the test's own broker_get call ran, intermittently failing
those assertions. Drop broker-start/broker-stop from the test
targets; the standalone targets remain for manual use.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.github/workflows/docker-release.yml

@@ -0,0 +1,74 @@
+name: Build & Release Docker Image
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing tag to release (e.g. v0.1.0)'
+        required: true
+        type: string
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    env:
+      IMAGE: git.warky.dev/wdevs/pgsql-broker
+      TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+    steps:
+      - name: Validate release tag
+        run: |
+          case "$TAG" in
+            v*) ;;
+            *) echo "Release tags must start with v (received: $TAG)" >&2; exit 1 ;;
+          esac
+
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Verify package registry credentials
+        env:
+          PACKAGE_REGISTRY_USERNAME: ${{ secrets.PACKAGE_REGISTRY_USERNAME }}
+          PACKAGE_REGISTRY_TOKEN: ${{ secrets.PACKAGE_REGISTRY_TOKEN }}
+        run: |
+          test -n "$PACKAGE_REGISTRY_USERNAME" || {
+            echo 'PACKAGE_REGISTRY_USERNAME is required to publish the Docker image.' >&2
+            exit 1
+          }
+          test -n "$PACKAGE_REGISTRY_TOKEN" || {
+            echo 'PACKAGE_REGISTRY_TOKEN is required to publish the Docker image.' >&2
+            exit 1
+          }
+
+      - name: Log in to the Warky container registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.warky.dev
+          username: ${{ secrets.PACKAGE_REGISTRY_USERNAME }}
+          password: ${{ secrets.PACKAGE_REGISTRY_TOKEN }}
+
+      - name: Build and push image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          build-args: |
+            VERSION=${{ env.TAG }}
+            COMMIT=${{ github.sha }}
+            BUILD_TIME=${{ github.event.head_commit.timestamp || github.event.repository.updated_at }}
+          tags: |
+            ${{ env.IMAGE }}:${{ env.TAG }}
+            ${{ env.IMAGE }}:latest
+          labels: |
+            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.version=${{ env.TAG }}

.github/workflows/integration.yml

@@ -12,6 +12,19 @@ jobs:
   integration-test:
     runs-on: ubuntu-latest
 
+    services:
+      postgres:
+        image: postgres:13
+        env:
+          POSTGRES_DB: broker_test
+          POSTGRES_USER: user
+          POSTGRES_PASSWORD: password
+        options: >-
+          --health-cmd="pg_isready -U user"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=10
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -19,16 +32,17 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: '1.26'
           cache: true
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-      
-      - name: Install podman-compose
-        run: pip install podman-compose
-
       - name: Run all tests
-        run: make test-all
+        env:
+          # act_runner runs this job in its own container alongside the
+          # postgres service container, both on the job's Docker network.
+          # "localhost" from inside the job container is the job container
+          # itself, not the runner host, so the service must be reached by
+          # its network alias (the services: key) and container-internal
+          # port -- not a published host port.
+          TEST_DB_HOST: postgres
+          TEST_DB_PORT: 5432
+        run: make test-ci TEST_DB_HOST="$TEST_DB_HOST" TEST_DB_PORT="$TEST_DB_PORT"

.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v5
       with:
-        go-version: '1.25'
+        go-version: '1.26'
         cache: true
 
     - name: Get version from tag

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build clean test test-all test-integration-go test-unit-go test-connection schema-install broker-start broker-stop install deps docker-up docker-down help
+.PHONY: all build clean test test-all test-ci test-integration-go test-unit-go test-connection generate-test-config schema-install broker-start broker-stop install deps docker-up docker-down docker-build release help
 
 # Build variables
 BINARY_NAME=pgsql-broker
@@ -30,9 +30,16 @@ COMPOSE_CMD := $(shell \
 
 
 
+# Test database connection info. Override in CI to point at a dynamically
+# assigned Postgres (e.g. a services: block port), avoiding a fixed host port
+# that can collide with other jobs on a shared runner.
+TEST_DB_HOST ?= 127.0.0.1
+TEST_DB_PORT ?= 5433
+TEST_CONFIG := $(BIN_DIR)/broker.test.runtime.yaml
+
 # Version information
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
-BUILD_TIME=$(shell date -u '+2026-01-02_19:58:30')
+BUILD_TIME=$(shell date -u '+%Y-%m-%d_%H:%M:%S')
 COMMIT=$(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
 
 # Inject version info
@@ -63,28 +70,52 @@ test-local-unit: deps ## Run local unit tests
 	@echo "Running local unit tests..."
 	@$(GO) test -v -race -cover $(shell $(GO) list ./... | grep -v /tests/integration)
 
-test-all: test-teardown test-setup test-connection schema-install broker-start test-local-unit test-integration-go broker-stop test-teardown ## Run all unit and integration tests
+test-all: test-teardown test-setup test-connection schema-install test-local-unit test-integration-go test-teardown ## Run all unit and integration tests (starts its own Postgres via docker-compose)
+
+test-ci: test-connection schema-install test-local-unit test-integration-go ## Run all unit and integration tests against an externally-provided Postgres (CI services: block)
 
 test-connection: deps ## Test database connection with retry
-	@echo "Testing database connection..."
+	@echo "Testing database connection (host=$(TEST_DB_HOST) port=$(TEST_DB_PORT))..."
-	@$(GO) test -v ./tests/integration/connection_test.go
+	@TEST_DB_HOST=$(TEST_DB_HOST) TEST_DB_PORT=$(TEST_DB_PORT) $(GO) test -v -run '^TestConnection$$' ./tests/integration/...
 
-schema-install: build ## Install database schema using the broker CLI
+generate-test-config: ## (internal) render broker.test.yaml with TEST_DB_HOST/TEST_DB_PORT
+	@mkdir -p $(BIN_DIR)
+	@sed -e "s/^    host: .*/    host: $(TEST_DB_HOST)/" -e "s/^    port: .*/    port: $(TEST_DB_PORT)/" broker.test.yaml > $(TEST_CONFIG)
+
+schema-install: build generate-test-config ## Install database schema using the broker CLI
 	@echo "Installing database schema..."
-	@$(BIN_DIR)/$(BINARY_NAME) install --config broker.test.yaml
+	@$(BIN_DIR)/$(BINARY_NAME) install --config $(TEST_CONFIG)
 
-test-setup: build ## Start test environment (docker-compose)
+test-setup: build ## Start test environment (docker-compose/podman-compose)
-	@echo "Starting test environment..."
+	@echo "Starting test environment (using $(COMPOSE_CMD))..."
-	@podman-compose -f tests/docker-compose.yml up -d
+	@if [ "$(CONTAINER_RUNTIME)" = "none" ]; then \
+		echo "Error: Neither Docker nor Podman is installed"; \
+		exit 1; \
+	fi
+	@$(COMPOSE_CMD) -f tests/docker-compose.yml up -d
+	@echo "Waiting for PostgreSQL to be ready..."
+	@for i in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15; do \
+		if $(COMPOSE_CMD) -f tests/docker-compose.yml exec -T postgres pg_isready -U user > /dev/null 2>&1; then \
+			echo "PostgreSQL is ready"; exit 0; \
+		fi; \
+		sleep 2; \
+	done; \
+	echo "ERROR: PostgreSQL did not become ready in time"; \
+	$(COMPOSE_CMD) -f tests/docker-compose.yml logs postgres; \
+	exit 1
 
-test-teardown: ## Stop test environment (docker-compose)
+test-teardown: ## Stop test environment (docker-compose/podman-compose)
-	@echo "Stopping test environment..."
+	@echo "Stopping test environment (using $(COMPOSE_CMD))..."
-	@podman-compose -f tests/docker-compose.yml down -v --rmi all
+	@if [ "$(CONTAINER_RUNTIME)" = "none" ]; then \
-	@sleep 5 # Give Docker time to release resources
+		echo "Neither Docker nor Podman is installed, skipping teardown"; \
+	else \
+		$(COMPOSE_CMD) -f tests/docker-compose.yml down -v --rmi all || true; \
+	fi
+	@sleep 5 # Give the container runtime time to release resources
 
-broker-start: build ## Start the broker in the background
+broker-start: build generate-test-config ## Start the broker in the background
 	@echo "Starting broker..."
-	@setsid $(BIN_DIR)/$(BINARY_NAME) start --config broker.test.yaml > broker.log 2>&1 < /dev/null & echo $$! > broker.pid
+	@setsid $(BIN_DIR)/$(BINARY_NAME) start --config $(TEST_CONFIG) > broker.log 2>&1 < /dev/null & echo $$! > broker.pid
 	@sleep 5 # Give the broker a moment to start
 
 broker-stop: ## Stop the broker
@@ -97,8 +128,8 @@ broker-stop: ## Stop the broker
 	fi
 
 test-integration-go: ## Run Go integration tests
-	@echo "Running Go integration tests..."
+	@echo "Running Go integration tests (host=$(TEST_DB_HOST) port=$(TEST_DB_PORT))..."
-	@$(GO) test -v ./tests/integration/...
+	@TEST_DB_HOST=$(TEST_DB_HOST) TEST_DB_PORT=$(TEST_DB_PORT) $(GO) test -v ./tests/integration/...
 
 install: build ## Install the binary to GOPATH/bin
 	@echo "Installing to GOPATH/bin..."
@@ -172,6 +203,15 @@ docker-down: ## Stop PostgreSQL test database
 	fi
 	@echo "PostgreSQL stopped"
 
+docker-build: ## Build the pgsql-broker runtime image
+	@if [ "$(CONTAINER_RUNTIME)" = "none" ]; then echo "Error: Neither Docker nor Podman is installed"; exit 1; fi
+	@$(CONTAINER_RUNTIME) build \
+		--build-arg VERSION=$(VERSION) \
+		--build-arg COMMIT=$(COMMIT) \
+		--build-arg BUILD_TIME=$(BUILD_TIME) \
+		-t pgsql-broker:$(VERSION) -t pgsql-broker:latest \
+		-f Dockerfile .
+
 release: ## Create and push a new release tag (auto-increments patch version)
 	@echo "Creating new release..."
 	@latest_tag=$$(git describe --tags --abbrev=0 2>/dev/null || echo ""); \

README.md

@@ -264,6 +264,23 @@ See the [examples](./examples/) directory for complete examples.
 
 ## Docker
 
+### Prebuilt image
+
+Published to `git.warky.dev/wdevs/pgsql-broker` on every `v*.*.*` tag (`.github/workflows/docker-release.yml`), tagged with the version and `latest`.
+
+```bash
+docker pull git.warky.dev/wdevs/pgsql-broker:latest
+docker run --rm -v $(pwd)/broker.yaml:/etc/pgsql-broker/broker.yaml:ro git.warky.dev/wdevs/pgsql-broker:latest
+```
+
+Config must be mounted at `/etc/pgsql-broker/broker.yaml` — no config is baked into the image.
+
+### Building the image locally
+
+```bash
+make docker-build   # builds pgsql-broker:<VERSION> and pgsql-broker:latest via Dockerfile
+```
+
 ### Production: `Dockerfile` + `docker-compose.yml`
 
 Multi-stage build (`golang:1.26-alpine` → `alpine:3.22`, static binary, non-root user). The compose stack runs Postgres, a one-shot `migrate` service (`install --with-roles`), then the `broker` service connecting as `broker_runtime`.
@@ -372,7 +389,7 @@ go test -v ./tests/integration/...     # integration tests (needs local Postgres
 docker-compose -f docker-compose.test.yml up --build --abort-on-container-exit --exit-code-from tests
 ```
 
-Integration tests expect Postgres reachable at `localhost:5433` (see `tests/integration/`), including `rls_test.go` (multi-tenant isolation) and `stage5_test.go`.
+Integration tests expect Postgres reachable at `127.0.0.1:5433` (see `tests/integration/`), including `rls_test.go` (multi-tenant isolation) and `stage5_test.go`. `127.0.0.1` is used instead of `localhost` because some CI Docker hosts publish container ports on IPv4 only, and `localhost` can resolve to `::1` first and fail.
 
 ### Project Structure
 

broker.test.yaml

@@ -1,6 +1,6 @@
 databases:
   - name: test
-    host: localhost
+    host: 127.0.0.1
     port: 5433
     database: broker_test
     user: user

pkg/broker/config/config.go

@@ -4,8 +4,8 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/spf13/viper"
 	"git.warky.dev/wdevs/pgsql-broker/pkg/broker/adapter"
+	"github.com/spf13/viper"
 )
 
 // Config holds all broker configuration

pkg/broker/install/install.go

@@ -326,7 +326,7 @@ func execStatements(ctx context.Context, tx adapter.DBTransaction, sqlText strin
 // $$-quoted function bodies intact.
 // splitSQLStatements splits a SQL script into individual statements on
 // top-level semicolons, ignoring semicolons that appear inside single-quoted
-// strings ('...', with '' as an escaped quote), double-quoted identifiers,
+// strings ('...', with ” as an escaped quote), double-quoted identifiers,
 // line comments (--), and dollar-quoted bodies ($$...$$ or $tag$...$tag$).
 func splitSQLStatements(sqlText string) []string {
 	var result []string

pkg/broker/queue/queue.go

@@ -24,16 +24,16 @@ type Queue struct {
 
 // Config holds queue configuration
 type Config struct {
-	Number            int
+	Number       int
-	InstanceID        int64
+	InstanceID   int64
-	WorkerCount       int
+	WorkerCount  int
-	DBAdapter         adapter.DBAdapter
+	DBAdapter    adapter.DBAdapter
-	Logger            adapter.Logger
+	Logger       adapter.Logger
-	BufferSize        int
+	BufferSize   int
-	TimerSeconds      int
+	TimerSeconds int
-	FetchSize         int
+	FetchSize    int
-	TenantID          string
+	TenantID     string
-	LeaseSeconds      int
+	LeaseSeconds int
 }
 
 // New creates a new queue manager

pkg/broker/worker/worker.go

@@ -218,7 +218,7 @@ func (w *Worker) processJobs(ctx context.Context) {
 
 		if jobID <= 0 {
 			tx.Rollback() // No job found, rollback
-			return         // No more jobs
+			return        // No more jobs
 		}
 
 		// Run the job

tests/integration/connection_test.go

@@ -2,6 +2,7 @@ package integration
 
 import (
 	"database/sql"
+	"fmt"
 	"testing"
 	"time"
 
@@ -10,7 +11,7 @@ import (
 )
 
 func TestConnection(t *testing.T) {
-	connStr := "user=user password=password dbname=broker_test port=5433 sslmode=disable"
+	connStr := fmt.Sprintf("user=user password=password dbname=broker_test host=%s port=%d sslmode=disable", testDBHost(), testDBPort())
 	var db *sql.DB
 	var err error
 

tests/integration/rls_test.go

@@ -3,6 +3,7 @@ package integration
 import (
 	"context"
 	"database/sql"
+	"fmt"
 	"testing"
 
 	_ "github.com/lib/pq"
@@ -47,7 +48,7 @@ func TestRLSTenantIsolation(t *testing.T) {
 	}
 
 	runtimeDB, err := sql.Open("postgres",
-		"user=test_broker_runtime password=test-pass dbname=broker_test host=localhost port=5433 sslmode=disable options='-c search_path=broker,public'")
+		fmt.Sprintf("user=test_broker_runtime password=test-pass dbname=broker_test host=%s port=%d sslmode=disable options='-c search_path=broker,public'", testDBHost(), testDBPort()))
 	require.NoError(t, err)
 	defer runtimeDB.Close()
 	require.NoError(t, runtimeDB.Ping())

tests/integration/stage5_test.go

@@ -3,6 +3,7 @@ package integration
 import (
 	"context"
 	"database/sql"
+	"fmt"
 	"log/slog"
 	"testing"
 	"time"
@@ -14,11 +15,13 @@ import (
 	"git.warky.dev/wdevs/pgsql-broker/pkg/broker/install"
 )
 
-const stage5ConnStr = "user=user password=password dbname=broker_test host=localhost port=5433 sslmode=disable"
+func stage5ConnStr() string {
+	return fmt.Sprintf("user=user password=password dbname=broker_test host=%s port=%d sslmode=disable", testDBHost(), testDBPort())
+}
 
 func newStage5Adapter(logger adapter.Logger) *adapter.PostgresAdapter {
 	return adapter.NewPostgresAdapter(adapter.PostgresConfig{
-		Host: "localhost", Port: 5433, Database: "broker_test",
+		Host: testDBHost(), Port: testDBPort(), Database: "broker_test",
 		User: "user", Password: "password", SSLMode: "disable",
 		MaxOpenConns: 10, MaxIdleConns: 2,
 		ConnMaxLifetime: 5 * time.Minute, ConnMaxIdleTime: 10 * time.Minute,
@@ -30,7 +33,7 @@ func newStage5Adapter(logger adapter.Logger) *adapter.PostgresAdapter {
 func setupStage5Schema(t *testing.T) *sql.DB {
 	t.Helper()
 
-	db, err := connectWithRetry(stage5ConnStr, 10, 2*time.Second)
+	db, err := connectWithRetry(stage5ConnStr(), 10, 2*time.Second)
 	require.NoError(t, err)
 
 	cleanupSchema(t, db)

tests/integration/testconfig_test.go

@@ -0,0 +1,26 @@
+package integration
+
+import (
+	"os"
+	"strconv"
+)
+
+// testDBHost and testDBPort let CI point the integration suite at a
+// dynamically-assigned Postgres (TEST_DB_HOST/TEST_DB_PORT), avoiding a fixed
+// host port that can collide with other jobs on a shared runner. Local dev
+// keeps working unset, defaulting to the docker-compose test stack.
+func testDBHost() string {
+	if h := os.Getenv("TEST_DB_HOST"); h != "" {
+		return h
+	}
+	return "127.0.0.1"
+}
+
+func testDBPort() int {
+	if p := os.Getenv("TEST_DB_PORT"); p != "" {
+		if n, err := strconv.Atoi(p); err == nil {
+			return n
+		}
+	}
+	return 5433
+}

tests/integration/workflow_test.go

@@ -3,6 +3,7 @@ package integration
 import (
 	"context"
 	"database/sql"
+	"fmt"
 	"log/slog"
 	"testing"
 	"time"
@@ -27,7 +28,7 @@ func TestBrokerWorkflow(t *testing.T) {
 	ctx := context.Background()
 
 	// Database connection string
-	connStr := "user=user password=password dbname=broker_test host=localhost port=5433 sslmode=disable"
+	connStr := fmt.Sprintf("user=user password=password dbname=broker_test host=%s port=%d sslmode=disable", testDBHost(), testDBPort())
 
 	// Connect to database with retry logic
 	db, err := connectWithRetry(connStr, 10, 2*time.Second)
@@ -43,8 +44,8 @@ func TestBrokerWorkflow(t *testing.T) {
 
 	// Create database adapter
 	postgresConfig := adapter.PostgresConfig{
-		Host:            "localhost",
+		Host:            testDBHost(),
-		Port:            5433,
+		Port:            testDBPort(),
 		Database:        "broker_test",
 		User:            "user",
 		Password:        "password",
@@ -78,8 +79,8 @@ func TestBrokerWorkflow(t *testing.T) {
 		Databases: []config.DatabaseConfig{
 			{
 				Name:       "test_db",
-				Host:       "localhost",
+				Host:       testDBHost(),
-				Port:       5433,
+				Port:       testDBPort(),
 				Database:   "broker_test",
 				User:       "user",
 				Password:   "password",