docs: update worker-upgrades runbook for binary split + admin pinning API#512
Merged
Conversation
… API Two pieces of the runbook went stale during the recent binary-split work: 1. The "canary a new build" instructions still recommended direct `UPDATE duckgres_managed_warehouses SET image=...` SQL against the config store. PR #506 replaced that with `PATCH /api/v1/orgs/:id/warehouse/pinning` (row-locked transaction, audit trail, no DB shell required). Updates every example to use the API endpoint and explicitly tells operators not to use SQL. 2. The image format was the all-in-one `posthog/duckgres:vX.Y.Z`. PRs #500-#503 split that into a per-DuckDB-version `duckgres-worker` matrix. Updates examples to the new `ghcr.io/posthog/duckgres-worker:<sha>-duckdb<version>` shape and adds a tag-conventions table covering both GHCR and the ECR mirror (provisioned in posthog-cloud-infra#7848). Adds two new sections: - "Available Worker Builds" — explains the matrix CD, shows operators how to list current ECR / GHCR tags, and explains why pinning a non-default DuckDB version requires a specific `<sha>-duckdb<version>` tag (no `latest-duckdb<version>` convention exists). - "Reverting a Pin" — documents the empty-string semantics for clearing back to the global default, with a caution that clearing `ducklake_version` does NOT downgrade an already-migrated tenant (one-way door from the existing CAUTION block). Also fixes the spec-version format in examples (it's `major.minor` only — "0.4" / "1.0" / "1.1" — matching the validator added in #506) and adds a "Background" section linking back to the binary-split PRs so future maintainers understand the two-image story. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two pieces of
docs/runbooks/worker-upgrades.mdwent stale during the recent binary-split work. This PR brings the runbook back in sync with what landed.What was wrong
imagefield for the target org in the Config Store database" and showed a literalUPDATE duckgres_managed_warehouses SET image=.... PR feat(admin): PATCH /orgs/:id/warehouse/pinning for tenant image+ducklake #506 replaced that with a row-locked admin endpoint:PATCH /api/v1/orgs/:id/warehouse/pinning. Direct SQL bypasses the transaction lock so concurrent operator mutations can clobber each other.posthog/duckgres:vX.Y.Z— but PRs feat(cmd/duckgres-worker): add a worker-only entry point that ships libduckdb #500-feat: add Dockerfile.controlplane for the duckdb-free CP image #503 split that into a per-DuckDB-versionduckgres-workermatrix CD producingghcr.io/posthog/duckgres-worker:<sha>-duckdb<version>(and the ECR mirror provisioned in posthog-cloud-infra#7848).Changes
PATCH /api/v1/orgs/:id/warehouse/pinningendpoint withcurl+ bearer-token shape, and an explicit "do not run direct UPDATE SQL" note.gh apiandaws ecr list-imagessnippets to enumerate what's currently in the registry, and an explanation of why pinning a non-default DuckDB version requires a specific<sha>-duckdb<version>tag (there's nolatest-duckdb<version>convention).ducklake_versiondoes NOT downgrade an already-migrated tenant (one-way door — already noted elsewhere in the doc).ducklake_versionformat in examples tomajor.minoronly ("0.4", "1.0", "1.1") matching the validator added in feat(admin): PATCH /orgs/:id/warehouse/pinning for tenant image+ducklake #506.Test plan
Doc-only — no code changes. CI lint should pass; no test impact.
🤖 Generated with Claude Code