v3.0.0

Changelog

[v3.0.0] - 2024-09-27

🚀 Major Release - Breaking Changes

This release represents a complete architectural overhaul of Octobe, introducing significant breaking changes that improve usability, type safety, and testing capabilities.

The goal of this upgrade is to provide a better generic interface to add other types of drivers.

✨ Added

New Architecture

• Direct Driver Interface: Removed the Octobe wrapper struct in favor of direct driver usage
• BuilderSession Interface: New interface that separates session management from transaction handling
• Automatic Transaction Management: New StartTransaction() method handles begin/commit/rollback automatically
• Connection Pool Support: Added pgxpool.Pool support alongside single pgx.Conn connections

Enhanced API

• Execute Functions:
  • Execute[RESULT, BUILDER](session, handler) - Execute handlers and return results
  • ExecuteVoid(session, handler) - Execute handlers that return no data
  • ExecuteMany(session, ...handlers) - Execute multiple handlers in sequence
• Driver Management:
  • Ping(ctx) - Test database connectivity
  • Close(ctx) - Properly close database connections and pools
• Enhanced Error Handling: Improved error types and messages

Testing & Mocking

• Comprehensive Mock Support:
  • mock.PGXPoolMock for pgxpool testing
  • mock.PGXMock for single connection testing
  • Full expectation-based testing with ExpectQueryRow, ExpectExec, ExpectQuery
• Mock Helpers:
  • MockRow for simulating database rows
  • AllExpectationsMet() for test verification

PostgreSQL Driver Improvements

• Dual Connection Support:
  • OpenPGXPool() - Connection pool-based driver
  • OpenPGX() - Single connection driver
  • OpenPGXWithPool() - Use existing pool instance
  • OpenPGXWithConn() - Use existing connection instance
• Enhanced Segment API:
  • Better type safety for query results
  • Improved ExecResult with RowsAffected field
  • Generic Rows interface for database compatibility

Documentation & Examples

• Complete README Rewrite: Comprehensive documentation with migration guides
• Real-World Examples:
  • Simple CRUD example (examples/simple/)
  • Complex blog application example (examples/blog/)
• Migration Guides: From database/sql, GORM, and Squirrel

🔄 Changed

Breaking Changes

• Package Structure: Moved from github.com/Kansuler/octobe/v2 to github.com/Kansuler/octobe/v3
• Core API:
  • Removed Octobe struct wrapper
  • New() now returns Driver interface directly
  • Sessions now use BuilderSession[BUILDER] interface
• Handler Signature: Changed from Handler[RESULT] func(Builder) (RESULT, error) to driver-specific handlers
• Transaction Management:
  • Removed WatchRollback() method
  • Added automatic transaction management with StartTransaction()
• Driver Interface: Complete redesign with generic type parameters

Improved APIs

• Session Management: Cleaner separation between transactional and non-transactional operations
• Builder Pattern: Enhanced builder with better type safety and error handling
• Configuration: Simplified option handling with type-safe Option[CONFIG] pattern

🗑️ Removed

Deprecated Features

• Octobe Struct: No longer needed with direct driver interface
• WatchRollback(): Replaced by automatic transaction management in StartTransaction()
• Global Handler Type: Replaced with driver-specific handlers
• Manual Transaction Management: Still available but StartTransaction() is recommended

Removed Dependencies

• Simplified dependency tree
• Removed unused testing utilities (replaced with comprehensive mock support)

🔧 Technical Improvements

• Type Safety: Enhanced generic usage throughout the API
• Error Handling: Better error types and more descriptive error messages
• Connection Management: Proper resource cleanup and connection pooling
• Testing: Comprehensive mock framework for unit testing
• Performance: Optimized query execution and connection handling

📖 Migration Guide

From v2 to v3

Before (v2):

// v2 API
db, err := octobe.New(postgres.Open(ctx, dsn))
session, err := db.Begin(ctx, postgres.WithTransaction(postgres.TxOptions{}))

user, err := postgres.Execute(session, GetUser(123))
if err != nil {
    session.Rollback()
    return err
}
session.Commit()

After (v3):

// v3 API
db, err := octobe.New(postgres.OpenPGXPool(ctx, dsn))

var user User
err = db.StartTransaction(ctx, func(session octobe.BuilderSession[postgres.Builder]) error {
    user, err = postgres.Execute(session, GetUser(123))
    return err // Automatic rollback on error, commit on success
})

Handler Migration

Before (v2):

func GetUser(id int) postgres.Handler[User] {
    return func(builder postgres.Builder) (User, error) {
        // Same implementation
    }
}

After (v3):

func GetUser(id int) octobe.Handler[User, postgres.Builder] {
    return func(builder postgres.Builder) (User, error) {
        // Same implementation - handlers are compatible!
    }
}

🎯 Upgrade Recommendations

1. Update import paths from v2 to v3
2. Replace manual transaction management with StartTransaction()
3. Update driver initialization to use new Open* functions
4. Adopt new testing patterns with mock support
5. Consider connection pooling with OpenPGXPool() for production use

Added support to close connection pool

• Added support to close connection pool

ob, err := octobe.New(postgres.Open(ctx, dsn, postgres.WithTransaction(postgres.TxOptions{})))
if err != nil {
	// ... error
}

// ... do stuff

// New method
err = ob.Close(ctx)
if err != nil {
	// ... error
}

Octobe remake!

• Added support for multiple drivers
• Made a clearer handler with generics that returns a result rather than sending a pointer into a query function.

implement dblike interface instead of *sql.DB

v0.3.0-beta.5

converted *sql.DB to use dblike interface instead, added transactionl…

v0.3.0

converted *sql.DB to use dblike interface instead, added transactionl…

Updated errs type

Code changes

• Errs type will not add nil values when serialized to string.

Repository changes

• Added integration tests and code testing coverage via Codacy.

Improved the internal API

• Improved the internal API by using interface instead of sql.DB and sql.Tx in parallel. #1
• Changed Argument func signature to func (segment *Segment) Arguments(args ...interface{}) *Segment. It's now possible to chain the calls. #1

Thanks for contribution @Arneball

v0.3.0-beta.2

• Improved error handling for merging multiple errors without losing their types.

Breaking changes v0.3.0-beta.1

• Removed the Insert method on Segments. It did not add any value compared to QueryRow
• Moved SuppressError options to every individual handler, as it should be set per query and not for the whole transaction.

// For illustration, you can also suppress specific errors in the scheme handler
err = scheme.Handle(InsertProduct(&p2), octobe.SuppressError(sql.ErrNoRows), octobe.SuppressError(sql.ErrTxDone))
if err != nil {
  return err
}

Added As to octobeError

• Added "As" method receiver to octobeError type