Upgrades

Channels

Puddle’s image comes in two channels (the tags are in Choosing a version):

• Releases (x.y.z, the newest also latest and stable): what to run for anything you keep. A release is a build of main, tagged as is. Versions are semantic and only go up: a fix ships as a new release from main, never as a backport to an older one, so upgrading means moving to a newer release.
• Builds of main (main, each also sha-<commit>): every push to main that passes its checks. For a test instance that follows what’s next.

Both work with dependency bots. A release is a plain version tag; a build of main is followed by digest: pin the main tag with the digest you run, and the bot moves the digest when main moves.

# The production instance: a release, bumped through reviewed PRs.
image: ghcr.io/ragnard/puddle:0.2.0

# The test instance: main's newest build, by digest.
image: ghcr.io/ragnard/puddle:main@sha256:<digest>

With Renovate, the default Docker manager handles both; to merge the test instance’s digest updates without review:

{
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "matchPackageNames": ["ghcr.io/ragnard/puddle"],
      "matchCurrentValue": "main",
      "automerge": true
    }
  ]
}

Dependabot’s docker (or docker-compose) ecosystem does the same: it bumps a release’s version tag, and the digest of a main@sha256:... reference.

Before upgrading to a new release, read its notes on the releases page: until the first public release, an upgrade may need the steps below.

Before the first public release

Puddle is pre-release. Until the first public release:

• There are no migrations between versions. Puddle’s database schemas (SQLite and PostgreSQL) change in place from one build to the next. A new build may not start against a database an older build created, or may misbehave with it. To upgrade, stop puddle, recreate the metastore (a new SQLite file, or drop the Postgres schema), and start the new build; then register the tables you want to keep from their current metadata files (register-table), since the warehouse’s files are unaffected.
• Configuration changes without deprecations. A renamed or removed setting is an error at startup (unknown keys are rejected); the configuration reference of the version you deploy is the one that applies.
• Backups restore only into the build that took them.

From the first public release on, schema changes ship as versioned migrations that puddle applies at startup: under a PostgreSQL advisory lock, so replicas starting together apply them once, and with a downgrade guard, so an older build refuses to start against a database a newer build has migrated.