postgres

func (*Postgres) AutoMigrate ¶

func (p *Postgres) AutoMigrate(models ...interface{}) error

AutoMigrate is a wrapper around GORM's AutoMigrate with additional features. It tracks migrations in the migration history table and provides better error handling.

Parameters:

• models: The GORM models to auto-migrate

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.

func (*Postgres) Count ¶

func (p *Postgres) Count(ctx context.Context, model interface{}, count *int64, conditions ...interface{}) error

Count determines the number of records that match the given conditions. It populates the count parameter with the result.

Parameters:

• ctx: Context for the database operation
• model: The model type to count
• count: Pointer to an int64 where the count will be stored
• conditions: Query conditions to filter the records to count

Returns a GORM error if the query fails or nil on success. Use TranslateError() to convert to standardized error types if needed.

Example:

var count int64
err := db.Count(ctx, &User{}, &count, "age > ?", 18)

func (*Postgres) Create ¶

func (p *Postgres) Create(ctx context.Context, value interface{}) error

Create inserts a new record into the database. It processes the value parameter according to GORM conventions, performing hooks and validations defined on the model.

Parameters:

• ctx: Context for the database operation
• value: The struct or slice of structs to be created

Returns a GORM error if the creation fails or nil on success. Use TranslateError() to convert to standardized error types if needed.

Example:

user := User{Name: "John", Email: "john@example.com"}
err := db.Create(ctx, &user)

func (*Postgres) CreateMigration ¶

func (p *Postgres) CreateMigration(migrationsDir, name string, migrationType MigrationType) (string, error)

CreateMigration generates a new migration file. It creates both up and down migration files with appropriate names and timestamps.

Parameters:

• migrationsDir: Directory where migration files should be created
• name: Descriptive name for the migration
• migrationType: Whether this is a schema or data migration

Returns the base filename of the created migration or a wrapped error if creation fails.

Example:

filename, err := db.CreateMigration("./migrations", "create_users_table", postgres.SchemaType)
if err == nil {
    fmt.Printf("Created migration: %s\n", filename)
}

func (*Postgres) DB ¶

func (p *Postgres) DB() *gorm.DB

DB returns the underlying GORM DB Client instance. This method provides direct access to the database connection while maintaining thread safety through an atomic load.

Use this method when you need to perform operations not covered by the wrapper methods or when you need to access specific GORM functionality. Note that direct usage bypasses some of the safety mechanisms, so use it with care.

func (*Postgres) Delete ¶

func (p *Postgres) Delete(ctx context.Context, value interface{}, conditions ...interface{}) (int64, error)

Delete removes records that match the given value and conditions from the database. It respects soft delete if implemented on the model.

Parameters:

• ctx: Context for the database operation
• value: The model to delete or a slice for batch delete
• conditions: Additional conditions to filter records to delete

Returns:

• int64: Number of rows affected by the delete operation
• error: GORM error if the deletion fails, nil on success

Example:

// Delete user with ID=1
rowsAffected, err := db.Delete(ctx, &User{}, "id = ?", 1)
if err != nil {
    return err
}
fmt.Printf("Deleted %d rows\n", rowsAffected)

// Or with a model instance
user := User{ID: 1}
rowsAffected, err := db.Delete(ctx, &user)

func (*Postgres) Exec ¶

func (p *Postgres) Exec(ctx context.Context, sql string, values ...interface{}) (int64, error)

Exec executes raw SQL directly against the database. This is useful for operations not easily expressed through GORM's API or for performance-critical code.

Parameters:

• ctx: Context for the database operation
• sql: The SQL statement to execute
• values: Parameters for the SQL statement

Returns:

• int64: Number of rows affected by the SQL execution
• error: GORM error if the execution fails, nil on success

Example:

rowsAffected, err := db.Exec(ctx, "UPDATE users SET status = ? WHERE last_login < ?",
                             "inactive", time.Now().AddDate(0, -6, 0))
if err != nil {
    return err
}
fmt.Printf("Updated %d users\n", rowsAffected)

func (*Postgres) Find ¶

func (p *Postgres) Find(ctx context.Context, dest interface{}, conditions ...interface{}) error

Find retrieves records from the database that match the given conditions. It populates the dest parameter with the query results.

Parameters:

• ctx: Context for the database operation
• dest: Pointer to a slice where the results will be stored
• conditions: Optional query conditions (follows GORM conventions)

Returns a GORM error if the query fails or nil on success. Use TranslateError() to convert to standardized error types if needed.

Example:

var users []User
err := db.Find(ctx, &users, "name LIKE ?", "%john%")

func (*Postgres) First ¶

func (p *Postgres) First(ctx context.Context, dest interface{}, conditions ...interface{}) error

First retrieves the first record that matches the given conditions. It populates the dest parameter with the result or returns an error if no matching record exists.

Parameters:

• ctx: Context for the database operation
• dest: Pointer to a struct where the result will be stored
• conditions: Optional query conditions (follows GORM conventions)

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 (*Postgres) GetErrorCategory ¶

func (p *Postgres) GetErrorCategory(err error) ErrorCategory

GetErrorCategory returns the category of the given error

func (*Postgres) GetMigrationStatus ¶

func (p *Postgres) GetMigrationStatus(ctx context.Context, migrationsDir string) ([]map[string]interface{}, error)

GetMigrationStatus returns the status of all migrations. It compares available migrations with those that have been applied to build a comprehensive status report.

Parameters:

• ctx: Context for database operations
• migrationsDir: Directory containing the migration SQL files

Returns a slice of maps with status information for each migration, or a wrapped error if the status cannot be determined. The error wraps the underlying GORM error with additional context.

Example:

status, err := db.GetMigrationStatus(ctx, "./migrations")
if err == nil {
    for _, m := range status {
        fmt.Printf("Migration %s: %v\n", m["id"], m["applied"])
    }
}

func (*Postgres) GracefulShutdown ¶

func (p *Postgres) GracefulShutdown() error

func (*Postgres) IsCritical ¶

func (p *Postgres) IsCritical(err error) bool

IsCritical returns true if the error indicates a serious system problem

func (*Postgres) IsRetryable ¶

func (p *Postgres) IsRetryable(err error) bool

IsRetryable returns true if the error might be resolved by retrying the operation

func (*Postgres) IsTemporary ¶

func (p *Postgres) IsTemporary(err error) bool

IsTemporary returns true if the error is likely temporary and might resolve itself

func (*Postgres) MigrateDown ¶

func (p *Postgres) MigrateDown(ctx context.Context, migrationsDir string) error

MigrateDown rolls back the last applied migration. It finds the most recently applied migration and executes its corresponding down migration to revert the changes.

Parameters:

• ctx: Context for database operations
• migrationsDir: Directory containing the migration SQL files

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:

err := db.MigrateDown(ctx, "./migrations")

func (*Postgres) MigrateUp ¶

func (p *Postgres) MigrateUp(ctx context.Context, migrationsDir string) error

MigrateUp applies all pending migrations from the specified directory. It identifies which migrations haven't been applied yet, sorts them by ID, and applies them in order within transactions.

Parameters:

• ctx: Context for database operations
• migrationsDir: Directory containing the migration SQL files

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:

err := db.MigrateUp(ctx, "./migrations")

func (*Postgres) MonitorConnection ¶

func (p *Postgres) MonitorConnection(ctx context.Context)

MonitorConnection periodically checks the health of the database connection and triggers reconnection attempts when necessary. It runs as a goroutine that performs health checks at regular intervals (10 seconds) and signals the RetryConnection goroutine when a failure is detected.

The function respects context cancellation and shutdown signals, ensuring proper resource cleanup and graceful termination when requested.

func (*Postgres) Query ¶

func (p *Postgres) Query(ctx context.Context) QueryBuilder

Query provides a flexible way to build complex queries. It returns a QueryBuilder interface which can be used to chain query methods in a fluent interface. The builder snapshots the current `*gorm.DB` connection and does not hold any package-level locks while the chain is being built or executed.

Parameters:

• ctx: Context for the database operation

Returns a QueryBuilder interface instance that can be used to construct the query.

Note: QueryBuilder methods return GORM errors directly. Use Postgres.TranslateError() to convert them to standardized error types if needed.

Example:

users := []User{}
err := db.Query(ctx).
    Where("age > ?", 18).
    Order("created_at DESC").
    Limit(10).
    Find(&users)
if err != nil {
    err = db.TranslateError(err) // Optional: translate to standardized error
}

func (*Postgres) RetryConnection ¶

func (p *Postgres) RetryConnection(ctx context.Context)

RetryConnection continuously attempts to reconnect to the PostgresSQL database when notified of a connection failure. It operates as a goroutine that waits for signals on retryChanSignal before attempting reconnection. The function respects context cancellation and shutdown signals, ensuring graceful termination when requested.

It implements two nested loops: - The outer loop waits for retry signals - The inner loop attempts reconnection until successful

func (*Postgres) Save ¶

func (p *Postgres) Save(ctx context.Context, value interface{}) error

Save updates the database record if the primary key exists, otherwise it creates a new record. It performs a full update of all fields, not just changed fields.

Parameters:

• ctx: Context for the database operation
• value: The struct to be saved

Returns a GORM error if the operation fails or nil on success. Use TranslateError() to convert to standardized error types if needed.

Example:

user.Name = "Updated Name"
err := db.Save(ctx, &user)

func (*Postgres) Transaction ¶

func (p *Postgres) Transaction(ctx context.Context, fn func(tx Client) error) error

Transaction executes the given function within a database transaction. It creates a transaction-specific Postgres instance and passes it as Client interface. If the function returns an error, the transaction is rolled back; otherwise, it's committed.

This method provides a clean way to execute multiple database operations as a single atomic unit, with automatic handling of commit/rollback based on the execution result.

Returns a GORM error if the transaction fails or the error returned by the callback function.

Example usage:

err := pg.Transaction(ctx, func(tx Client) error {
	if err := tx.Create(ctx, user); err != nil {
		return err
	}
	return tx.Create(ctx, userProfile)
})

func (*Postgres) TranslateError ¶

func (p *Postgres) TranslateError(err error) error

TranslateError converts GORM/database-specific errors into standardized application errors. This function provides abstraction from the underlying database implementation details, allowing application code to handle errors in a database-agnostic way.

It maps common database errors to the standardized error types defined above. If an error doesn't match any known type, it's returned unchanged.

func (*Postgres) Update ¶

func (p *Postgres) Update(ctx context.Context, model interface{}, attrs interface{}) (int64, error)

Update updates records that match the given model's non-zero fields or primary key. It only updates the fields provided in attrs and only affects records that match the model's primary key or query conditions.

Parameters:

• ctx: Context for the database operation
• model: The model instance with primary key set, or struct with query conditions
• attrs: Map, struct, or individual field values to update

Returns:

• int64: Number of rows affected by the update operation
• 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.

Example:

// Update user with ID=1
rowsAffected, err := db.Update(ctx, &User{ID: 1}, map[string]interface{}{
    "name": "New Name",
    "age": 30,
})
if err != nil {
    return err
}
fmt.Printf("Updated %d rows\n", rowsAffected)

func (*Postgres) UpdateColumn ¶

func (p *Postgres) UpdateColumn(ctx context.Context, model interface{}, columnName string, value interface{}) (int64, error)

UpdateColumn updates a single column's value for records that match the given model. Unlike Update, it doesn't run hooks and can be used to update fields that are zero values (like setting a string to empty or a number to zero).

Parameters:

• ctx: Context for the database operation
• model: The model instance with primary key set, or struct with query conditions
• columnName: Name of the column to update
• value: New value for the column

Returns:

• int64: Number of rows affected by the update operation
• error: GORM error if the update fails, nil on success

Example:

// Set status to "inactive" for user with ID=1
rowsAffected, err := db.UpdateColumn(ctx, &User{ID: 1}, "status", "inactive")
if err != nil {
    return err
}
fmt.Printf("Updated %d rows\n", rowsAffected)

func (*Postgres) UpdateColumns ¶

func (p *Postgres) UpdateColumns(ctx context.Context, model interface{}, columnValues map[string]interface{}) (int64, error)

UpdateColumns updates multiple columns with name/value pairs for records that match the given model. Like UpdateColumn, it doesn't run hooks and can update zero-value fields.

Parameters:

• ctx: Context for the database operation
• model: The model instance with primary key set, or struct with query conditions
• columnValues: Map of column names to their new values

Returns:

• int64: Number of rows affected by the update operation
• error: GORM error if the update fails, nil on success

Example:

// Update multiple fields for user with ID=1
rowsAffected, err := db.UpdateColumns(ctx, &User{ID: 1}, map[string]interface{}{
    "status": "inactive",
    "last_login": time.Now(),
})
if err != nil {
    return err
}
fmt.Printf("Updated %d rows\n", rowsAffected)

func (*Postgres) UpdateWhere ¶

func (p *Postgres) UpdateWhere(ctx context.Context, model interface{}, attrs interface{}, condition string, args ...interface{}) (int64, error)

UpdateWhere updates records that match the specified WHERE condition. This method provides more flexibility than Update for complex conditions.

Parameters:

• ctx: Context for the database operation
• model: The model type to update
• attrs: Fields to update (map, struct, or name/value pairs)
• condition: WHERE condition as a string
• args: Arguments for the WHERE condition

Returns:

• int64: Number of rows affected by the update operation
• error: GORM error if the update fails, nil on success

Example:

// Update all users who haven't logged in for 6 months
rowsAffected, err := db.UpdateWhere(ctx, &User{},
                                    map[string]interface{}{"status": "inactive"},
                                    "last_login < ?",
                                    time.Now().AddDate(0, -6, 0))
if err != nil {
    return err
}
fmt.Printf("Updated %d users to inactive status\n", rowsAffected)

func (*Postgres) WithLogger ¶ added in v0.13.0

func (p *Postgres) WithLogger(logger Logger) *Postgres

WithLogger attaches a logger to the Postgres client for internal logging. This method uses the builder pattern and returns the client for method chaining.

The logger will be used for lifecycle events, connection monitoring, and background operations.

Example:

client, err := postgres.NewPostgres(config)
if err != nil {
    return err
}
client = client.WithLogger(myLogger)
defer client.GracefulShutdown()

func (*Postgres) WithObserver ¶ added in v0.13.0

func (p *Postgres) WithObserver(observer observability.Observer) *Postgres

WithObserver attaches an observer to the Postgres client for observability hooks. This method uses the builder pattern and returns the client for method chaining.

The observer will be notified of all database operations, allowing external systems to track metrics, traces, or other observability data.

Example:

client, err := postgres.NewPostgres(config)
if err != nil {
    return err
}
client = client.WithObserver(myObserver)
defer client.GracefulShutdown()