Subscribe mechanics

[djthorpe]

This pull request introduces a major update to error handling and notification subscription APIs in the package, improving ergonomics, safety, and observability. The most significant changes include a new, higher-level Subscribe API for PostgreSQL notifications, a comprehensive overhaul of error normalization and classification, and the addition of robust tests and documentation for these features.

Notification Subscription Improvements:

• Introduced a new Subscribe method on pool-backed connections, providing a callback-based interface for listening to PostgreSQL notifications. This API manages the listener lifecycle, ensures cleanup, and is now the recommended approach for asynchronous notifications. (conn.go [1] pool.go [2] listener.go [3] README.md [4] [5]
• Enforced that Subscribe is only available on pool-backed connections; calling it on transactional or bulk connections returns a typed error. (conn.go [1] bulk.go [2]
• Improved resource cleanup for listeners and subscriptions, including context-based shutdown and timeouts. (listener.go [1] [2] pkg/queue/task.go [3] pool.go [4] [5] [6]

Error Handling Overhaul:

• Replaced the old err.go with a new error.go that introduces typed errors for common PostgreSQL conditions (e.g., not found, conflict, constraint violations), a DatabaseError type for detailed SQLSTATE inspection, and helper functions for error normalization and classification. (error.go [1] removes err.go [2]
• Updated documentation to describe new error types, normalization, and usage patterns for robust error handling in client code. (README.md README.mdL453-R511)

Testing and Documentation:

• Added comprehensive unit tests for error normalization, SQLSTATE handling, and error classification to ensure correctness and future maintainability. (error_test.go error_test.goR1-R66)
• Improved and clarified documentation for both the notification and error handling APIs, guiding users toward best practices. (README.md [1] [2] [3]

These changes make the package safer, more idiomatic, and easier to use for both notification handling and error management.

[Copilot]

Pull request overview

This PR introduces a higher-level Subscribe API for PostgreSQL LISTEN/NOTIFY built on pool-backed dedicated listener connections, and expands the error model to normalize driver errors into typed package errors.

Changes:

• Add pool-managed subscription tracking so pool.Close()/Reset() cancels active subscriptions and waits for callback shutdown.
• Add Conn.Subscribe(...) (supported only on pool-backed connections) and document the preferred subscription API.
• Replace the previous minimal error wrapper with NormalizeError, SQLState, and typed PostgreSQL error kinds, plus tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
subscription.go	Adds internal subscription primitives (subscriptionArray) used to coordinate cancellation and shutdown.
pool.go	Tracks active subscriptions in the pool; Close() now cancels/waits before closing the underlying pgxpool.
listener.go	Implements subscribe() helper and listener cleanup to run background notification callbacks.
conn.go	Adds Subscribe to the Conn interface and returns ErrNotAvailable for non-pool-backed conns.
bulk.go	Explicitly disables Subscribe for bulk connections with ErrNotAvailable.
pool_test.go	Adds tests for Subscribe behavior and pool shutdown waiting semantics.
pkg/queue/task.go	Improves listener close behavior by using a bounded shutdown context.
error.go	Introduces typed database errors, SQLSTATE mapping, and NormalizeError utilities.
error_test.go	Adds tests for NormalizeError/SQLSTATE behavior.
README.md	Documents Subscribe as the recommended API and expands error-handling documentation.
err.go	Removes the previous minimal error definition in favor of the new error system.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.