Skip to main content

API + DB + Worker

Use this when your stack has synchronous API calls and asynchronous background jobs sharing one database.

Baseline config​

{
  "services": {
    "db": {
      "cmd": ["postgres", "-D", "./var/db"],
      "port": 5432,
      "ready": {"type": "tcp"}
    },
    "api": {
      "cmd": ["go", "run", "./cmd/api"],
      "dependsOn": ["db"],
      "port": 3000,
      "ready": {
        "type": "http",
        "url": "http://127.0.0.1:3000/health"
      }
    },
    "worker": {
      "cmd": ["go", "run", "./cmd/worker"],
      "dependsOn": ["db"]
    }
  }
}

Why it works​

  • DB startup is isolated and gated by TCP readiness.
  • API and worker share one hard dependency (db) and can start in parallel afterward.
  • API readiness prevents downstream consumers from racing an unready endpoint.

Common adjustments​

  • add session.bind and session.token when you need remote TUI access
  • add service-specific logView.maxEntries for chatty workers
  • use stopCmd for graceful job-drain before shutdown

Failure modes​

  • API depends on worker and worker depends on API: cycle
  • DB has no readiness gate: API starts too early and fails repeatedly
  • worker declared as dependency for API even when not required for API startup

For readiness and dependency details, see Readiness and Waves.