postgres

Documentation

Index

• func BasicWaitStrategies() testcontainers.CustomizeRequestOption
• func WithConfigFile(cfg string) testcontainers.CustomizeRequestOption
• func WithDatabase(dbName string) testcontainers.CustomizeRequestOption
• func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption
• func WithPassword(password string) testcontainers.CustomizeRequestOption
• func WithUsername(user string) testcontainers.CustomizeRequestOption
• type Option
  • func WithSQLDriver(driver string) Option
  • func (o Option) Customize(*testcontainers.GenericContainerRequest) error
• type PostgresContainer
  • func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*PostgresContainer, error)
  • func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*PostgresContainer, error)
  • func (c *PostgresContainer) ConnectionString(ctx context.Context, args ...string) (string, error)
  • func (c *PostgresContainer) MustConnectionString(ctx context.Context, args ...string) string
  • func (c *PostgresContainer) Restore(ctx context.Context, opts ...SnapshotOption) error
  • func (c *PostgresContainer) Snapshot(ctx context.Context, opts ...SnapshotOption) error
• type SnapshotOption
  • func WithSnapshotName(name string) SnapshotOption

Examples

• Run

Functions

func BasicWaitStrategies

func BasicWaitStrategies() testcontainers.CustomizeRequestOption

BasicWaitStrategies is a simple but reliable way to wait for postgres to start. It returns a two-step wait strategy:

• It will wait for the container to log `database system is ready to accept connections` twice, because it will restart itself after the first startup.
• It will then wait for docker to actually serve the port on localhost. For non-linux OSes like Mac and Windows, Docker or Rancher Desktop will have to start a separate proxy. Without this, the tests will be flaky on those OSes!

func WithConfigFile

func WithConfigFile(cfg string) testcontainers.CustomizeRequestOption

WithConfigFile sets the config file to be used for the postgres container It will also set the "config_file" parameter to the path of the config file as a command line argument to the container

func WithDatabase

func WithDatabase(dbName string) testcontainers.CustomizeRequestOption

WithDatabase sets the initial database to be created when the container starts It can be used to define a different name for the default database that is created when the image is first started. If it is not specified, then the value of WithUser will be used.

func WithInitScripts

func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption

WithInitScripts sets the init scripts to be run when the container starts

func WithPassword

func WithPassword(password string) testcontainers.CustomizeRequestOption

WithPassword sets the initial password of the user to be created when the container starts It is required for you to use the PostgreSQL image. It must not be empty or undefined. This environment variable sets the superuser password for PostgreSQL.

func WithUsername

func WithUsername(user string) testcontainers.CustomizeRequestOption

WithUsername sets the initial username to be created when the container starts It is used in conjunction with WithPassword to set a user and its password. It will create the specified user with superuser power and a database with the same name. If it is not specified, then the default user of postgres will be used.

Types

type Option

type Option func(*options)

Option is an option for the Redpanda container.

func WithSQLDriver

func WithSQLDriver(driver string) Option

WithSQLDriver sets the SQL driver to use for the container. It is passed to sql.Open() to connect to the database when making or restoring snapshots. This can be set if your app imports a different postgres driver, f.ex. "pgx"

func (Option) Customize

func (o Option) Customize(*testcontainers.GenericContainerRequest) error

Customize is a NOOP. It's defined to satisfy the testcontainers.ContainerCustomizer interface.

type PostgresContainer

type PostgresContainer struct {
	testcontainers.Container
	// contains filtered or unexported fields
}

PostgresContainer represents the postgres container type used in the module

func Run

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*PostgresContainer, error)

Run creates an instance of the Postgres container type

Example

// runPostgresContainer {
ctx := context.Background()

dbName := "users"
dbUser := "user"
dbPassword := "password"

postgresContainer, err := postgres.Run(ctx,
	"docker.io/postgres:16-alpine",
	postgres.WithInitScripts(filepath.Join("testdata", "init-user-db.sh")),
	postgres.WithConfigFile(filepath.Join("testdata", "my-postgres.conf")),
	postgres.WithDatabase(dbName),
	postgres.WithUsername(dbUser),
	postgres.WithPassword(dbPassword),
	testcontainers.WithWaitStrategy(
		wait.ForLog("database system is ready to accept connections").
			WithOccurrence(2).
			WithStartupTimeout(5*time.Second)),
)
defer func() {
	if err := testcontainers.TerminateContainer(postgresContainer); err != nil {
		log.Printf("failed to terminate container: %s", err)
	}
}()
if err != nil {
	log.Printf("failed to start container: %s", err)
	return
}
// }

state, err := postgresContainer.State(ctx)
if err != nil {
	log.Printf("failed to get container state: %s", err)
	return
}

fmt.Println(state.Running)

Output:

true

func RunContainer

func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*PostgresContainer, error)

Deprecated: use Run instead RunContainer creates an instance of the Postgres container type

func (*PostgresContainer) ConnectionString

func (c *PostgresContainer) ConnectionString(ctx context.Context, args ...string) (string, error)

ConnectionString returns the connection string for the postgres container, using the default 5432 port, and obtaining the host and exposed port from the container. It also accepts a variadic list of extra arguments which will be appended to the connection string. The format of the extra arguments is the same as the connection string format, e.g. "connect_timeout=10" or "application_name=myapp"

func (*PostgresContainer) MustConnectionString

func (c *PostgresContainer) MustConnectionString(ctx context.Context, args ...string) string

MustConnectionString panics if the address cannot be determined.

func (*PostgresContainer) Restore

func (c *PostgresContainer) Restore(ctx context.Context, opts ...SnapshotOption) error

Restore will restore the database to a specific snapshot. By default, it will restore the last snapshot taken on the database by the Snapshot method. If a snapshot name is provided, it will instead try to restore the snapshot by name.

func (*PostgresContainer) Snapshot

func (c *PostgresContainer) Snapshot(ctx context.Context, opts ...SnapshotOption) error

Snapshot takes a snapshot of the current state of the database as a template, which can then be restored using the Restore method. By default, the snapshot will be created under a database called migrated_template, you can customize the snapshot name with the options. If a snapshot already exists under the given/default name, it will be overwritten with the new snapshot.

type SnapshotOption

type SnapshotOption func(container *snapshotConfig) *snapshotConfig

SnapshotOption is the type for passing options to the snapshot function of the database

func WithSnapshotName

func WithSnapshotName(name string) SnapshotOption

WithSnapshotName adds a specific name to the snapshot database created from the main database defined on the container. The snapshot must not have the same name as your main database, otherwise it will be overwritten