postgresenv

type BeforeConnectHook ¶

type BeforeConnectHook func(ctx context.Context, cfg *pgxpool.Config) error

BeforeConnectHook is a function that is called before establishing a database connection. It allows modification of the connection configuration before the connection is created. This is useful for scenarios like:

• Starting a container before the first connection
• Modifying connection parameters based on runtime conditions
• Implementing custom connection initialization logic

Parameters:

• ctx: Context for cancellation and timeout
• cfg: Connection configuration that can be modified

Returns:

• error: Non-nil to prevent the connection from being established

Example:

hook := func(ctx context.Context, cfg *pgxpool.Config) error {
	// Start container on first connection
	return container.Start(ctx)
}

type CloseHook ¶

type CloseHook func() error

CloseHook is a function that is called when the connector is closed. It allows cleanup of resources associated with the connector. This is useful for scenarios like:

• Stopping containers when the connector is no longer needed
• Cleaning up external resources
• Releasing allocated resources

Returns:

• error: Non-nil if cleanup fails

Example:

hook := func() error {
	// Stop container when connector closes
	return container.Stop()
}

type Connector ¶

type Connector struct {
	// contains filtered or unexported fields
}

Connector manages database connections to a PostgreSQL instance. It provides a flexible connection management system with support for:

• Connection pooling via pgx
• Hook-based lifecycle management
• Service pool sharing across environments
• Configuration merging and overrides

Connector is designed to work with various PostgreSQL deployment scenarios:

• Local PostgreSQL instances
• Docker containers
• Cloud databases
• Test environments

Thread Safety: Connector is safe for concurrent use. The environmentsServicePools map is protected and can be accessed from multiple goroutines.

Example:

// Create connector with container lifecycle
cnt := containers.NewContainer()
connector := NewConnector(cnt.ConnectorOptions()...)

// Connect to database
pool, err := connector.Connect(ctx, nil)
if err != nil {
	return err
}
defer pool.Close()

// Use connection pool...

func NewConnector(opts ...ConnectorOption) *Connector

// Create connector with custom settings
connector := NewConnector(
	WithHost("localhost"),
	WithPort(5433),
	WithDatabase("testdb"),
	WithUser("testuser"),
	WithPassword("testpass"),
)

// Create connector with container lifecycle
cnt := containers.NewContainer()
connector := NewConnector(cnt.ConnectorOptions()...)

// Create connector with hooks
connector := NewConnector(
	WithBeforeConnectHook(func(ctx context.Context, cfg *pgxpool.Config) error {
		fmt.Println("Connecting to database...")
		return nil
	}),
	WithCloseHook(func() error {
		fmt.Println("Connector closed")
		return nil
	}),
)

func (c *Connector) Close() error

// Create connector with container
cnt := containers.NewContainer()
connector := NewConnector(cnt.ConnectorOptions()...)

// Use connector...
pool, _ := connector.Connect(ctx, nil)
defer pool.Close()

// Clean up when done
defer connector.Close() // This will also stop the container

func (c *Connector) Config() (*pgxpool.Config, error)

// Get base configuration
cfg, err := connector.Config()
if err != nil {
	return err
}

// Modify configuration
cfg.MaxConns = 10
cfg.ConnConfig.TLSConfig = &tls.Config{...}

// Use configuration
pool, err := pgxpool.NewWithConfig(ctx, cfg)

func (c *Connector) Connect(ctx context.Context, cfg *pgxpool.Config) (*pgxpool.Pool, error)

// Connect with default settings
pool, err := connector.Connect(ctx, nil)
if err != nil {
	return err
}
defer pool.Close()

// Connect with custom pool size
pool, err := connector.Connect(ctx, &pgxpool.Config{
	MaxConns: 10,
})

// Connect to different database
pool, err := connector.Connect(ctx, &pgxpool.Config{
	ConnConfig: &pgx.ConnConfig{
		Config: pgconn.Config{
			Database: "other_db",
		},
	},
})

type ConnectorOption ¶

type ConnectorOption func(*Connector)

ConnectorOption is a function that configures a Connector. Options can be passed to NewConnector to customize the connector's behavior.

func WithBeforeConnectHook(hook BeforeConnectHook) ConnectorOption

// Start container before first connection
cnt := containers.NewContainer()
connector := NewConnector(
	WithBeforeConnectHook(cnt.Launch),
	WithCloseHook(cnt.Close),
)

func WithCloseHook(hook CloseHook) ConnectorOption

// Stop container when connector closes
cnt := containers.NewContainer()
connector := NewConnector(
	WithBeforeConnectHook(cnt.Launch),
	WithCloseHook(cnt.Close),
)

func WithDatabase(databaseName string) ConnectorOption

connector := NewConnector(
	WithDatabase("myapp_test"),
)

func WithHost(host string) ConnectorOption

connector := NewConnector(
	WithHost("localhost"),
	WithPort(5432),
)

func WithPassword(password string) ConnectorOption

connector := NewConnector(
	WithUser("admin"),
	WithPassword("secret"),
)

func WithPort(port uint16) ConnectorOption

connector := NewConnector(
	WithPort(5433), // Non-standard port
)

func WithSchema(schema string) ConnectorOption

connector := NewConnector(
	WithSchema("myschema"),
)

func WithUser(user string) ConnectorOption

connector := NewConnector(
	WithUser("admin"),
	WithPassword("secret"),
)

type Environment ¶

type Environment struct {
	// contains filtered or unexported fields
}

Environment manages PostgreSQL connection pools with flexible reuse strategies. It provides a high-level interface for creating database connections with automatic resource management and isolation.

Environment supports different reuse strategies to balance isolation and performance:

• No strategy (default): Direct connection to PostgreSQL, no automatic cleanup
• CreateNewDB: Full isolation with a new database per connection
• CreateNewSchema: Good isolation with a new schema per connection

Environment integrates with the reuse package to efficiently manage connectors and resources across multiple connections and tests.

Thread Safety: Environment is safe for concurrent use. Multiple goroutines can call Connect concurrently, and each will receive an independent Pool.

Example:

// Create environment with container
cnt := containers.NewContainer()
env := postgresenv.New(
	postgresenv.WithConnectorReuseOptions(func() (*Connector, error) {
		return NewConnector(cnt.ConnectorOptions()...), nil
	}),
	postgresenv.WithReuseStrategy(&ReuseStrategyCreateNewDB{}),
	postgresenv.WithMaxConnsPerConnect(10),
)

// Connect
pool, err := env.Connect(ctx)
if err != nil {
	return err
}
defer pool.Close()

// Use pool...

func New(opts ...EnvironmentOption) *Environment

// Simple environment
env := postgresenv.New()

// Environment with container
cnt := containers.NewContainer()
env := postgresenv.New(
	postgresenv.WithConnectorReuseOptions(func() (*Connector, error) {
		return NewConnector(cnt.ConnectorOptions()...), nil
	}),
)

// Environment with all options
env := postgresenv.New(
	postgresenv.WithReuseStrategy(&ReuseStrategyCreateNewDB{}),
	postgresenv.WithConnectorReuseOptions(connectorFactory),
	postgresenv.WithMaxConnsPerConnect(10),
)

func (e *Environment) Connect(ctx context.Context) (*Pool, error)

pool, err := env.Connect(ctx)
if err != nil {
	return err
}
defer pool.Close()

// Use pool.Pool for database operations
rows, err := pool.Pool.Query(ctx, "SELECT * FROM users")

type EnvironmentOption ¶

type EnvironmentOption func(*Environment)

EnvironmentOption is a function that configures an Environment. Options can be passed to New to customize the environment's behavior.

func WithConnectorReuseOptions(
	createFunc func() (*Connector, error),
	opts ...reuse.Option[*Connector],
) EnvironmentOption

func WithMaxConnsPerConnect(maxConnPerConnect int32) EnvironmentOption

env := postgresenv.New(
	postgresenv.WithMaxConnsPerConnect(10),
)

func WithReuseStrategy(strategy ReuseStrategy) EnvironmentOption

// Create new database per connection
env := postgresenv.New(
	postgresenv.WithReuseStrategy(&ReuseStrategyCreateNewDB{}),
)

// Create new schema per connection
env := postgresenv.New(
	postgresenv.WithReuseStrategy(&ReuseStrategyCreateNewSchema{
		DB: "mydb",
	}),
)

type Pool ¶

type Pool struct {
	// Pool is the underlying pgx connection pool ready for database operations.
	Pool *pgxpool.Pool
	// contains filtered or unexported fields
}

Pool represents a database connection pool with lifecycle management. It wraps a pgxpool.Pool with automatic cleanup and connector reuse tracking.

Pool instances are created by Environment.Connect and should be closed using the Close method when no longer needed. The Close method handles both pool cleanup and connector lifecycle management.

Thread Safety: Pool is safe for concurrent use. The underlying pgxpool.Pool handles connection pooling and concurrent access safely.

Example:

env := postgresenv.New(
	postgresenv.WithConnectorReuseOptions(connectorFactory),
)

pool, err := env.Connect(ctx)
if err != nil {
	return err
}
defer pool.Close()

// Use pool.Pool for database operations
rows, err := pool.Pool.Query(ctx, "SELECT * FROM users")

func (p *Pool) Close()

pool, err := env.Connect(ctx)
if err != nil {
	return err
}
defer pool.Close()

// Use pool...

type ReuseStrategy ¶

type ReuseStrategy interface {
	// contains filtered or unexported methods
}

ReuseStrategy defines the strategy for reusing database resources across multiple connections. Different strategies provide different levels of isolation and performance characteristics.

Implementations:

• ReuseStrategyCreateNewDB: Creates a new database for each connection
• ReuseStrategyCreateNewSchema: Creates a new schema in a shared database
• nil (default): Uses raw PostgreSQL connection without additional isolation

type ReuseStrategyCreateNewDB ¶

type ReuseStrategyCreateNewDB struct {
	// NewDBName is a function that generates a unique database name.
	// If nil, a default name generator is used that creates names like
	// "public123456789" using random numbers.
	//
	// The function should return a unique name each time it's called.
	// Names are automatically converted to lowercase.
	NewDBName func() string
}

ReuseStrategyCreateNewDB creates a new database for each connection. This provides complete isolation between tests but may be slower due to database creation overhead.

Each time Connect is called, a new database is created with a unique name. When the pool is closed, the database is automatically dropped.

Use this strategy when:

• You need complete isolation between tests
• Tests modify database-level settings
• Tests create/drop tables, indexes, or other database objects

Example:

env := postgresenv.New(
	postgresenv.WithReuseStrategy(&postgresenv.ReuseStrategyCreateNewDB{
		NewDBName: func() string {
			return "testdb_" + uuid.New().String()
		},
	}),
	postgresenv.WithConnectorReuseOptions(connectorFactory),
)

type ReuseStrategyCreateNewSchema ¶

type ReuseStrategyCreateNewSchema struct {
	// DB is the name of the database in which to create schemas.
	// This database must already exist.
	DB string

	// NewSchemaName is a function that generates a unique schema name.
	// If nil, a default name generator is used that creates names like
	// "public123456789" using random numbers.
	//
	// The function should return a unique name each time it's called.
	// Names are automatically converted to lowercase.
	NewSchemaName func() string
}

ReuseStrategyCreateNewSchema creates a new schema in an existing database for each connection. This provides good isolation with better performance than creating new databases.

Each time Connect is called, a new schema is created within the specified database. When the pool is closed, the schema is automatically dropped.

Use this strategy when:

• You want good isolation but better performance than creating databases
• Tests only create/drop tables and other schema-level objects
• Multiple tests need to share the same database but not the same schema

Example:

env := postgresenv.New(
	postgresenv.WithReuseStrategy(&postgresenv.ReuseStrategyCreateNewSchema{
		DB: "mydb", // Use existing database
		NewSchemaName: func() string {
			return "testschema_" + uuid.New().String()
		},
	}),
	postgresenv.WithConnectorReuseOptions(connectorFactory),
)

type StdlibEnvironment ¶

type StdlibEnvironment struct {
	// contains filtered or unexported fields
}

StdlibEnvironment wraps a pgx-based Environment to provide standard library database/sql compatibility.

This allows projects that use the standard *sql.DB interface to work seamlessly with the testenv framework. The wrapper handles the conversion between pgx connection pools and standard library connections while maintaining all the benefits of the testenv environment management.

Key Features:

• Provides *sql.DB instead of *pgxpool.Pool
• Maintains all environment benefits (reuse strategies, cleanup, etc.)
• Automatic resource cleanup when DB is closed
• Full compatibility with database/sql ecosystem

Example:

// Create base environment with container
cnt := containers.NewContainer()
env := postgresenv.New(
	postgresenv.WithConnectorReuseOptions(func() (*Connector, error) {
		return NewConnector(cnt.ConnectorOptions()...), nil
	}),
	postgresenv.WithReuseStrategy(&ReuseStrategyCreateNewDB{}),
)

// Wrap with stdlib compatibility
stdlibEnv := postgresenv.NewStdlib(env)

// Connect using standard library
db, err := stdlibEnv.Connect(ctx)
if err != nil {
	return err
}
defer db.Close()

// Use standard *sql.DB
rows, err := db.QueryContext(ctx, "SELECT * FROM users")

func NewStdlib(
	env *Environment,
	opts ...stdlib.OptionOpenDB,
) *StdlibEnvironment

// Create base environment
cnt := containers.NewContainer()
env := postgresenv.New(
	postgresenv.WithConnectorReuseOptions(func() (*Connector, error) {
		return NewConnector(cnt.ConnectorOptions()...), nil
	}),
	postgresenv.WithReuseStrategy(&ReuseStrategyCreateNewDB{}),
)

// Wrap for stdlib compatibility
stdlibEnv := postgresenv.NewStdlib(env)

// Use with dbenv helpers
db := dbenv.UseForTesting(t, stdlibEnv)

stdlibEnv := postgresenv.NewStdlib(env,
	stdlib.OptionBeforeAcquire(func(ctx context.Context, conn *pgx.Conn) bool {
		// Custom connection validation
		return conn.Ping(ctx) == nil
	}),
)

func (d *StdlibEnvironment) Connect(ctx context.Context) (*sql.DB, error)

db, err := stdlibEnv.Connect(ctx)
if err != nil {
	return err
}
defer db.Close()

// Standard library usage
var count int
err = db.QueryRowContext(ctx, "SELECT COUNT(*) FROM users").Scan(&count)
if err != nil {
	return err
}

fmt.Printf("User count: %d\n", count)