feat: add Postgres module (#945)

* chore: move postgres module from examples to modules * chore: export types and entrypoint * docs: document opts * chore: remove withPort opt * docs: document types * chore: add WithInitDBArgs * chore: add WithImage * docs: link to Docker Hub * docs: reorder * chore: support retrieving the connection strinng of the container * chore: add tests for timescale and postgis * chore: support for init scripts * chore: extract to constant * fix: update module name * chore: support for extra args for the connection string * chore: wait longer for postgis * docs: include how to configure the connection string * chore: remove WithInitDBArgs Avoid mapping any configuration from the underlying image * chore: separate withInitDatabase in three methods * chore: support for copying the config file
testcontainers · Mar 23, 2023 · e843b72 · e843b72
1 parent dd66783
commit e843b72
Show file tree

Hide file tree

Showing 15 changed files with 1,195 additions and 185 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -54,12 +54,6 @@ updates:
         interval: monthly
       open-pull-requests-limit: 3
       rebase-strategy: disabled
-    - package-ecosystem: gomod
-      directory: /examples/postgres
-      schedule:
-        interval: monthly
-      open-pull-requests-limit: 3
-      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /examples/pubsub
       schedule:
@@ -108,6 +102,12 @@ updates:
         interval: monthly
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/postgres
+      schedule:
+        interval: monthly
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /modules/pulsar
       schedule:

diff --git a/.github/workflows/postgres-example.yml → .github/workflows/module-postgres.yml b/.github/workflows/postgres-example.yml → .github/workflows/module-postgres.yml
@@ -1,4 +1,4 @@
-name: Postgres example pipeline
+name: Postgres module pipeline
 
 on: [push, pull_request]
 
@@ -24,15 +24,15 @@ jobs:
         uses: actions/checkout@v3
 
       - name: modVerify
-        working-directory: ./examples/postgres
+        working-directory: ./modules/postgres
         run: go mod verify
 
       - name: modTidy
-        working-directory: ./examples/postgres
+        working-directory: ./modules/postgres
         run: make tools-tidy
 
       - name: gotestsum
-        working-directory: ./examples/postgres
+        working-directory: ./modules/postgres
         run: make test-unit
 
       - name: Run checker

diff --git a/docs/examples/postgres.md b/docs/examples/postgres.md
diff --git a/docs/modules/postgres.md b/docs/modules/postgres.md
@@ -0,0 +1,104 @@
+# Postgres
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Postgres module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/postgres
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a Postgres container](../../modules/postgres/postgres_test.go) inside_block:postgresCreateContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The Postgres module exposes one entrypoint function to create the Postgres container, and this function receives two parameters:
+
+```golang
+func StartContainer(ctx context.Context, opts ...PostgresContainerOption) (*PostgresContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `PostgresContainerOption`, a variad argument for passing options.
+
+### Container Options
+
+When starting the Postgres container, you can pass options in a variadic way to configure it.
+
+!!!tip
+    You can find all the available configuration and environment variables for the Postgres Docker image on [Docker Hub](https://hub.docker.com/_/postgres).
+
+#### Image
+
+If you need to set a different Postgres Docker image, you can use `WithImage` with a valid Docker image
+for Postgres. E.g. `WithImage("docker.io/postgres:9.6")`.
+
+#### Initial Database
+
+If you need to set a different database, and its credentials, you can use the `WithInitialDatabase`.
+
+<!--codeinclude-->
+[Set Initial database](../../modules/postgres/postgres_test.go) inside_block:withInitialDatabase
+<!--/codeinclude-->
+
+#### Init Scripts
+
+If you would like to do additional initialization in the Postgres container, add one or more `*.sql`, `*.sql.gz`, or `*.sh` scripts to the container request.
+Those files will be copied after the container is created but before it's started under `/docker-entrypoint-initdb.d`. According to Postgres Docker image,
+it will run any `*.sql` files, run any executable `*.sh` scripts, and source any non-executable `*.sh` scripts found in that directory to do further
+initialization before starting the service.
+
+<!--codeinclude-->
+[Include init scripts](../../modules/postgres/postgres_test.go) inside_block:withInitScripts
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Init script content](../../modules/postgres/testresources/init-user-db.sh)
+<!--/codeinclude-->
+
+#### Database configuration
+
+In the case you have a custom config file for Postgres, it's possible to copy that file into the container before it's started.
+
+!!!tip
+    For information on what is available to configure, see the [PostgreSQL docs](https://www.postgresql.org/docs/14/runtime-config.html) for the specific version of PostgreSQL that you are running. 
+
+<!--codeinclude-->
+[Include custom configuration file](../../modules/postgres/postgres_test.go) inside_block:withConfigFile
+<!--/codeinclude-->
+
+#### Wait Strategies
+
+Given you could need to wait for different conditions, in particular using a wait.ForSQL strategy,
+the Postgres container exposes a `WithWaitStrategy` option to set a custom wait strategy.
+
+<!--codeinclude-->
+[Set Wait Strategy](../../modules/postgres/postgres_test.go) inside_block:withWaitStrategy
+<!--/codeinclude-->
+
+### Container Methods
+
+#### ConnectionString
+
+This method returns the connection string to connect to the Postgres container, using the default `5432` port and SSL disabled.
+It's possible to pass extra parameters to the connection string, e.g. `application_name=myapp`, in a variadic way.
+
+<!--codeinclude-->
+[Get connection string](../../modules/postgres/postgres_test.go) inside_block:connectionString
+<!--/codeinclude-->
+
+### Postgres variants
+
+It's possible to use the Postgres container with Timescale or Postgis, to name a few. You simply need to update the image name and the wait strategy.
+
+<!--codeinclude-->
+[Image for Timescale](../../modules/postgres/postgres_test.go) inside_block:timescale
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Image for Postgis](../../modules/postgres/postgres_test.go) inside_block:postgis
+<!--/codeinclude-->
diff --git a/examples/postgres/postgres.go b/examples/postgres/postgres.go
diff --git a/examples/postgres/postgres_test.go b/examples/postgres/postgres_test.go
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -53,6 +53,7 @@ nav:
         - modules/index.md
         - modules/couchbase.md
         - modules/localstack.md
+        - modules/postgres.md
         - modules/pulsar.md
     - Examples:
         - examples/index.md
@@ -64,7 +65,6 @@ nav:
         - examples/mongodb.md
         - examples/mysql.md
         - examples/nginx.md
-        - examples/postgres.md
         - examples/pubsub.md
         - examples/redis.md
         - examples/spanner.md

diff --git a/examples/postgres/Makefile → modules/postgres/Makefile b/examples/postgres/Makefile → modules/postgres/Makefile
diff --git a/examples/postgres/go.mod → modules/postgres/go.mod b/examples/postgres/go.mod → modules/postgres/go.mod
@@ -1,4 +1,4 @@
-module github.com/testcontainers/testcontainers-go/examples/postgres
+module github.com/testcontainers/testcontainers-go/modules/postgres
 
 go 1.19
 

diff --git a/examples/postgres/go.sum → modules/postgres/go.sum b/examples/postgres/go.sum → modules/postgres/go.sum