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)
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 Connection ¶ added in v0.2.1
type Connection struct {
// contains filtered or unexported fields
}
Connection contains the connection information for a PostgreSQL container. The fields are private and can only be accessed through the getter methods, ensuring read-only access to the container's connection configuration.
func (*Connection) Database ¶ added in v0.2.1
func (c *Connection) Database() string
Database returns the database name in the PostgreSQL container.
func (*Connection) Host ¶ added in v0.2.1
func (c *Connection) Host() string
Host returns the host address for connecting to the PostgreSQL container. This is typically "localhost" when running tests on the same machine as Docker.
func (*Connection) Password ¶ added in v0.2.1
func (c *Connection) Password() string
Password returns the password for authenticating to the PostgreSQL container.
func (*Connection) Port ¶ added in v0.2.1
func (c *Connection) Port() uint16
Port returns the externally mapped port for connecting to the PostgreSQL container. This is the port number mapped from the container's internal PostgreSQL port (5432).
func (*Connection) User ¶ added in v0.2.1
func (c *Connection) User() string
User returns the username for authenticating to the PostgreSQL container.
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) Connection ¶ added in v0.2.1
func (c *Container) Connection(ctx context.Context) (Connection, error)
Connection returns the complete connection information for the PostgreSQL container in a single call. This includes host, port, username, password, and database name.
This method retrieves the externally accessible network address of the container along with the authentication credentials, which can be used to establish connections from outside the Docker network.
The returned Connection struct provides read-only access to all connection parameters through its getter methods.
This method must be called after the container has been started (e.g., after Launch). Calling Connection before the container is running will result in an error.
Example:
conn, err := cnt.Connection(ctx)
if err != nil {
return err
}
fmt.Printf("Container: %s:%d user=%s database=%s\n",
conn.Host(), conn.Port(), conn.User(), conn.Database())
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)
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