Added config property to run the Container with a fixed name. Updated README and enhanced other documentation.

Author: quinnandrews

README.md

@@ -43,27 +43,37 @@ public class PostgreSQLContainerConfig {
     private static final Logger logger = LoggerFactory.getLogger(PostgreSQLContainerConfig.class);
 
     private final String containerImage;
+    private final String containerName;
     private final Integer containerPort;
     private final Boolean followContainerLog;
     private final String databaseName;
     private final String username;
     private final String password;
     private final String initScript;
+    private final String applicationUsername;
+    private final String applicationPassword;
 
     /**
      * Constructs an instance of this Configuration Class with the given properties.
      *
      * @param containerImage      The Docker Image to use as the Container (optional).
+     * @param containerName       The name to use for the Docker Container when started.
      * @param containerPort       The port on the Container that should map to PostgreSQL (optional).
-     * @param followContainerLog  Whether to log the log output produced by the Container (optional).
+     * @param followContainerLog  Whether to log the output produced by the Container's logs (optional).
      * @param databaseName        The name for the database (optional).
-     * @param username            The username of the database super/admin user (optional).
+     * @param username            The username for the database super/admin user (optional).
      * @param password            The password for the database super/admin user (optional).
+     * @param applicationUsername The username for the database user the Application should connect with,
+     *                            if different from the super/admin user (optional).
+     * @param applicationPassword The password for the database user the Application should connect with,
+     *                            if different from the super/admin user (optional).
      * @param initScript          The path to an SQL script that should be executed when the Container
      *                            starts (optional).
      */
     public PostgreSQLContainerConfig(@Value("${spring.local.postgresql.container.image:#{null}}")
                                      final String containerImage,
+                                     @Value("${spring.local.postgresql.container.name:#{null}}")
+                                     final String containerName,
                                      @Value("${spring.local.postgresql.container.port:#{null}}")
                                      final Integer containerPort,
                                      @Value("${spring.local.postgresql.container.log.follow:#{false}}")
@@ -74,19 +84,26 @@ public PostgreSQLContainerConfig(@Value("${spring.local.postgresql.container.ima
                                      final String username,
                                      @Value("${spring.local.postgresql.database.password:#{null}}")
                                      final String password,
+                                     @Value("${spring.local.postgresql.database.application.username:#{null}}")
+                                     final String applicationUsername,
+                                     @Value("${spring.local.postgresql.database.application.password:#{null}}")
+                                     final String applicationPassword,
                                      @Value("${spring.local.postgresql.database.init.script:#{null}}")
                                      final String initScript) {
         this.containerImage = containerImage;
+        this.containerName = containerName;
         this.containerPort = containerPort;
         this.followContainerLog = followContainerLog;
         this.databaseName = databaseName;
         this.username = username;
         this.password = password;
+        this.applicationUsername = applicationUsername;
+        this.applicationPassword = applicationPassword;
         this.initScript = initScript;
     }
 
     /**
-     * Initializes a Testcontainers Bean that runs PostgreSQL inside a Docker Container
+     * Returns a Testcontainers Bean that runs PostgreSQL inside a Docker Container
      * with the given configuration.
      *
      * @return PostgreSQLContainer
@@ -99,12 +116,14 @@ public PostgreSQLContainer<?> postgreSQLContainer() {
                         .orElse(POSTGRESQL_DEFAULT_IMAGE))
         );
         Optional.ofNullable(containerPort).ifPresent(cp ->
-                container.withCreateContainerCmdModifier(cmd -> cmd.withHostConfig(
-                        new HostConfig().withPortBindings(
-                                new PortBinding(Ports.Binding.bindPort(cp),
-                                new ExposedPort(PostgreSQLContainer.POSTGRESQL_PORT)))
-                ))
-        );
+                container.withCreateContainerCmdModifier(cmd -> cmd
+                        .withName(containerName)
+                        .withHostConfig(
+                                new HostConfig().withPortBindings(
+                                        new PortBinding(
+                                                Ports.Binding.bindPort(cp),
+                                                new ExposedPort(PostgreSQLContainer.POSTGRESQL_PORT))
+                                ))));
         if (followContainerLog) {
             container.withLogConsumer(new Slf4jLogConsumer(logger));
         }
@@ -121,32 +140,40 @@ public PostgreSQLContainer<?> postgreSQLContainer() {
                         
                             Running PostgreSQLContainer for development and testing.
                         
-                            Built with Docker Image: {0}
+                            Container: {0}
+                            Image: {1}
+                            Port Mapping: {2}:{3}
+                        
+                            Use the credentials below to connect with your client of choice (DBeaver,
+                            IntelliJ IDEA, etc.):
+                        
+                            JDBC URL: {4}
+                            Admin User Username: {5}
+                            Admin User Password: {6}
+                            Application User Username: {7}
+                            Application User Password: {8}
                         
-                            Use the credentials below to connect your client of choice (DBeaver,
-                            IntelliJ IDEA, etc.) to the PostgreSQL server inside the container:
-                                        
-                            JDBC URL: {1}
-                            Username: {2}
-                            Password: {3}
-
-                            Note: The port referenced in the JDBC URL is a port to access the
-                            container. Inside the container PostgreSQL is on port 5432 as usual.
-                                  
                         |+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|+|
                         *************************************************************************************
                         """,
+                container.getContainerName(),
                 container.getDockerImageName(),
+                String.valueOf(container.getMappedPort(PostgreSQLContainer.POSTGRESQL_PORT)),
+                String.valueOf(PostgreSQLContainer.POSTGRESQL_PORT),
                 container.getJdbcUrl(),
                 container.getUsername(),
-                container.getPassword()));
+                container.getPassword(),
+                Optional.ofNullable(applicationUsername)
+                        .orElse("[not configured]"),
+                Optional.ofNullable(applicationPassword)
+                        .orElse("[not configured]")));
         return container;
     }
 
     /**
      * Initializes a Spring Bean connecting the Application to the PostgreSQLContainer.
      *
-     * @param applicationUsername The username of the database user the Application should connect with,
+     * @param applicationUsername The username for the database user the Application should connect with,
      *                            if different from the super/admin user (optional).
      * @param applicationPassword The password for the database user the Application should connect with,
      *                            if different from the super/admin user (optional).

src/main/java/io/github/quinnandrews/spring/local/postgresql/config/PostgreSQLContainerConfig.java

@@ -3,61 +3,67 @@
     {
       "name": "spring.local.postgresql.engaged",
       "type": "java.lang.Boolean",
-      "description": "Whether the embedded, containerized PostgreSQL database should be configured to start when the Application starts.",
+      "description": "Whether the containerized PostgreSQL database should be configured and started when the Application starts.",
       "defaultValue": true
     },
     {
       "name": "spring.local.postgresql.container.image",
       "type": "java.lang.String",
-      "description": "The name of a Docker Image containing a given version of PostgreSQL (example: postgres:15). If undefined, the Testcontainers default of 'postgres:9.6.12' is used.",
+      "description": "The Docker Image with the chosen version of PostgreSQL (example: postgres:15). If undefined, Testcontainers will use its default ('postgres:9.6.12').",
       "defaultValue": "postgres:9.6.12"
     },
+    {
+      "name": "spring.local.postgresql.container.name",
+      "type": "java.lang.String",
+      "description": "The name to use for the Docker Container when started. If undefined, a random name is used. Random names are preferred for Integration Tests, but when running the Application locally, a fixed name is useful, since it allows developers to find the running container with a consistent, predictable name.",
+      "defaultValue": "[random name assignment]"
+    },
     {
       "name": "spring.local.postgresql.container.port",
       "type": "java.lang.Integer",
-      "description": "The port on the Docker Container that should map to the port used by PostgreSQL inside the container. If undefined, a random port is used, which is preferred for integration tests, but when running the Application locally, defining a fixed port is useful. It gives developers the ability to configure a JDBC client with a consistent port. Otherwise, the port in the client's configuration must be updated if the Application had been restarted since the client was last used.",
+      "description": "The port on the Docker Container to map with the PostgreSQL port inside the container. If undefined, a random port is used. Random ports are preferred for Integration Tests, but when running the Application locally, a fixed port is useful, since it allows developers to configure any connecting, external tools or apps with a consistent, predictable port.",
       "defaultValue": "[random port assignment]"
     },
     {
       "name": "spring.local.postgresql.container.log.follow",
       "type": "java.lang.Boolean",
-      "description": "Whether the Application should log the log output produced by the Container.",
+      "description": "Whether the Application should log the output produced by the Container's log.",
       "defaultValue": false
     },
     {
       "name": "spring.local.postgresql.database.name",
       "type": "java.lang.String",
-      "description": "The name of the PostgreSQL database the Application will connect to. If undefined, defaults to the Testcontainers default of 'test'.",
+      "description": "The name to use for the PostgreSQL database. If undefined, Testcontainers will use its default (test).",
       "defaultValue": "test"
     },
     {
       "name": "spring.local.postgresql.database.username",
       "type": "java.lang.String",
-      "description": "The username of an admin or superuser in the PostgreSQL database. If no 'spring.local.postgresql.database.application.username' is defined, this will also be the username the Application uses to connect. If undefined, defaults to the Testcontainers default of 'test'.",
+      "description": "The username of an admin or superuser in the PostgreSQL database. If 'spring.local.postgresql.database.application.username' is not defined, this will also be the username the Application uses to connect. If undefined, Testcontainers will use its default ('test').",
       "defaultValue": "test"
     },
     {
       "name": "spring.local.postgresql.database.password",
       "type": "java.lang.String",
-      "description": "The password that goes with the username of the admin or superuser in the PostgreSQL database. If no 'spring.local.postgresql.database.application.username' is defined, this will also be the password for the username the Application uses to connect. If undefined, defaults to the Testcontainers default of 'test'.",
+      "description": "The password that goes with the username of the admin or superuser in the PostgreSQL database. If 'spring.local.postgresql.database.application.username' is not defined, this will also be the password for the username the Application uses to connect. If undefined, Testcontainers will use its default ('test').",
       "defaultValue": "test"
     },
     {
       "name": "spring.local.postgresql.database.application.username",
       "type": "java.lang.String",
-      "description": "In most cases the database user used by the Application should not have admin or superuser privileges. This property provides the ability to define the username of an \"application user\" for use during testing and local development. The Application will use this username to connect to the PostgreSQL database. If undefined, the value defined by 'spring.local.postgresql.database.username' will be used instead. NOTE: This application user is NOT automatically created. An init-script is required to create the user and grant their initial privileges.",
+      "description": "In most cases the database user used by the Application should not have admin or superuser privileges. This property provides the ability to define the username of an \"application user\" for use during testing and local development. The Application will use this username to connect to the PostgreSQL database. If undefined, the value defined by 'spring.local.postgresql.database.username' will be used instead. NOTE: The application user will NOT be created automatically. An init-script is required to create the user and grant their initial privileges.",
       "defaultValue": null
     },
     {
       "name": "spring.local.postgresql.database.application.password",
       "type": "java.lang.String",
-      "description": "In most cases the database user used by the Application should not have admin or superuser privileges. This property provides the ability to define the password for the username of an \"application user\" for use during testing and local development. The Application will use this password to connect to the PostgreSQL database. If undefined, the value defined by 'spring.local.postgresql.database.password' will be used instead. NOTE: This application user is NOT automatically created. An init-script is required to create the user and grant their initial privileges.",
+      "description": "In most cases the database user used by the Application should not have admin or superuser privileges. This property provides the ability to define the password for the username of an \"application user\" for use during testing and local development. The Application will use this password to connect to the PostgreSQL database. If undefined, the value defined by 'spring.local.postgresql.database.password' will be used instead. NOTE: The application user will NOT be created automatically. An init-script is required to create the user and grant their initial privileges.",
       "defaultValue": null
     },
     {
       "name": "spring.local.postgresql.database.init.script",
       "type": "java.lang.String",
-      "description": "The path to an SQL file (beginning with the 'resources' directory as the root) that should be executed when the Docker Container starts. Executes before migrations. Useful for administrative tasks, like creating additional users, for example. If undefined, no script is executed.",
+      "description": "The path to an SQL file (with the 'resources' directory as the root) that should be executed when the Docker Container starts. Executes before migrations. Useful for administrative tasks, like creating additional users, for example. If undefined, no script is executed.",
       "defaultValue": null
     }
   ]

src/main/resources/META-INF/additional-spring-configuration-metadata.json

@@ -1,12 +1,12 @@
 package io.github.quinnandrews.spring.local.postgresql;
 
 import com.zaxxer.hikari.HikariDataSource;
+import io.github.quinnandrews.spring.local.postgresql.application.Application;
+import io.github.quinnandrews.spring.local.postgresql.application.data.guitarpedals.repository.GuitarPedalRepository;
 import org.junit.jupiter.api.MethodOrderer;
 import org.junit.jupiter.api.Order;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestMethodOrder;
-import io.github.quinnandrews.spring.local.postgresql.application.Application;
-import io.github.quinnandrews.spring.local.postgresql.application.data.guitarpedals.repository.GuitarPedalRepository;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.data.domain.Sort;
@@ -43,6 +43,7 @@ void container_initialized() {
         assertTrue(postgreSQLContainer.isRunning());
         // then the container matches the 'appuser' configuration
         assertEquals("postgres:15", postgreSQLContainer.getDockerImageName());
+        assertEquals("/local_postgresql", postgreSQLContainer.getContainerName());
         assertEquals(15432, postgreSQLContainer.getMappedPort(PostgreSQLContainer.POSTGRESQL_PORT));
         assertEquals("pedals", postgreSQLContainer.getDatabaseName());
         assertEquals("fuzz", postgreSQLContainer.getUsername());

src/test/java/io/github/quinnandrews/spring/local/postgresql/AppUserPostgreSQLContainerConfigTest.java

@@ -40,6 +40,7 @@ void container_initialized() {
         assertTrue(postgreSQLContainer.isRunning());
         // then the container matches the 'custom' configuration
         assertEquals("postgres:15", postgreSQLContainer.getDockerImageName());
+        assertEquals("/local_postgresql", postgreSQLContainer.getContainerName());
         assertEquals(15432, postgreSQLContainer.getMappedPort(PostgreSQLContainer.POSTGRESQL_PORT));
         assertEquals("pedals", postgreSQLContainer.getDatabaseName());
         assertEquals("fuzz", postgreSQLContainer.getUsername());

src/test/java/io/github/quinnandrews/spring/local/postgresql/CustomPostgreSQLContainerConfigTest.java

@@ -1,13 +1,13 @@
 package io.github.quinnandrews.spring.local.postgresql;
 
 import com.zaxxer.hikari.HikariDataSource;
+import io.github.quinnandrews.spring.local.postgresql.application.Application;
+import io.github.quinnandrews.spring.local.postgresql.application.data.guitarpedals.repository.GuitarPedalRepository;
+import io.github.quinnandrews.spring.local.postgresql.config.PostgreSQLContainerConfig;
 import org.junit.jupiter.api.MethodOrderer;
 import org.junit.jupiter.api.Order;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestMethodOrder;
-import io.github.quinnandrews.spring.local.postgresql.application.Application;
-import io.github.quinnandrews.spring.local.postgresql.application.data.guitarpedals.repository.GuitarPedalRepository;
-import io.github.quinnandrews.spring.local.postgresql.config.PostgreSQLContainerConfig;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.data.domain.Sort;

src/test/java/io/github/quinnandrews/spring/local/postgresql/DefaultPostgreSQLContainerConfigTest.java

@@ -3,6 +3,7 @@
 #spring.local.postgresql.engaged=true
 
 spring.local.postgresql.container.image=postgres:15
+spring.local.postgresql.container.name=local_postgresql
 spring.local.postgresql.container.port=15432
 spring.local.postgresql.database.name=pedals
 spring.local.postgresql.database.username=fuzz

src/test/resources/application-appuser.properties

@@ -3,6 +3,7 @@
 #spring.local.postgresql.engaged=true
 
 spring.local.postgresql.container.image=postgres:15
+spring.local.postgresql.container.name=local_postgresql
 spring.local.postgresql.container.port=15432
 spring.local.postgresql.database.name=pedals
 spring.local.postgresql.database.username=fuzz