Documentation
¶
Overview ¶
Package containers provides Docker container management for PostgreSQL test environments. It leverages testcontainers to automatically manage PostgreSQL container lifecycle, making it easy to spin up isolated PostgreSQL instances for integration testing.
The package provides:
- Container type for managing PostgreSQL Docker containers
- Automatic container creation and cleanup
- Integration with the postgresenv Connector system
- Flexible configuration options
Example Usage:
// Create a new PostgreSQL container
cnt := containers.NewContainer(
containers.WithLogger(log.New(os.Stdout, "", log.LstdFlags)),
)
// Create connector with container options
connector := postgresenv.NewConnector(cnt.ConnectorOptions()...)
// Ensure cleanup
defer connector.Close()
// Connect to PostgreSQL
pool, err := connector.Connect(ctx, nil)
if err != nil {
return err
}
defer pool.Close()
// Use the pool...
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
func NewContainer ¶
func NewContainer( opts ...ContainerOption, ) *Container
NewContainer creates a new PostgreSQL container for testing. This function initializes container configuration but does not immediately start the container. The container is started lazily when the first connection is requested via the ConnectorOptions.
Container Creation Process:
- Creates container configuration
- Sets up lifecycle hooks for automatic startup
- Returns container ready for use with connectors
The container uses sensible defaults:
- PostgreSQL 16-alpine image
- Automatic port mapping
- Default credentials (user: test, password: test, database: test)
- Health check waiting strategy
Example:
// Create with defaults cnt := containers.NewContainer() // Create with custom logger cnt := containers.NewContainer( containers.WithLogger(myLogger), )
func (*Container) Close ¶
Close stops and removes the PostgreSQL container. This method cleans up all resources associated with the container.
Cleanup Process:
- Stops the Docker container
- Removes the container
- Releases all resources
Close should be called when the container is no longer needed. After Close is called, the container should not be used to create new connections.
This method is typically called automatically via the CloseHook when the connector is closed.
func (*Container) ConnectorOptions ¶
func (c *Container) ConnectorOptions() []postgresenv.ConnectorOption
ConnectorOptions returns connector options for connecting to this container. These options can be passed to postgresenv.NewConnector to create a connector that automatically manages the container lifecycle.
The returned options include:
- BeforeConnectHook: Starts the container before first connection
- CloseHook: Stops the container when connector is closed
- Connection parameters (host, port, credentials)
This method implements lazy container initialization - the container is only started when the first connection is requested.
Example:
cnt := containers.NewContainer() connector := postgresenv.NewConnector(cnt.ConnectorOptions()...) defer connector.Close() // Container starts automatically on first Connect call pool, err := connector.Connect(ctx, nil)
func (*Container) Launch ¶
Launch starts the PostgreSQL container if not already running. This method is called automatically by the BeforeConnectHook when the first connection is requested.
Container Startup Process:
- Creates container request with PostgreSQL configuration
- Starts the Docker container
- Waits for PostgreSQL to be ready (health check)
- Retrieves connection information (host, port)
This method is idempotent - if the container is already running, it returns immediately without starting a new container.
type ContainerOption ¶
type ContainerOption func(*Container)
ContainerOption is a function that configures a Container. Options can be passed to NewContainer to customize the container's behavior.
func WithLogger ¶
func WithLogger(logger *log.Logger) ContainerOption
WithLogger sets a custom logger for the container. The logger is used to log container lifecycle events and any issues that occur during container management.
If not set, a default no-op logger is used that discards all log output.
Example:
cnt := containers.NewContainer( containers.WithLogger(log.New(os.Stdout, "", log.LstdFlags)), )
Source Files