Skip to content

v2.0.3

Pre-release
Pre-release

Choose a tag to compare

View all tags
@github-actions github-actions released this 22 Jul 05:40
v2.0.3
5d7bf7c

v2.0.3 - Fail-Fast Database Bootstrap

Development prerelease. This release is published from dev, may receive
rapid follow-up changes, and is not selected by the default latest image.

Summary

v2.0.3 serializes every startup-time MySQL schema and configuration mutation
under one connection-scoped advisory lock. Migration ledger corruption,
missing recorded schema objects, legacy cleanup failures, baseline migration
failures, versioned migration failures, and default-configuration failures now
stop the server before it accepts traffic.

No new checksummed schema version, image-processing recipe, or upload API is
introduced. This release changes how existing bootstrap work is coordinated,
validated, and reported.

Mandatory First-Upgrade Procedure

Stop every backend instance running v2.0.2 or earlier before starting the first
v2.0.3 instance. Do not use a rolling deployment that overlaps old and new
binaries. Older binaries perform legacy cleanup, baseline AutoMigrate, and
configuration seeding outside the advisory lock now owned by v2.0.3.

After one v2.0.3 instance completes database bootstrap successfully, other
v2.0.3 instances may start normally. They serialize through the same
database-scoped lock.

Changes

Serialized startup bootstrap

  • Replaced four independent startup calls with one
    BootstrapDatabase(ctx, db) entry point.
  • Reserves one physical SQL connection, acquires the MySQL advisory lock on
    that connection, and keeps both through ledger validation, legacy token
    cleanup, baseline migration, versioned migrations, and default seeding.
  • Uses clean GORM sessions for baseline migration and seeding while retaining
    the pinned physical connection.
  • Propagates caller context while waiting for the lock and executing database
    work, and uses a bounded cleanup context when releasing the lock.
  • Returns every stage error to main; the HTTP server no longer starts after a
    partially failed bootstrap.

Migration integrity and recovery

  • Validates known versions, version continuity, migration names, and immutable
    SHA-256 checksums before destructive legacy work.
  • Verifies that columns, indexes, tables, and the capacity-lock seed represented
    by applied ledger entries still exist.
  • Keeps pending operations retry-safe when MySQL has committed some DDL but the
    corresponding ledger entry was not written.
  • Documents that MySQL DDL commits implicitly. Bootstrap recovery is based on
    serialization, object probes, idempotent operations, and retry rather than a
    transaction rollback promise.

Legacy token and configuration compatibility

  • Inspects all four legacy access-token columns in one pass and removes every
    residual legacy column with one ALTER TABLE statement.
  • Deletes incompatible legacy token rows only when token_hash is still
    present. A partially migrated table without that hash keeps modern token
    rows while its remaining old columns are removed.
  • Seeds required configuration with conflict-safe inserts that never overwrite
    administrator values and now reports query or insert failures.
  • Copies the former admin key image_token_default_ttl to the canonical
    private_token_ttl_default_ms key when needed, without overwriting an
    existing canonical value.
  • Corrected the admin web UI to read and write the canonical private-token TTL
    key used by the backend.

Continuous integration

  • Added a pinned MySQL 8.4.10 service to the backend CI job.
  • Added a required real-MySQL bootstrap suite. CI fails instead of silently
    skipping the suite when its DSN is missing.
  • Covers a one-connection pool, repeated bootstrap, full and partial legacy
    token states, invalid and inconsistent ledgers, context cancellation,
    concurrent starters, retry after partially committed DDL, configuration-key
    compatibility, seed failure propagation, and advisory-lock release.
  • Normalized direct Go dependency declarations without changing dependency
    versions.

Verification

  • MySQL 8.4.10 bootstrap integration: 9 scenarios passed.
  • Backend go test ./... -count=1: passed.
  • Backend go vet ./...: passed.
  • Backend go build ./...: passed.
  • Frontend ESLint: passed.
  • Frontend Vitest: 17 test files, 131 tests passed.
  • TypeScript project and Vite production build: passed.
  • Python requirements lock and release-image policy tests: passed.
  • GitBook documentation and translation source-hash verification: passed.
  • The existing wasm-vips direct-eval dependency warning remains unchanged and
    does not fail the build.

Installation

Development images must be pulled explicitly:

docker pull jaykserks/summerain:dev-v2.0.3

Equivalent exact development tag:

jaykserks/summerain:dev-2.0.3

The moving dev tag also points to the newest successful development build.
latest, main, and stable semantic-version aliases are not changed by this
release.

Known Limitations

  • Applied-object validation proves that recorded objects exist; it does not
    compare every column type, default, index column order, constraint, or table
    option with the migration definition.
  • MySQL DDL cannot be transactionally rolled back by this bootstrap. Correct a
    reported failure and restart so idempotent probes can converge the schema.
  • The advisory-lock wait is bounded at 60 seconds. Large historical DDL may
    require an upgrade maintenance window that accommodates startup time.
  • The legacy image_token_default_ttl row is retained for compatibility after
    its value is copied. Runtime reads and new admin writes use only the canonical
    key.
  • Animated image support remains planned for a later release.
Assets 2
Loading