Skip to content

v0.4.1-beta - API Convenience Methods

Pre-release
Pre-release

Choose a tag to compare

View all tags
@kolkov kolkov released this 26 Oct 12:16
· 138 commits to main since this release
v0.4.1-beta
e4fcd7b

Released: October 26, 2025
Focus: Developer ergonomics - shorter API for common operations

🎯 What's New

API Convenience Methods - Shorter syntax while maintaining architectural clarity

Added convenience methods to DB and Tx for improved developer experience:

New Methods (8 total)

On DB:

  • Select(cols...) - Create SELECT query
  • Insert(table, data) - Create INSERT query
  • Update(table) - Create UPDATE query
  • Delete(table) - Create DELETE query

On Tx:

  • Same 4 methods available in transactions

📝 API Comparison

Before (v0.4.0)

// Longer syntax
var users []User
err := db.Builder().Select("*").
    From("users").
    Where("active = ?", true).
    All(&users)

// INSERT
_, err = db.Builder().Insert("users", map[string]interface{}{
    "name":  "Alice",
    "email": "alice@example.com",
}).Execute()

// UPDATE
_, err = db.Builder().
    Update("users").
    Set(map[string]interface{}{"status": "active"}).
    Where("id = ?", 123).
    Execute()

// DELETE
_, err = db.Builder().
    Delete("users").
    Where("id = ?", 123).
    Execute()

After (v0.4.1)

// Shorter syntax (10 characters less per query!)
var users []User
err := db.Select("*").
    From("users").
    Where("active = ?", true).
    All(&users)

// INSERT
_, err = db.Insert("users", map[string]interface{}{
    "name":  "Alice",
    "email": "alice@example.com",
}).Execute()

// UPDATE
_, err = db.Update("users").
    Set(map[string]interface{}{"status": "active"}).
    Where("id = ?", 123).
    Execute()

// DELETE
_, err = db.Delete("users").
    Where("id = ?", 123).
    Execute()

Advanced Features - Use Builder()

// For complex queries (CTEs, UNION, subqueries) - continue using Builder()
var results []Stats
err := db.Builder().
    With("active_users", subquery).
    Select("*").
    From("active_users").
    Union(otherQuery).
    All(&results)

✅ Design Philosophy

Best of Both Worlds:

  • ✅ Short API for common CRUD operations (db.Select())
  • ✅ Clear architecture for advanced features (db.Builder().With())
  • ✅ 100% backward compatible - all v0.4.0 code continues to work
  • ✅ Zero performance overhead - compiler inlines wrapper methods

API Guidelines:

  • Use db.Select() / db.Insert() / db.Update() / db.Delete() for simple queries
  • Use db.Builder() for advanced features (CTEs, UNION, complex subqueries)

📊 Quality Metrics

Test Coverage

  • 326 tests passing (up from 310)
  • 93.3% coverage (up from 92.9%)
  • 16 new comprehensive tests for convenience methods
  • 3 test suites:
    • DB convenience methods (6 tests)
    • Tx convenience methods (3 tests)
    • Backward compatibility (3 tests)
    • Complex queries (4 tests)

Code Quality

  • golangci-lint: 0 issues
  • go vet: Clean
  • All integration tests: Passing (PostgreSQL, MySQL, SQLite)
  • Benchmarks: Compiling and running

🔄 Backward Compatibility

100% compatible with v0.4.0:

// v0.4.0 code continues to work WITHOUT changes
db.Builder().Select("*").From("users").All(&users)  // ✅ Still works

// v0.4.1 adds shorter alternative
db.Select("*").From("users").All(&users)  // ✅ New convenience method

No breaking changes:

  • All existing methods unchanged
  • Builder() continues to work as before
  • No API removals or deprecations

📦 Installation

# Get latest version
go get -u github.com/coregx/relica@v0.4.1-beta

# Or in go.mod
require github.com/coregx/relica v0.4.1-beta

🎓 Documentation

Updated Guides

  • README.md - Quick Start with convenience methods
  • CHANGELOG.md - Complete v0.4.1-beta changes
  • ROADMAP.md - Updated for v0.4.1-beta release

API Documentation

  • pkg.go.dev - All 8 new methods with examples
  • Godoc comments - Comprehensive inline documentation

🚀 What's Next

v0.5.0-beta (Q1 2026)

Production Hardening & Performance

Planned features:

  • ⚡ Query Optimizer - Auto-index hints, slow query detection
  • 📊 Query Analyzer - EXPLAIN integration for all databases
  • 🔍 SQL Logging & Tracing - slog, OpenTelemetry support
  • 🚀 Performance Tuning - Advanced pooling, result caching, read replicas
  • 🛡️ Security Hardening - Audit logging, PII masking, query whitelisting

Timeline: 6-8 weeks
Status: Planning phase

🤝 Community

🙏 Acknowledgments

This release was inspired by the ergonomics of ozzo-dbx while maintaining Relica's architectural clarity and separation of concerns.

📋 Complete Changelog

See CHANGELOG.md for complete details.

Previous Release: v0.4.0-beta
Full Changelog: v0.4.0-beta...v0.4.1-beta

Relica - Lightweight, Type-Safe Database Query Builder for Go
Zero production dependencies • Advanced SQL features • Production-ready

Assets 2
Loading