Skip to content

v0.4.0-beta - Better Documentation & API Stability

Pre-release
Pre-release

Choose a tag to compare

View all tags
@kolkov kolkov released this 26 Oct 01:03
· 145 commits to main since this release
v0.4.0-beta
5396d48

Major architectural improvement - Migrated from type aliases to wrapper types for improved pkg.go.dev documentation and Go best practices compliance.

Breaking Changes: See Migration Guide for v0.3.0 → v0.4.0 upgrade instructions.

🎯 What Changed

We've replaced type aliases with wrapper types to dramatically improve pkg.go.dev documentation and follow Go best practices 2025.

Before (v0.3.0)

type DB = core.DB              // type alias
type QueryBuilder = core.QueryBuilder

Problem: pkg.go.dev doesn't show methods for type aliases from internal packages.

After (v0.4.0)

type DB struct {               // wrapper type
    db *core.DB
}

type QueryBuilder struct {
    qb *core.QueryBuilder
}

Result: All methods now visible on pkg.go.dev with comprehensive examples!

✨ Key Features

Wrapper Types Migration

  • 81 methods wrapped with comprehensive godoc
  • Zero performance overhead - Compiler inlines wrapper calls (0ns)
  • Full backward compatibility - 95% of code requires ZERO changes
  • Industry best practices - Follows patterns from sqlx, pgx, GORM

New Methods

  • DB.Unwrap() *core.DB - Access internal types when needed
  • QueryBuilder.Unwrap() *core.QueryBuilder
  • SelectQuery.Unwrap() *core.SelectQuery
  • Tx.Unwrap() *core.Tx
  • All query types support Unwrap() for advanced use cases

Bug Fixes

  • Critical: Fixed SELECT "" being quoted as SELECT "" causing scan failures
    • Location: internal/core/builder.go line 634
    • Impact: Fixed 2 failing wrapper tests

Documentation

  • Migration Guide - Comprehensive v0.3.0 → v0.4.0 upgrade guide
  • Comprehensive godoc for all 81 public methods with examples
  • Code examples in godoc comments for better IDE integration

📊 Quality Metrics

  • ✅ Test Coverage: 92.9% (improved from 89.9%)
  • ✅ Tests: All 310+ tests passing
  • ✅ golangci-lint: 0 issues
  • ✅ Performance: Zero overhead (0ns wrapper calls)
  • ✅ Integration Tests: PostgreSQL, MySQL, SQLite all passing
  • ✅ CI Duration: 2m 46s (all platforms)

🔄 Migration Impact

95% of Code - ZERO Changes Required

// ✅ All of this continues working:
db, err := relica.Open("postgres", dsn)
defer db.Close()

db.Builder().Select("*").From("users").All(&users)

tx, _ := db.Begin(ctx)
tx.Builder().Insert("users", data).Execute()
tx.Commit()

sqlDB, _ := sql.Open("postgres", dsn)
db := relica.WrapDB(sqlDB, "postgres")  // ✅ Still works!

5% of Code - Simple Updates

Type Assertions:

// ❌ Before (v0.3.0):
coreDB := (*core.DB)(db)

// ✅ After (v0.4.0):
coreDB := db.Unwrap()  // Use new Unwrap() method

Function Signatures:

// ❌ Before:
func process(db *core.DB) { }

// ✅ After (Option 1):
func process(db *relica.DB) { }

// ✅ After (Option 2):
func process(db *core.DB) { }
// Call with: process(db.Unwrap())

Test Type Checks:

// ❌ Before:
assert.IsType(t, &core.DB{}, db)

// ✅ After:
assert.IsType(t, &relica.DB{}, db)

🎁 What You Gain

Better Documentation

Before (v0.3.0):

pkg.go.dev shows:
  type DB = core.DB
  (methods not visible)

After (v0.4.0):

pkg.go.dev shows:
  type DB struct { ... }

  func (d *DB) Builder() *QueryBuilder
      Builder returns a new QueryBuilder for constructing queries.

      Example:
        db.Builder().Select("*").From("users").All(&users)

  func (d *DB) Close() error
      Close closes the database connection...

  (all 81 methods with examples)

Better IDE Support

  • ✅ Full autocomplete for all methods
  • ✅ Inline documentation
  • ✅ Go to definition works correctly
  • ✅ Better refactoring support

Future-Proof API

  • ✅ Public API now stable for v1.0.0
  • ✅ Internal implementation can change without breaking users
  • ✅ Follows industry best practices

📦 Installation

go get github.com/coregx/relica@v0.4.0-beta

📚 Documentation

User Guides

💬 Breaking Changes

This is a breaking change (acceptable in beta). See the Migration Guide for:

  • ✅ What keeps working (95% of code)
  • ⚠️ What might break (5% - type assertions, function signatures)
  • 🔧 How to fix (simple updates with Unwrap())
  • 📊 Migration checklist
  • 💡 Common issues and solutions

Average migration time: 15-30 minutes for typical projects

🙏 Acknowledgments

  • IrisMX Team - Our first production user (10K+ concurrent users). Your WrapDB() integration is fully compatible with v0.4.0-beta!
  • Community - Feedback on pkg.go.dev documentation led to this improvement
  • Go Team - For clear guidance on type aliases vs wrapper types

🎯 What's Next?

v0.5.0-beta (Q1 2026) - Production Hardening:

  • Query optimizer with auto-index hints
  • Query analyzer (EXPLAIN integration)
  • Performance tuning enhancements
  • Security hardening

v1.0.0 (Q2 2026) - Production Stable Release:

  • API freeze (no more breaking changes)
  • Long-term support commitment
  • Enterprise support options

See ROADMAP for details.

🚨 Need Help?

When reporting issues, include:

  • Code snippet showing the problem
  • Error message
  • Go version
  • Relica version (v0.4.0-beta)

Full Changelog: v0.3.0-beta...v0.4.0-beta

"Better documentation leads to better adoption. This release prioritizes developer experience."

— COREGX Team

Assets 2
Loading