ROADMAP.md

Norm Roadmap

This document tracks planned work. Items are grouped by area. Checked items are implemented and covered by e2e tests.

Core & Stability

• PGX v5 + pgxpool integration, context-based ops, graceful shutdown
• Config with pooling, timeouts, statement cache capacity
• Health checks (SELECT 1)
• Retry attempts + backoff (exponential with jitter)
• Circuit breaker (open/half-open/closed) with metrics

Migration Engine

• Struct tag parsing (db, orm) including PK, unique, not_null, default, index, FK, version
• Create table, add column if not exists, indexes, foreign keys
• Idempotency via checksum in schema_migrations
• Transactional migrations with pg_advisory_xact_lock
• Plan/preview API with diff against information_schema
• Identifier quoting for DDL
• Rename detection via norm:"rename:old_name" (safe plan)
• Type and nullability change warnings + unsafe statements
• Manual migrations: file-based SQL (Up/Down)
• Go-based migration helpers (functions)
• Rollback: down-runner with safety gates
• Drop/rename column plan (diff) with explicit opt-in guards (apply-time)
• Table drop/rename planning (explicit opt-in)
• Index/constraint drop diffing (apply-time opt-in)
• Detailed plan formatting (grouping by table, severity)

Query Builder

• Fluent Select/Where/Join/OrderBy/Limit/Offset
• Raw with ? to $n placeholder conversion
• First/Last, Delete chain methods
• Insert/Update with RETURNING, ON CONFLICT DO UPDATE
• Condition DSL (Eq/Ne/Gt/Ge/Lt/Le/In/And/Or)
• Keyset pagination (After/Before)
• Struct ops: InsertStruct, UpdateStructByPK
• Identifier-quoting helpers in builder API (safe column/table refs) (e2e covered)
• Named parameters support (WhereNamed, RawNamed) (e2e covered)
• Prebuilt common scopes (e.g., by date ranges) (e2e covered)

Repository & Transactions

• Generic CRUD (Create/Update/Delete/Find/Count/Exists)
• Partial updates, bulk inserts (CreateBatch, copy support placeholder)
• Soft delete with default scoping (WithTrashed, OnlyTrashed, Restore, PurgeTrashed)
• Optimistic locking (norm:"version")
• Transactions (TxManager, transaction-bound QueryBuilder)
• Auto route read operations to read-replica pool; writes to primary
• Upsert helpers in repository (e2e covered)
• Eager/lazy loading helpers (e2e covered)

Read/Write Splitting & Caching

• Optional read pool via ReadOnlyConnString + QueryRead() (e2e covered)
• Auto read routing + overrides (UsePrimary, UseReadPool) (e2e covered)
• Cache integration hooks (read-through/write-through) (docs only, minimal no-op default)
• Cache invalidation on write/tx commit (opt-in via WithInvalidateKeys)

Observability & Logging

• Metrics/Logger interfaces
• Basic query duration metric calls in builder
• Structured logging with context fields, correlation IDs
• Slow query logging with threshold and parameter masking
• Built-in metrics adapter examples (expvar)

Security & Production

• SQL injection safety via parameterization
• Audit logging hook points
• RLS helpers (session vars, SET ROLE helpers)

Testing & Tooling

• Makefile to run Postgres in Docker + e2e suite
• Comprehensive e2e tests for migrations, CRUD, soft delete, tx, builder, pagination, DSL, struct ops
• Migration diff tests (rename/type/nullability) and quoting
• E2E tests for read pool via QueryRead()
• E2E tests for auto read routing + retry policies (idempotency cases)
• Lint and coverage targets; example CI workflow

Nice-to-haves

• Documentation site with full guides and recipes (see docs/)