feat(postgres): initial stable release v0.9.0

pgx v5-native PostgreSQL client with launcher lifecycle, health check, unit-of-work via context injection, and structured error mapping.

What's included:
- Executor / Tx / Client / Component interfaces using pgx native types (pgconn.CommandTag, pgx.Rows, pgx.Row)
- New(logger, cfg) constructor; pgxpool initialised in OnInit
- Config struct with env-tag support for all pool tuning parameters
- UnitOfWork via context injection; GetExecutor(ctx) returns active Tx or pool
- HandleError mapping pgerrcode constants to xerrors codes (AlreadyExists, InvalidInput, NotFound, Internal)
- health.Checkable at LevelCritical; HealthCheck delegates to pgxpool.Ping

Tested-via: todo-api POC integration
Reviewed-against: docs/adr/

errors.go

@@ -0,0 +1,38 @@
+package postgres
+
+import (
+	"errors"
+
+	"github.com/jackc/pgerrcode"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+
+	"code.nochebuena.dev/go/xerrors"
+)
+
+// HandleError maps pgx and PostgreSQL errors to xerrors types.
+// Also available as client.HandleError(err).
+func HandleError(err error) error {
+	if err == nil {
+		return nil
+	}
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) {
+		switch pgErr.Code {
+		case pgerrcode.UniqueViolation:
+			return xerrors.New(xerrors.ErrAlreadyExists, "record already exists").
+				WithContext("constraint", pgErr.ConstraintName).WithError(err)
+		case pgerrcode.ForeignKeyViolation:
+			return xerrors.New(xerrors.ErrInvalidInput, "data integrity violation").
+				WithContext("table", pgErr.TableName).WithError(err)
+		case pgerrcode.CheckViolation:
+			return xerrors.New(xerrors.ErrInvalidInput, "data constraint violation").
+				WithContext("table", pgErr.TableName).
+				WithContext("column", pgErr.ColumnName).WithError(err)
+		}
+	}
+	if errors.Is(err, pgx.ErrNoRows) {
+		return xerrors.New(xerrors.ErrNotFound, "record not found").WithError(err)
+	}
+	return xerrors.New(xerrors.ErrInternal, "unexpected database error").WithError(err)
+}