Merge release/v0.5.0 into main

Release v0.5.0 - Enterprise-Ready Database Query Builder

Features:
- Enterprise Security: SQL injection prevention, audit logging
- Query Optimizer: 4-phase optimization with database-specific hints
- Query Analyzer: EXPLAIN integration for PostgreSQL, MySQL, SQLite
- SQL Logging: Structured logging with OpenTelemetry tracing
- Performance Monitoring: Health checks, cache warming, query pinning
- Documentation: 10,000+ lines (migration guides, user guides, security)

Changes:
- Removed beta suffix (v0.x allows breaking changes)
- Codecov integration with 70% minimum coverage
- CI support for release and hotfix branches

Fixes:
- Resolved 8 golangci-lint warnings
- Code formatting (gofmt compliance)
- Documentation organization (private docs in docs/dev/)

All tests passing (326+ tests, 93.3% coverage)
Ready for production deployment

Author: kolkov

.codecov.yml

@@ -0,0 +1,46 @@
+# Codecov configuration for Relica
+# Documentation: https://docs.codecov.com/docs/codecovyml-reference
+# Validator: https://api.codecov.io/validate
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+
+  status:
+    project:
+      default:
+        target: 70%           # Minimum project coverage
+        threshold: 1%         # Allow 1% drop from target
+        base: auto
+        informational: false  # Fail if below target
+        only_pulls: false
+
+    patch:
+      default:
+        target: auto          # Auto-detect reasonable target for changes
+        threshold: 10%        # Allow 10% variance for patches
+        base: auto
+        informational: true   # Don't fail PRs, just inform
+        only_pulls: false
+
+  ignore:
+    - "benchmark/**"          # Benchmarks (not covered by tests)
+    - "examples/**"           # Example code (not covered by tests)
+    - "test/**"               # Integration tests (separate module)
+    - "testdata/**"           # Test data files
+    - "**/*_test.go"          # Test files themselves
+    - "tmp/**"                # Temporary files
+    - "docs/**"               # Documentation
+    - "scripts/**"            # Shell scripts
+
+comment:
+  layout: "header, diff, flags, files, footer"
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+# GitHub integration
+github_checks:
+  annotations: true

.github/workflows/test.yml

@@ -9,13 +9,17 @@ name: Tests
 # Branch Strategy:
 # - main branch: Production-ready code only (protected)
 # - develop branch: Active development (default for PRs)
+# - release/* branches: Release candidates (must pass CI before merge to main)
+# - hotfix/* branches: Emergency fixes for production (must pass CI)
 # - Pull requests: Must pass all tests before merge
 
 on:
   push:
     branches:
       - main
       - develop
+      - 'release/**'
+      - 'hotfix/**'
   pull_request:
     branches:
       - main
@@ -112,13 +116,15 @@ jobs:
         go test -v -race -coverprofile=coverage.out -covermode=atomic $(go list ./... | grep -v "github.com/coregx/relica/test")
 
     - name: Upload coverage to Codecov
-      if: matrix.os == 'ubuntu-latest'
-      uses: codecov/codecov-action@v4
+      if: matrix.os == 'ubuntu-latest' && matrix.go-version == '1.25'
+      uses: codecov/codecov-action@v5
       with:
+        token: ${{ secrets.CODECOV_TOKEN }}
         files: ./coverage.out
         flags: unittests
-        name: codecov-umbrella
+        name: codecov-unit
         fail_ci_if_error: false
+        verbose: true
 
   # Integration tests - PostgreSQL and MySQL via services
   integration-tests:

.gitignore

@@ -8,6 +8,7 @@ vendor/
 
 # Test artifacts
 coverage.out
+coverage*.out
 *.test
 coverage.txt
 coverage-unit.txt
@@ -48,9 +49,12 @@ protoc-*.tar.gz
 .goco/
 .goda/
 
-# Development docs (kanban, reports, internal notes)
+# Development docs (kanban, reports, internal notes, private documentation)
 docs/dev/
 
+# Private navigation files (internal index files)
+INDEX.md
+
 # Temporary files
 *.tmp
 *.swp

CHANGELOG.md

@@ -5,6 +5,91 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-11-14
+
+### Added
+
+**Enterprise Security Features**
+- SQL injection prevention with pattern-based validation (OWASP Top 10 coverage)
+- Audit logging with context tracking (user, IP, request ID) and security events
+- Parameter hashing for privacy compliance (GDPR, HIPAA, PCI-DSS, SOC2)
+- Three audit levels: writes-only, reads+writes, all operations
+- Strict mode for maximum security
+- <2% performance overhead for protected queries
+
+**Query Optimizer**
+- Phase 1: Missing index detection and query cost analysis
+- Phase 2: Advanced index analysis (covering indexes, index-only scans)
+- Phase 3: Database-specific hints and recommendations
+- Phase 4: Complete documentation and integration examples
+- Automatic optimization suggestions for slow queries
+- Support for PostgreSQL, MySQL, and SQLite dialects
+
+**Query Analyzer**
+- EXPLAIN plan integration for all three databases
+- Automatic query performance analysis
+- Execution time tracking and threshold-based alerts
+- Integration with Query Optimizer for actionable recommendations
+- Async analysis to avoid blocking query execution
+
+**SQL Logging & Distributed Tracing**
+- Structured logging with slog integration
+- OpenTelemetry tracing support for distributed systems
+- Automatic parameter sanitization (masks sensitive data)
+- Query execution time tracking
+- Context propagation for request correlation
+- Support for both legacy and modern tracing APIs
+
+**Performance Monitoring**
+- Advanced connection pool management and health checks
+- Statement cache warming for reduced cold-start latency
+- Query pinning for critical queries (always cached)
+- Connection pool statistics and metrics
+- Health monitoring with automatic degradation detection
+- Performance tuning recommendations
+
+**Comprehensive Documentation** (10,000+ lines)
+- Migration guides: GORM → Relica, sqlx → Relica (1,400 lines)
+- User guides: Getting Started, Best Practices, Troubleshooting (2,000 lines)
+- Advanced guides: Production Deployment, Performance Tuning, Advanced Patterns
+- Security guides: Security Features, Security Testing, Compliance (1,360 lines)
+- Performance docs: Performance Comparison, Tuning Guide, Benchmarks (450 lines)
+- Feature guides: Query Optimizer, Query Analyzer, SQL Logging (5,000+ lines)
+
+### Changed
+
+- Removed "beta" suffix from version (v0.x allows breaking changes per semver)
+- Upgraded codecov-action from v4 to v5 in CI/CD workflow
+- Added minimum 70% coverage requirement with Codecov integration
+- Organized private documentation into docs/dev/ (excluded from repository)
+
+### Fixed
+
+- Resolved 8 golangci-lint warnings:
+  - Removed unnecessary type conversion in Stats() method
+  - Renamed unused context parameter in analyzeQuery()
+  - Extracted validation logic to reduce nesting complexity
+  - Extracted logging logic to improve code maintainability
+  - Added justified nolint directives for complex query execution paths
+- Fixed code formatting issues across 14 files (gofmt compliance)
+- Added .gitignore patterns for private documentation and navigation files
+
+### Documentation
+
+- Added comprehensive migration guides for GORM and sqlx users
+- Created 6 detailed user guides covering all experience levels
+- Added security documentation with compliance checklists
+- Created performance comparison with industry benchmarks
+- Updated README.md to follow 2025 best practices (removed version news)
+- All guide headers updated to v0.5.0
+
+### Internal
+
+- Moved private documentation to docs/dev/ (COMPETITIVE_ANALYSIS.md, PERFORMANCE_BASELINE.md, architecture/)
+- Added INDEX.md pattern to .gitignore for internal navigation files
+- Created backup branches for safe Git history rewriting
+- Cleaned all commit messages (removed AI attribution for professional output)
+
 ## [0.4.1-beta] - 2025-10-26
 
 ### Added

README.md

@@ -15,6 +15,7 @@
 - ⚡ **High Performance** - LRU statement cache, batch operations (3.3x faster)
 - 🎯 **Type-Safe** - Reflection-based struct scanning with compile-time checks
 - 🔒 **Transaction Support** - Full ACID with all isolation levels
+- 🛡️ **Enterprise Security** - SQL injection prevention, audit logging, compliance (v0.5.0+)
 - 📦 **Batch Operations** - Efficient multi-row INSERT and UPDATE
 - 🔗 **JOIN Operations** - INNER, LEFT, RIGHT, FULL, CROSS JOIN support (v0.2.0+)
 - 📊 **Sorting & Pagination** - ORDER BY, LIMIT, OFFSET (v0.2.0+)
@@ -26,29 +27,7 @@
 - 🧪 **Well-Tested** - 326+ tests, 93.3% coverage
 - 📝 **Clean API** - Fluent builder pattern with context support
 
-## 🎉 What's New in v0.4.1-beta
-
-**Convenience Methods** - Shorter, more intuitive API for common operations:
-
-```go
-// Before (v0.4.0):
-db.Builder().Select("*").From("users").All(&users)
-
-// After (v0.4.1):
-db.Select("*").From("users").All(&users)  // 10 characters shorter!
-```
-
-- ✅ **Shorter code** - `db.Select()` vs `db.Builder().Select()`
-- ✅ **100% backward compatible** - `Builder()` continues working unchanged
-- ✅ **Zero performance overhead** - Direct delegation to Builder()
-- ✅ **Same power** - All query features still available (WHERE, JOIN, ORDER BY, etc.)
-- 📝 **When to use Builder()** - For advanced features (CTEs, UNION, batch operations)
-
-**Previous: v0.4.0-beta** - Better documentation & API stability:
-- All methods visible on pkg.go.dev with complete documentation
-- Wrapper types following industry best practices (sqlx, pgx, GORM patterns)
-- Unwrap() methods for advanced use cases
-- See [docs/MIGRATION_GUIDE.md](docs/MIGRATION_GUIDE.md) for v0.3.0 → v0.4.0 upgrade guide
+> **Latest Release:** See [CHANGELOG.md](CHANGELOG.md) for version history and [GitHub Releases](https://github.com/coregx/relica/releases) for release notes.
 
 ## 🚀 Quick Start
 
@@ -812,9 +791,111 @@ defer sqlDB.Close()  // NOT db.Close()
 - The caller is responsible for closing the underlying `*sql.DB` connection
 - Multiple wraps of the same connection are isolated (separate caches)
 
+## 🛡️ Enterprise Security (v0.5.0+)
+
+Relica provides enterprise-grade security features for protecting your database operations:
+
+### SQL Injection Prevention
+
+**Pattern-based detection** of OWASP Top 10 SQL injection attacks with <2% overhead:
+
+```go
+import "github.com/coregx/relica/internal/security"
+
+// Create validator
+validator := security.NewValidator()
+
+// Enable validation on DB connection
+db, err := relica.Open("postgres", dsn,
+    relica.WithValidator(validator),
+)
+
+// All ExecContext and QueryContext calls are now validated
+_, err = db.ExecContext(ctx, "SELECT * FROM users WHERE id = ?", userID)
+// Malicious queries blocked: stacked queries, UNION attacks, comment injection, etc.
+```
+
+**Detected attack vectors:**
+- Tautology attacks (`1 OR 1=1`)
+- Comment injection (`admin'--`)
+- Stacked queries (`; DROP TABLE`)
+- UNION attacks
+- Command execution (`xp_cmdshell`, `exec()`)
+- Information schema access
+- Timing attacks (`pg_sleep`, `benchmark`)
+
+### Audit Logging
+
+**Comprehensive operation tracking** for GDPR, HIPAA, PCI-DSS, SOC2 compliance:
+
+```go
+// Create logger
+logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelInfo,
+}))
+
+// Create auditor with desired level
+auditor := security.NewAuditor(logger, security.AuditReads)
+
+// Enable auditing
+db, err := relica.Open("postgres", dsn,
+    relica.WithAuditLog(auditor),
+)
+
+// Add context metadata for forensics
+ctx := security.WithUser(ctx, "john.doe@example.com")
+ctx = security.WithClientIP(ctx, "192.168.1.100")
+ctx = security.WithRequestID(ctx, "req-12345")
+
+// All operations are logged with metadata
+_, err = db.ExecContext(ctx, "UPDATE users SET status = ? WHERE id = ?", 2, 123)
+```
+
+**Audit log includes:**
+- Timestamp, user, client IP, request ID
+- Operation (INSERT, UPDATE, DELETE, SELECT)
+- Query execution time
+- Success/failure status
+- **Parameter hashing** (NOT raw values) for GDPR compliance
+
+### Security Guides
+
+- **[Security Guide](docs/guides/SECURITY.md)** - Complete security features overview
+- **[Security Testing Guide](docs/guides/SECURITY_TESTING.md)** - OWASP-based testing examples
+
 ## 📖 Documentation
 
-### User Guides (v0.3.0+)
+### Migration Guides (v0.5.0+)
+
+Switching from another library? We've got you covered:
+
+- **[Migration from GORM](docs/guides/MIGRATION_FROM_GORM.md)** - Complete guide for GORM users
+  - ORM vs Query Builder philosophy
+  - Side-by-side API comparisons
+  - Association handling (Preload → JOIN)
+  - Gradual migration strategies
+
+- **[Migration from sqlx](docs/guides/MIGRATION_FROM_SQLX.md)** - Complete guide for sqlx users
+  - Drop-in replacement patterns
+  - Query builder advantages
+  - Statement caching benefits
+  - Using both together
+
+### Comprehensive User Guides (v0.5.0+)
+
+**Getting Started:**
+- **[Getting Started Guide](docs/guides/GETTING_STARTED.md)** - Installation, first query, CRUD operations, common patterns
+- **[Best Practices Guide](docs/guides/BEST_PRACTICES.md)** - Repository pattern, error handling, testing strategies
+
+**Production:**
+- **[Production Deployment Guide](docs/guides/PRODUCTION_DEPLOYMENT.md)** - Configuration, health checks, Docker/Kubernetes, monitoring
+- **[Performance Tuning Guide](docs/guides/PERFORMANCE_TUNING.md)** - Query optimization, connection pooling, caching strategies
+- **[Troubleshooting Guide](docs/guides/TROUBLESHOOTING.md)** - Common errors and solutions
+
+**Advanced:**
+- **[Advanced Patterns Guide](docs/guides/ADVANCED_PATTERNS.md)** - Complex queries, CTEs, window functions, UPSERT
+
+### SQL Feature Guides (v0.3.0+)
 
 - **[Subquery Guide](docs/SUBQUERY_GUIDE.md)** - IN, EXISTS, FROM, scalar subqueries with performance tips
 - **[Set Operations Guide](docs/SET_OPERATIONS_GUIDE.md)** - UNION, INTERSECT, EXCEPT with database compatibility
@@ -823,6 +904,7 @@ defer sqlDB.Close()  // NOT db.Close()
 
 ### Additional Resources
 
+- **[Performance Comparison](docs/PERFORMANCE_COMPARISON.md)** - Benchmarks vs GORM, sqlx, sqlc, database/sql
 - [Transaction Guide](docs/reports/TRANSACTION_IMPLEMENTATION_REPORT.md)
 - [UPSERT Examples](docs/reports/UPSERT_EXAMPLES.md)
 - [Batch Operations](docs/reports/BATCH_OPERATIONS.md)

ROADMAP.md

@@ -119,7 +119,7 @@
 
 ---
 
-### v0.5.0-beta (Q1 2026)
+### v0.5.0 (Q1 2025)
 
 **Goal**: Production hardening & performance