# Revision history for pgmq-effectful
## 0.4.0.0 -- 2026-07-14
* Version bump only — coordinated release with pgmq-migration 0.4.0.0.
No library source changes since 0.3.0.0; the test suite was updated for the
native `pgmq-migration` API.
* Bumped `pgmq-core` and `pgmq-hasql` dependency bounds to `>=0.4 && <0.5`.
## 0.3.0.0 -- 2026-05-31
### Breaking Changes
* Now requires the `hs-opentelemetry` 1.0 package family and
`hs-opentelemetry-semantic-conventions` 1.40 (previously the 0.x
series). Downstream projects must upgrade their OpenTelemetry
dependencies to build against this release.
### New Features
* `Pgmq.Effectful.Telemetry` re-exports the stable semantic-convention
attribute keys `messaging_operation_name`, `messaging_operation_type`,
`db_system_name`, and `db_operation_name`.
* The traced interpreter now honours `OTEL_SEMCONV_STABILITY_OPT_IN` to
choose old, stable, or duplicate messaging and database attributes.
The default remains compatible with the v1.24 attributes emitted by
0.2.0.0. Use `OTEL_SEMCONV_STABILITY_OPT_IN=messaging,database` for
stable-only attributes (`messaging.operation.name`,
`messaging.operation.type`, `db.system.name`, `db.operation.name`),
or `messaging/dup,database/dup` to emit both old and stable names
during migration.
## 0.2.0.0 -- 2026-04-23
### Breaking Changes
* **OpenTelemetry semantic conventions updated to spec v1.24.** The
traced interpreter now emits attribute names compliant with
OpenTelemetry Semantic Conventions
[v1.24](https://github.com/open-telemetry/semantic-conventions/tree/v1.24.0),
sourced as typed `AttributeKey` values from the
[`hs-opentelemetry-semantic-conventions`](https://hackage.haskell.org/package/hs-opentelemetry-semantic-conventions)
library. Breaking consequences:
* `messaging.operation.type` → `messaging.operation`. Values change
from the post-v1.24 vocabulary (`"send"`, `"receive"`) to the
v1.24 vocabulary (`"publish"`, `"receive"`). Note the verb change:
`send` → `publish`.
* `db.operation.name` → `db.operation`. Values are the pgmq SQL
function name (`"pgmq.send"`, `"pgmq.read"`, `"pgmq.archive"`, …),
not the previous free-form label.
* `messaging.destination.routing_key` (ad-hoc, not in v1.24) is
gone. Topic-send operations now emit the routing key as
`messaging.destination.name`, since for pgmq topics the routing
key is the logical destination. `ValidateRoutingKey`,
`ValidateTopicPattern`, and `TestRouting` no longer emit a
routing-key attribute at all.
* Span names changed from `"pgmq <op>"` to the v1.24
`"<operation> <destination>"` form. Examples:
`"pgmq send"` → `"publish my-queue"`,
`"pgmq read"` → `"receive my-queue"`,
`"pgmq archive"` → `"pgmq.archive my-queue"`,
`"pgmq list_queues"` → `"pgmq.list_queues"`.
* Queue management operations (`createQueue`, `dropQueue`,
`createPartitionedQueue`, `createUnloggedQueue`) moved from
`Producer` span kind to `Internal`. v1.24 reserves `Producer` for
message publishes; queue administration is not a publish.
* Span status on failure now carries a short non-PII label
(`"pool.acquisition_timeout"`, `"pool.connection.networking"`,
`"pool.session.statement"`, …) instead of the raw `show` of
`UsageError` (which bakes in SQL text and parameter values).
Full detail remains on the standard `exception` event via
`OpenTelemetry.Trace.Core.recordException`.
Dashboards, saved queries, and alerts keyed on the old attribute
names or span-name format need to be updated.
* **Trace context propagation now uses the tracer provider's
configured propagator** (W3C by default, but B3 / Datadog / … work
out of the box when the provider is configured with them). The old
implementation hard-wired `hs-opentelemetry-propagator-w3c`.
* `Pgmq.Effectful.Telemetry.injectTraceContext` / `extractTraceContext`
take a `TracerProvider` (previously an `OTel.Span` / raw carrier).
* `Pgmq.Effectful.Telemetry.TraceHeaders` is now
`Network.HTTP.Types.RequestHeaders` (case-insensitive header names),
matching the carrier type every propagator uses. The previous
`[(ByteString, ByteString)]` alias is gone.
* `Pgmq.Effectful.Traced.sendMessageTraced` takes a `TracerProvider`.
* `Pgmq.Effectful.Traced.readMessageWithContext` takes a
`TracerProvider` and now returns
`Vector (Message, OpenTelemetry.Context.Context)`.
Callers that specifically need the raw `SpanContext` can recover
it via `Context.lookupSpan >>= getSpanContext`.
* Two new helpers, `traceHeadersToJson` and `jsonToTraceHeaders`,
handle the pgmq-over-jsonb serialization boundary.
The `hs-opentelemetry-propagator-w3c` dependency was dropped from
the library; the SDK still installs the W3C propagator as the
default.
* Renamed the interpreter error type from `PgmqError` to
`PgmqRuntimeError` and replaced its opaque `PgmqPoolError UsageError`
constructor with three structured constructors:
data PgmqRuntimeError
= PgmqAcquisitionTimeout
| PgmqConnectionError Hasql.Errors.ConnectionError
| PgmqSessionError Hasql.Errors.SessionError
The old `PgmqError`/`PgmqPoolError` names are retained with a
DEPRECATED pragma and will be removed in 0.3.0.0.
* `runPgmq`'s error constraint changed from `Error PgmqError :> es` to
`Error PgmqRuntimeError :> es`. Update any
`runError @PgmqError` annotation to `runError @PgmqRuntimeError`.
* `runPgmqTraced` and `runPgmqTracedWith` now require
`Error PgmqRuntimeError :> es`. Previously they had *no* error
constraint and threw a `fail`-derived `IOError` outside the Error
effect channel, which meant any `runError` wrapper around a traced
program was a no-op. Code that relied on that silent swallowing now
receives typed errors; update call sites to wrap with
`runError @PgmqRuntimeError`.
### New Features
* `fromUsageError :: Hasql.Pool.UsageError -> PgmqRuntimeError` —
convert raw hasql-pool errors into the pgmq-effectful error type.
Useful when layering `pgmq-effectful` over code that already calls
`Pool.use` directly.
* `isTransient :: PgmqRuntimeError -> Bool` — classification helper for
retry logic. Returns True for acquisition timeouts, networking
connection errors, unrecognized libpq connection errors, and
session-level connection drops; False for authentication,
compatibility, missing-types, statement, script, and driver errors.
* New test suite `pgmq-effectful-test` asserts that both interpreters
surface typed `PgmqRuntimeError` values through the Error channel.
### Migration Guide
Before:
import Pgmq.Effectful (PgmqError (..), runPgmq)
handler =
runEff . runError @PgmqError . runPgmq pool $ action
After:
import Pgmq.Effectful (PgmqRuntimeError (..), runPgmq)
handler =
runEff . runError @PgmqRuntimeError . runPgmq pool $ action
For retry logic:
import Pgmq.Effectful (isTransient)
retryIfTransient action = do
result <- runError @PgmqRuntimeError action
case result of
Right a -> pure (Right a)
Left (_, err)
| isTransient err -> retryIfTransient action
| otherwise -> pure (Left err)
## 0.1.3.0 -- 2026-03-12
### Other Changes
* Update repository homepage URL to shinzui/pgmq-hs
## 0.1.2.0 -- 2026-03-03
* Version bump only (no changes)
## 0.1.1.0 -- 2026-02-23
### New Features
* Effectful effects and interpreters for pgmq 1.11.0 topic routing operations
* Topic management: `bindTopic`, `unbindTopic`, `validateRoutingKey`, `validateTopicPattern`, `testRouting`, `listTopicBindings`, `listTopicBindingsForQueue`
* Topic sending: `sendTopic`, `sendTopicWithHeaders`, `batchSendTopic`, `batchSendTopicForLater`, `batchSendTopicWithHeaders`, `batchSendTopicWithHeadersForLater`
* Notification management: `listNotifyInsertThrottles`, `updateNotifyInsert`
## 0.1.0.0 -- 2026-02-21
* Initial release
* Effectful effects and interpreters for all pgmq operations
* OpenTelemetry instrumentation via traced interpreter
* Support for pgmq 1.5.0 through 1.10.0 features