fix: Standardize Error Handling in Postgres Package (#32)

* Refine error handling across Postgres methods by standardizing GORM error propagation

Updated all Postgres methods and QueryBuilder implementations to return GORM errors directly for consistency and performance. Introduced optional `TranslateError` utility for standardized error conversion when needed. Enhanced documentation and integration tests to demonstrate direct GORM error handling, translation patterns, and helper functions for consistency in error handling workflows.

* update docs

Author: abolfazl-alemi-aa

README.md

@@ -70,7 +70,7 @@ DOCKER_HOST=unix://$HOME/.colima/default/docker.sock TESTCONTAINERS_RYUK_DISABLE
 
 # Go Packages Documentation
 
-Generated on Tue Dec 16 18:01:28 CET 2025
+Generated on Thu Dec 18 12:16:13 CET 2025
 
 ## Packages
 - [tracer](docs/v1/tracer.md)

docs/v1/postgres.md

@@ -12,7 +12,8 @@ import (
 //   - dest: Pointer to a slice where the results will be stored
 //   - conditions: Optional query conditions (follows GORM conventions)
 //
-// Return an error if the query fails or nil on success.
+// Returns a GORM error if the query fails or nil on success.
+// Use TranslateError() to convert to standardized error types if needed.
 //
 // Example:
 //
@@ -33,12 +34,16 @@ func (p *Postgres) Find(ctx context.Context, dest interface{}, conditions ...int
 //   - dest: Pointer to a struct where the result will be stored
 //   - conditions: Optional query conditions (follows GORM conventions)
 //
-// Return ErrRecordNotFound if no matching record exists, or another error if the query fails.
+// Returns gorm.ErrRecordNotFound if no matching record exists, or another GORM error if the query fails.
+// Use TranslateError() to convert to standardized error types if needed.
 //
 // Example:
 //
 //	var user User
 //	err := db.First(ctx, &user, "email = ?", "user@example.com")
+//	if errors.Is(err, gorm.ErrRecordNotFound) {
+//	    // Handle not found
+//	}
 func (p *Postgres) First(ctx context.Context, dest interface{}, conditions ...interface{}) error {
 	p.mu.RLock()
 	defer p.mu.RUnlock()
@@ -54,7 +59,8 @@ func (p *Postgres) First(ctx context.Context, dest interface{}, conditions ...in
 //   - ctx: Context for the database operation
 //   - value: The struct or slice of structs to be created
 //
-// Returns an error if the creation fails or nil on success.
+// Returns a GORM error if the creation fails or nil on success.
+// Use TranslateError() to convert to standardized error types if needed.
 //
 // Example:
 //
@@ -75,7 +81,8 @@ func (p *Postgres) Create(ctx context.Context, value interface{}) error {
 //   - ctx: Context for the database operation
 //   - value: The struct to be saved
 //
-// Returns an error if the operation fails or nil on success.
+// Returns a GORM error if the operation fails or nil on success.
+// Use TranslateError() to convert to standardized error types if needed.
 //
 // Example:
 //
@@ -99,7 +106,7 @@ func (p *Postgres) Save(ctx context.Context, value interface{}) error {
 //
 // Returns:
 //   - int64: Number of rows affected by the update operation
-//   - error: Error if the update fails, nil on success
+//   - error: GORM error if the update fails, nil on success
 //
 // Note: The current implementation has a bug where it executes the query twice.
 // This should be fixed to execute only once and return both values properly.
@@ -136,7 +143,7 @@ func (p *Postgres) Update(ctx context.Context, model interface{}, attrs interfac
 //
 // Returns:
 //   - int64: Number of rows affected by the update operation
-//   - error: Error if the update fails, nil on success
+//   - error: GORM error if the update fails, nil on success
 //
 // Example:
 //
@@ -165,7 +172,7 @@ func (p *Postgres) UpdateColumn(ctx context.Context, model interface{}, columnNa
 //
 // Returns:
 //   - int64: Number of rows affected by the update operation
-//   - error: Error if the update fails, nil on success
+//   - error: GORM error if the update fails, nil on success
 //
 // Example:
 //
@@ -197,7 +204,7 @@ func (p *Postgres) UpdateColumns(ctx context.Context, model interface{}, columnV
 //
 // Returns:
 //   - int64: Number of rows affected by the delete operation
-//   - error: Error if the deletion fails, nil on success
+//   - error: GORM error if the deletion fails, nil on success
 //
 // Example:
 //
@@ -231,7 +238,7 @@ func (p *Postgres) Delete(ctx context.Context, value interface{}, conditions ...
 //
 // Returns:
 //   - int64: Number of rows affected by the SQL execution
-//   - error: Error if the execution fails, nil on success
+//   - error: GORM error if the execution fails, nil on success
 //
 // Example:
 //
@@ -259,7 +266,8 @@ func (p *Postgres) Exec(ctx context.Context, sql string, values ...interface{})
 //   - count: Pointer to an int64 where the count will be stored
 //   - conditions: Query conditions to filter the records to count
 //
-// Returns an error if the query fails or nil on success.
+// Returns a GORM error if the query fails or nil on success.
+// Use TranslateError() to convert to standardized error types if needed.
 //
 // Example:
 //
@@ -284,7 +292,7 @@ func (p *Postgres) Count(ctx context.Context, model interface{}, count *int64, c
 //
 // Returns:
 //   - int64: Number of rows affected by the update operation
-//   - error: Error if the update fails, nil on success
+//   - error: GORM error if the update fails, nil on success
 //
 // Example:
 //

v1/postgres/basic_ops.go

@@ -92,6 +92,48 @@
 //	)
 //	app.Run()
 //
+// Error Handling:
+//
+// All methods in this package return GORM errors directly. This design provides:
+//   - Consistency: All methods behave the same way
+//   - Flexibility: Consumers can use errors.Is() with GORM error types
+//   - Performance: No translation overhead unless needed
+//   - Transparency: Preserves the full error chain from GORM
+//
+// Basic error handling with GORM errors:
+//
+//	var user User
+//	err := db.First(ctx, &user, "email = ?", "user@example.com")
+//	if errors.Is(err, gorm.ErrRecordNotFound) {
+//	    // Handle not found
+//	}
+//
+//	err = db.Query(ctx).Where("email = ?", "user@example.com").First(&user)
+//	if errors.Is(err, gorm.ErrRecordNotFound) {
+//	    // Handle not found
+//	}
+//
+// For standardized error types, use TranslateError():
+//
+//	err := db.First(ctx, &user, conditions)
+//	if err != nil {
+//	    err = db.TranslateError(err)
+//	    if errors.Is(err, postgres.ErrRecordNotFound) {
+//	        // Handle not found with standardized error
+//	    }
+//	}
+//
+// Recommended pattern - create a helper function for common error checks:
+//
+//	func isRecordNotFound(err error) bool {
+//	    return errors.Is(err, gorm.ErrRecordNotFound)
+//	}
+//
+//	// Use consistently throughout your codebase
+//	if isRecordNotFound(err) {
+//	    // Handle not found
+//	}
+//
 // Performance Considerations:
 //
 //   - Connection pooling is automatically handled to optimize performance

v1/postgres/doc.go

@@ -2,18 +2,17 @@ package postgres
 
 import (
 	"context"
+	"database/sql"
+	"errors"
 	"fmt"
 	"net"
 	"os"
 	"testing"
 	"time"
 
 	"github.com/docker/docker/api/types/container"
-	"github.com/jackc/pgx/v5/pgconn"
-
-	"database/sql"
-
 	"github.com/docker/go-connections/nat"
+	"github.com/jackc/pgx/v5/pgconn"
 	_ "github.com/lib/pq"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -393,32 +392,78 @@ func TestPostgresWithFXModule(t *testing.T) {
 		assert.Equal(t, 200, items[1].Value)
 	})
 
-	// Test error translation
-	t.Run("ErrorTranslation", func(t *testing.T) {
+	// Test error handling - GORM errors and translation
+	t.Run("ErrorHandling", func(t *testing.T) {
 		ctx := context.Background()
 
-		// Test record didn't find an error
-		var user TestUser
-		err := postgres.First(ctx, &user, "name = ?", "NonExistentUser")
-		translatedErr := postgres.TranslateError(err)
-		assert.ErrorIs(t, translatedErr, ErrRecordNotFound)
+		// Test 1: Direct GORM error checking (recommended pattern)
+		t.Run("DirectGORMErrorChecking", func(t *testing.T) {
+			var user TestUser
+			err := postgres.First(ctx, &user, "name = ?", "NonExistentUser")
+			assert.Error(t, err)
+			assert.ErrorIs(t, err, gorm.ErrRecordNotFound, "Should return gorm.ErrRecordNotFound directly")
+
+			// Same pattern works with QueryBuilder
+			err = postgres.Query(ctx).Where("name = ?", "NonExistentUser").First(&user)
+			assert.Error(t, err)
+			assert.ErrorIs(t, err, gorm.ErrRecordNotFound, "QueryBuilder should also return gorm.ErrRecordNotFound")
+		})
 
-		// Create a table with a unique constraint
-		_, err = postgres.Exec(ctx, `
-			CREATE TABLE IF NOT EXISTS unique_test (
-				id SERIAL PRIMARY KEY,
-				email TEXT UNIQUE NOT NULL
-			)
-		`)
-		assert.NoError(t, err)
+		// Test 2: Helper function pattern (recommended for consistency)
+		t.Run("HelperFunctionPattern", func(t *testing.T) {
+			// Define helper function (would typically be in your repository layer)
+			isRecordNotFound := func(err error) bool {
+				return errors.Is(err, gorm.ErrRecordNotFound)
+			}
 
-		// Create a record
-		_, err = postgres.Exec(ctx, `INSERT INTO unique_test (email) VALUES ('test@example.com')`)
-		assert.NoError(t, err)
+			var user TestUser
+			err := postgres.First(ctx, &user, "name = ?", "NonExistentUser")
+			assert.True(t, isRecordNotFound(err), "Helper function should identify record not found")
+
+			// Works consistently with QueryBuilder too
+			err = postgres.Query(ctx).Where("name = ?", "NonExistentUser").First(&user)
+			assert.True(t, isRecordNotFound(err), "Helper function works with QueryBuilder")
+		})
+
+		// Test 3: Error translation (optional, when standardized errors are needed)
+		t.Run("ErrorTranslation", func(t *testing.T) {
+			var user TestUser
+			err := postgres.First(ctx, &user, "name = ?", "NonExistentUser")
+			translatedErr := postgres.TranslateError(err)
+			assert.ErrorIs(t, translatedErr, ErrRecordNotFound, "TranslateError should convert to ErrRecordNotFound")
+
+			// Translation works with any GORM error
+			err = postgres.Query(ctx).Where("name = ?", "NonExistentUser").First(&user)
+			translatedErr = postgres.TranslateError(err)
+			assert.ErrorIs(t, translatedErr, ErrRecordNotFound, "TranslateError works with QueryBuilder errors")
+		})
 
-		// Try to create a duplicate (will fail due to unique constraint)
-		_, err = postgres.Exec(ctx, `INSERT INTO unique_test (email) VALUES ('test@example.com')`)
-		assert.Error(t, err)
+		// Test 4: Constraint violation errors
+		t.Run("ConstraintViolations", func(t *testing.T) {
+			// Create a table with a unique constraint
+			_, err := postgres.Exec(ctx, `
+				CREATE TABLE IF NOT EXISTS unique_test (
+					id SERIAL PRIMARY KEY,
+					email TEXT UNIQUE NOT NULL
+				)
+			`)
+			assert.NoError(t, err)
+
+			// Create a record
+			_, err = postgres.Exec(ctx, `INSERT INTO unique_test (email) VALUES ('test@example.com')`)
+			assert.NoError(t, err)
+
+			// Try to create a duplicate (will fail due to unique constraint)
+			_, err = postgres.Exec(ctx, `INSERT INTO unique_test (email) VALUES ('test@example.com')`)
+			assert.Error(t, err)
+
+			// Check with GORM error
+			assert.ErrorIs(t, err, gorm.ErrDuplicatedKey, "Should return gorm.ErrDuplicatedKey for unique violation")
+
+			// Or translate to standardized error
+			translatedErr := postgres.TranslateError(err)
+			assert.ErrorIs(t, translatedErr, ErrDuplicateKey, "Should translate to ErrDuplicateKey")
+		})
 	})
 
 	// Stop the application
@@ -2715,7 +2760,7 @@ func TestQueryBuilder_ToSubquery(t *testing.T) {
 
 		require.NoError(t, err)
 		assert.Len(t, results, 2) // Charlie and Dave
-		
+
 		names := make([]string, len(results))
 		for i, u := range results {
 			names[i] = u.Name

v1/postgres/integration_test.go

@@ -92,7 +92,7 @@ type MigrationHistoryRecord struct {
 // Parameters:
 //   - models: The GORM models to auto-migrate
 //
-// Returns an error if any part of the migration process fails.
+// Returns a GORM error if any part of the migration process fails.
 //
 // This method is useful during development or for simple applications,
 // but for production systems, explicit migrations are recommended.
@@ -143,7 +143,8 @@ func (p *Postgres) ensureMigrationHistoryTable() error {
 //   - ctx: Context for database operations
 //   - migrationsDir: Directory containing the migration SQL files
 //
-// Returns an error if any migration fails or if there are issues accessing the migrations.
+// Returns a wrapped error if any migration fails or if there are issues accessing the migrations.
+// The error wraps the underlying GORM error with additional context.
 //
 // Example:
 //
@@ -241,7 +242,8 @@ func (p *Postgres) MigrateUp(ctx context.Context, migrationsDir string) error {
 //   - ctx: Context for database operations
 //   - migrationsDir: Directory containing the migration SQL files
 //
-// Returns an error if the rollback fails or if the down migration can't be found.
+// Returns a wrapped error if the rollback fails or if the down migration can't be found.
+// The error wraps the underlying GORM error with additional context.
 //
 // Example:
 //
@@ -372,7 +374,8 @@ func (p *Postgres) loadMigrations(dir string, direction MigrationDirection) ([]M
 //   - migrationsDir: Directory containing the migration SQL files
 //
 // Returns a slice of maps with status information for each migration,
-// or an error if the status cannot be determined.
+// or a wrapped error if the status cannot be determined.
+// The error wraps the underlying GORM error with additional context.
 //
 // Example:
 //
@@ -440,7 +443,7 @@ func (p *Postgres) GetMigrationStatus(ctx context.Context, migrationsDir string)
 //   - name: Descriptive name for the migration
 //   - migrationType: Whether this is a schema or data migration
 //
-// Returns the base filename of the created migration or an error if creation fails.
+// Returns the base filename of the created migration or a wrapped error if creation fails.
 //
 // Example:
 //