Skip to main content

V2 removes the compatibility layer that v1 kept for v0 callers, folds result storage into every driver, and merges the two worker observer interfaces. Stored jobs are compatible: run Migrate once and existing rows keep working.

1. Update import paths#

Every module gains a /v2 suffix. The root module puts it after the module root; nested modules put it at the end of their own path:

v1v2
github.com/kirimatt/goncordiagithub.com/kirimatt/goncordia/v2
github.com/kirimatt/goncordia/coregithub.com/kirimatt/goncordia/v2/core
github.com/kirimatt/goncordia/driver/memorygithub.com/kirimatt/goncordia/v2/driver/memory
github.com/kirimatt/goncordia/driver/pgxv5github.com/kirimatt/goncordia/driver/pgxv5/v2
github.com/kirimatt/goncordia/otelgithub.com/kirimatt/goncordia/otel/v2
github.com/kirimatt/goncordia/gontestgithub.com/kirimatt/goncordia/gontest/v2

The same rule applies to driver/stdlib, driver/mongodb, driver/redis, driver/cassandra, driver/clickhouse, driver/dynamodb, driver/firestore, driver/gorm, and driver/bun.

2. Run Migrate#

Every driver now stores future results. Migrate adds goncordia_job_results (SQL migration 008, Cassandra, ClickHouse, DynamoDB). MongoDB, Firestore, and Redis need no schema change.

3. Replace removed APIs#

RemovedUse instead
WorkerPool.Stop()WorkerPool.Shutdown(ctx), which reports whether the drain finished
ClientConfig.NowClientConfig.Clock
core.WorkerOpts.Queue (had no effect)InsertOpts.Queue or ClientConfig.DefaultQueue
QueuePolicy.RateLimit / RatePeriodQueuePolicy.RateLimits: []QueueRateLimit{{Limit: n, Period: p, Burst: n}}
clock.Mock, clock.NewMockclock.Manual, clock.NewManual
internal/clockclock
gontest.Jobs (dropped decode errors), gontest.JobsEgontest.Jobs, which now returns ([]*core.Job[T], error)
WorkerLifecycleObserverWorkerObserver, which now has all six methods

4. Observers#

WorkerObserver now includes JobStarted, JobFinished, and JobRateLimited. Embed goncordia.NopWorkerObserver to implement only the events you need, and combine observers with goncordia.WorkerObservers:

5. Custom drivers and clocks#

  • driver.Executor (and ExecutorTx) now embeds driver.JobResultStore: implement JobResultPut, JobResultGet (return driver.ErrNotFound when absent), and JobResultDelete, and delete a job’s result in JobDelete. drivertest.RunResults checks the contract.
  • clock.Clock now requires NewTimer(time.Duration) clock.Timer.

6. MongoDB on mongo-driver v2#

driver/mongodb stays on the deprecated mongo-driver v1. The new driver/mongodbv2 module uses mongo-driver v2 and the same collections, so processes can switch one at a time:

7. Unchanged#

Database schemas other than the new results table, job payloads, metric and span names, and the OpenTelemetry instrumentation scope (github.com/kirimatt/goncordia) stay the same, so dashboards and alerts keep working.