Embedded Database Spring Test

https://github.com/zonkyio/embedded-database-spring-test
Admin
Embedded Database Spring Test is a library that simplifies writing Spring-powered integration tests...
Tokens:34,543
Snippets:512
Trust Score:7.4
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Implement custom DatabasePreparer

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

Example implementation of the DatabasePreparer interface to execute custom SQL setup scripts.

```java
public class CustomDatabasePreparer implements DatabasePreparer {
    
    @Override
    public long estimatedDuration() {
        return 100; // milliseconds
    }
    
    @Override
    public void prepare(DataSource dataSource) throws SQLException {
        try (Connection conn = dataSource.getConnection()) {
            try (Statement stmt = conn.createStatement()) {
                stmt.execute("CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100))");
                stmt.execute("INSERT INTO users VALUES (1, 'Test User')");
            }
        }
    }
}
```

--------------------------------

### Example PostgreSQL configuration

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Provides a concrete example of setting client, initdb, and server properties for a PostgreSQL embedded database.

```properties
zonky.test.database.postgres.client.properties.stringtype=unspecified
zonky.test.database.postgres.initdb.properties.lc-collate=cs_CZ.UTF-8
zonky.test.database.postgres.initdb.properties.lc-monetary=cs_CZ.UTF-8
zonky.test.database.postgres.initdb.properties.lc-numeric=cs_CZ.UTF-8
zonky.test.database.postgres.server.properties.shared_buffers=512MB
zonky.test.database.postgres.server.properties.max_connections=100
```

--------------------------------

### Properties Configuration Example

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/00-index.md

Standard format for configuration properties.

```properties
# Property examples
# Standard properties format
```

--------------------------------

### Maven Configuration Example

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/00-index.md

Standard format for Maven dependency or configuration snippets.

```xml
<!-- Maven examples when relevant -->
```

--------------------------------

### Repeatable Migration Script Example

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Example of a repeatable SQL script used to refresh database views.

```java
// db/migration/R__refresh_views.sql
-- Runs whenever content changes
CREATE OR REPLACE VIEW user_summary AS
  SELECT id, name, COUNT(*) as post_count
  FROM users u LEFT JOIN posts p ON u.id = p.user_id
  GROUP BY u.id, u.name;
```

--------------------------------

### Implement MariaDB Container Customization

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Example bean configuration for setting MariaDB root password.

```java
@Bean
public MariaDBContainerCustomizer mariadbContainerCustomizer() {
    return container -> {
        container.withStartupTimeout(Duration.ofSeconds(60L));
        container.withRootPassword("rootpassword");
    };
}
```

--------------------------------

### Java Code Example Template

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/00-index.md

Standard template for demonstrating Java usage patterns.

```java
// Java code examples
// Shows actual usage patterns
```

--------------------------------

### Implement MSSQL Server Container Customization

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Example bean configuration for MSSQL. Note that license acceptance is mandatory.

```java
@Bean
public MSSQLServerContainerCustomizer mssqlContainerCustomizer() {
    return container -> {
        container.acceptLicense();
        container.withStartupTimeout(Duration.ofSeconds(90L));
        container.withPassword("YourStrong@Passw0rd");
    };
}
```

--------------------------------

### Configure database settings in properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

A comprehensive example of configuring database type, initialization, prefetching, and PostgreSQL settings using a properties file.

```properties
# Core database configuration
zonky.test.database.type=postgres
zonky.test.database.provider=docker
zonky.test.database.refresh=after_each_test_method
zonky.test.database.replace=any

# Database initialization
zonky.test.database.init.script-locations=classpath:db/test-schema.sql,classpath:db/test-data.sql
zonky.test.database.init.continue-on-error=false
zonky.test.database.init.separator=;
zonky.test.database.init.encoding=UTF-8

# Prefetching performance
zonky.test.database.prefetching.thread-name-prefix=db-prefetch-
zonky.test.database.prefetching.concurrency=5
zonky.test.database.prefetching.pipeline-cache-size=10
zonky.test.database.prefetching.max-prepared-templates=20

# PostgreSQL specific
zonky.test.database.postgres.client.properties.stringtype=unspecified
zonky.test.database.postgres.server.properties.shared_buffers=512MB
zonky.test.database.postgres.server.properties.max_connections=100
zonky.test.database.postgres.docker.image=postgres:16-alpine
zonky.test.database.postgres.docker.tmpfs.enabled=true
```

--------------------------------

### Configure database settings in YAML

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

A comprehensive example of configuring database settings using YAML format, equivalent to the properties configuration.

```yaml
zonky:
  test:
    database:
      type: postgres
      provider: docker
      refresh: after_each_test_method
      replace: any
      
      init:
        script-locations:
          - classpath:db/test-schema.sql
          - classpath:db/test-data.sql
        continue-on-error: false
        separator: ";"
        encoding: UTF-8
      
      prefetching:
        thread-name-prefix: db-prefetch-
        concurrency: 5
        pipeline-cache-size: 10
        max-prepared-templates: 20
      
      postgres:
        client:
          properties:
            stringtype: unspecified
        server:
          properties:
            shared_buffers: 512MB
            max_connections: 100
        docker:
          image: postgres:16-alpine
          tmpfs:
            enabled: true
            options: "rw,noexec,nosuid"
```

--------------------------------

### Implement PostgreSQL Container Customization

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Example configuration bean to apply custom settings like startup timeout and credentials to a PostgreSQL container.

```java
@Configuration
public class EmbeddedPostgresConfiguration {
    
    @Bean
    public PostgreSQLContainerCustomizer postgresContainerCustomizer() {
        return container -> {
            container.withStartupTimeout(Duration.ofSeconds(60L));
            container.withPassword("testpassword");
            container.withUsername("testuser");
        };
    }
}
```

--------------------------------

### Implement MySQL Container Customization

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Example bean configuration for setting MySQL root password and database name.

```java
@Bean
public MySQLContainerCustomizer mysqlContainerCustomizer() {
    return container -> {
        container.withStartupTimeout(Duration.ofSeconds(60L));
        container.withRootPassword("rootpassword");
        container.withDatabaseName("testdb");
    };
}
```

--------------------------------

### Define Custom Dockerfile

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Example Dockerfile for extending the base PostgreSQL image with additional packages and initialization scripts.

```dockerfile
FROM postgres:16-alpine

# Install extensions
RUN apk add --no-cache postgresql-contrib

# Copy initialization scripts
COPY init-custom.sql /docker-entrypoint-initdb.d/
```

--------------------------------

### Test Data Setup with SQL Scripts

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Uses the @Sql annotation to load schema and test data from classpath resources before test execution.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase
@Sql({
    "classpath:db/schema.sql",
    "classpath:db/test-data.sql"
})
public class WithTestDataTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Autowired
    private UserRepository userRepository;
    
    @Test
    void testDataIsLoaded() {
        List<User> users = userRepository.findAll();
        assertFalse(users.isEmpty(), "Test data should be loaded");
        assertEquals("Test User", users.get(0).getName());
    }
}
```

--------------------------------

### Define Liquibase Changelog

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Example XML structure for defining database schema changes and initial data.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                   http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.10.xsd">
    
    <changeSet id="1" author="test">
        <createTable tableName="users">
            <column name="id" type="INT">
                <constraints primaryKey="true"/>
            </column>
            <column name="name" type="VARCHAR(100)"/>
        </createTable>
    </changeSet>
    
    <changeSet id="2" author="test" context="test">
        <insert tableName="users">
            <column name="id" value="1"/>
            <column name="name" value="Test User"/>
        </insert>
    </changeSet>
    
</databaseChangeLog>
```

--------------------------------

### EmbeddedDatabase Usage Example

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

Demonstrates how to interact with an injected DataSource within a test method.

```java
@Autowired
private DataSource dataSource;

@Test
void testWithEmbeddedDatabase() throws SQLException {
    try (Connection conn = dataSource.getConnection()) {
        try (Statement stmt = conn.createStatement()) {
            stmt.execute("CREATE TABLE test (id INT)");
        }
    }
}
```

--------------------------------

### Configure @FlywayTest Attributes

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Examples of customizing migration paths, clean operations, and multiple location configurations.

```java
// Custom migration location
@FlywayTest(locationsForMigrate = "db/test-migrations")
public class CustomMigrationPathTest { }

// Skip clean operation
@FlywayTest(invokeCleanDB = false)
public class NoCleanTest { }

// Multiple locations
@FlywayTest(locationsForMigrate = {"db/migrations", "db/test-fixtures"})
public class MultiPathTest { }
```

--------------------------------

### Register and Execute Custom Preparer

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Manually invoke the custom preparer within a test setup method to initialize the database state.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase
public class CustomPreparerTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Before
    void setupTestData() throws SQLException {
        DatabasePreparer preparer = new CustomDataPreparer(
            "CREATE TABLE users (id INT, name VARCHAR(100))",
            "INSERT INTO users VALUES (1, 'Test User')"
        );
        preparer.prepare(dataSource);
    }
}
```

--------------------------------

### Simple Embedded Database Test

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Demonstrates basic setup using @AutoConfigureEmbeddedDatabase to provide a DataSource for standard JDBC operations.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase
public class SimpleEmbeddedDatabaseTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Test
    void testDatabaseIsAvailable() throws SQLException {
        try (Connection conn = dataSource.getConnection()) {
            assertNotNull(conn);
            
            try (Statement stmt = conn.createStatement()) {
                stmt.execute("CREATE TABLE users (id INT, name VARCHAR(100))");
                stmt.execute("INSERT INTO users VALUES (1, 'Alice')");
                
                ResultSet rs = stmt.executeQuery("SELECT * FROM users WHERE id = 1");
                assertTrue(rs.next());
                assertEquals("Alice", rs.getString("name"));
            }
        }
    }
}
```

--------------------------------

### Configure Empty Embedded Database

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/10-quick-reference.md

Basic setup for an empty embedded database using the @AutoConfigureEmbeddedDatabase annotation.

```java
@AutoConfigureEmbeddedDatabase
public class Test {
    @Autowired
    private DataSource dataSource;
}
```

--------------------------------

### Configure Basic Embedded Database Test

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/02-annotation-autoconfigure.md

Standard setup for injecting an embedded DataSource into a test class.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase
public class SimpleEmbeddedDatabaseTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Test
    void testWithEmbeddedDatabase() {
        // Use embedded database
        try (Connection conn = dataSource.getConnection()) {
            // Perform database operations
        }
    }
}
```

--------------------------------

### Implement Flyway Migration Test

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Example of using @FlywayTest with Spring test context to verify database migrations.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase
@FlywayTest
@ContextConfiguration("classpath:db-config.xml")
public class FlywayMigrationTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Test
    @FlywayTest  // Can also annotate individual methods
    void testMigrationApplied() throws SQLException {
        try (Connection conn = dataSource.getConnection()) {
            // Database has migrations applied
            // Can verify schema exists
        }
    }
}
```

--------------------------------

### Implement TestExecutionStartedEvent Listener

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Use this listener to execute logic when test execution starts, before the database refresh occurs.

```java
@Component
public class TestStartupListener {
    
    @EventListener
    public void onTestStarted(TestExecutionStartedEvent event) {
        System.out.println("Test started: " + event.getTestMethod());
    }
}
```

--------------------------------

### Define PostgreSQLContainerCustomizer Interface

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

The functional interface used to customize PostgreSQL containers before they start.

```java
@FunctionalInterface
public interface PostgreSQLContainerCustomizer {
    void customize(PostgreSQLContainer container);
}
```

--------------------------------

### Configure Development Environment

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Optimizes for fast feedback by enabling tmpfs and high concurrency for prefetching.

```properties
# application-dev.properties
zonky.test.database.type=auto
zonky.test.database.provider=docker
zonky.test.database.refresh=never
zonky.test.database.prefetching.concurrency=8
zonky.test.database.postgres.docker.tmpfs.enabled=true
```

--------------------------------

### Configure PostgreSQL Initdb Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Defines additional options for the initdb command during database initialization.

```properties
zonky.test.database.postgres.initdb.properties.lc-collate=cs_CZ.UTF-8
zonky.test.database.postgres.initdb.properties.encoding=UTF8
```

--------------------------------

### Configure Multiple Databases

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/02-annotation-autoconfigure.md

Demonstrates how to configure and inject multiple distinct DataSource beans.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase(beanName = "db1")
@AutoConfigureEmbeddedDatabase(beanName = "db2", type = DatabaseType.POSTGRES)
@AutoConfigureEmbeddedDatabase(beanName = "db3", provider = DatabaseProvider.EMBEDDED)
public class MultipleDatabasesTest {
    
    @Autowired
    @Qualifier("db1")
    private DataSource dataSource1;
    
    @Autowired
    @Qualifier("db2")
    private DataSource dataSource2;
    
    @Autowired
    @Qualifier("db3")
    private DataSource dataSource3;
}
```

--------------------------------

### Implement a Custom DatabaseProvider

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Create a custom provider by implementing the DatabaseProvider interface and handling database initialization and preparation.

```java
public class CustomDatabaseProvider implements DatabaseProvider {
    
    @Override
    public EmbeddedDatabase createDatabase(DatabasePreparer preparer) 
            throws ProviderException {
        try {
            // Initialize database
            EmbeddedDatabase database = initializeDatabase();
            
            // Apply preparer
            preparer.prepare(database);
            
            return database;
        } catch (Exception e) {
            throw new ProviderException("Failed to create database", e);
        }
    }
    
    private EmbeddedDatabase initializeDatabase() {
        // Implementation specific to your provider
        return null;
    }
}
```

--------------------------------

### Configure Database Prefetching

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Adjust prefetching behavior to optimize database initialization speed using properties in the zonky.test.database.prefetching group.

```properties
zonky.test.database.prefetching.thread-name-prefix=prefetching- # Prefix to use for the names of database prefetching threads.
zonky.test.database.prefetching.concurrency=3                   # Maximum number of concurrently running database prefetching threads.
zonky.test.database.prefetching.pipeline-cache-size=5           # Maximum number of prepared databases per pipeline.
zonky.test.database.prefetching.max-prepared-templates=10       # Maximum number of prepared database templates.
```

--------------------------------

### Configure Database Prefetching

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Adjusts concurrency and template limits to improve database preparation speed.

```properties
zonky.test.database.prefetching.concurrency=8
zonky.test.database.prefetching.max-prepared-templates=20
```

--------------------------------

### Configure Docker provider settings

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Shows how to specify custom Docker images and tmpfs settings for various supported database engines.

```properties
zonky.test.database.postgres.docker.image=postgres:11-alpine        # Docker image containing PostgreSQL database.
zonky.test.database.postgres.docker.tmpfs.enabled=false             # Whether to mount postgres data directory as tmpfs.
zonky.test.database.postgres.docker.tmpfs.options=rw,noexec,nosuid  # Mount options used to configure the tmpfs filesystem.

zonky.test.database.mysql.docker.image=mysql:5.7                    # Docker image containing MySQL database.
zonky.test.database.mysql.docker.tmpfs.enabled=false                # Whether to mount database data directory as tmpfs.
zonky.test.database.mysql.docker.tmpfs.options=rw,noexec,nosuid     # Mount options used to configure the tmpfs filesystem.

zonky.test.database.mariadb.docker.image=mariadb:10.4               # Docker image containing MariaDB database.
zonky.test.database.mariadb.docker.tmpfs.enabled=false              # Whether to mount database data directory as tmpfs.
zonky.test.database.mariadb.docker.tmpfs.options=rw,noexec,nosuid   # Mount options used to configure the tmpfs filesystem.

zonky.test.database.mssql.docker.image=mcr.microsoft.com/mssql/server:2017-latest # Docker image containing MSSQL database.
```

--------------------------------

### MariaDBContainerCustomizer

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Interface for customizing MariaDB containers before startup.

```APIDOC
## MariaDBContainerCustomizer

### Description
Callback interface for customizing MariaDB containers before startup.

### Method
void customize(MariaDBContainer container)

### Usage Example
```java
@Bean
public MariaDBContainerCustomizer mariadbContainerCustomizer() {
    return container -> {
        container.withRootPassword("rootpassword");
    };
}
```
```

--------------------------------

### Build documentation with Pandoc

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/MANIFEST.md

Converts all markdown files in the current directory into a single HTML file using Pandoc.

```bash
pandoc *.md -o documentation.html
```

--------------------------------

### Enable MySQL tmpfs

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Configures whether to mount the MySQL data directory as tmpfs.

```properties
zonky.test.database.mysql.docker.tmpfs.enabled=true
```

--------------------------------

### Configure Database via Environment Variables

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Use these environment variables to override default database settings using relaxed binding.

```bash
export ZONKY_TEST_DATABASE_TYPE=postgres
export ZONKY_TEST_DATABASE_PROVIDER=docker
export ZONKY_TEST_DATABASE_REFRESH=AFTER_EACH_TEST_METHOD
```

--------------------------------

### Configure PostgreSQL Docker Tmpfs Options

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Sets the mount options for the tmpfs filesystem.

```properties
zonky.test.database.postgres.docker.tmpfs.options=rw,noexec,nosuid,size=1G
```

--------------------------------

### Configure PostgreSQL Server Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Sets additional options for PostgreSQL server configuration.

```properties
zonky.test.database.postgres.server.properties.shared_buffers=512MB
zonky.test.database.postgres.server.properties.max_connections=100
zonky.test.database.postgres.server.properties.work_mem=64MB
```

--------------------------------

### Configure MariaDB Docker Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Sets the Docker image and enables tmpfs for the MariaDB provider.

```properties
zonky.test.database.mariadb.docker.image=mariadb:11.3
zonky.test.database.mariadb.docker.tmpfs.enabled=true
```

--------------------------------

### Configure MSSQL Docker Image

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Sets the Docker image for the MSSQL provider via properties.

```properties
zonky.test.database.mssql.docker.image=mcr.microsoft.com/mssql/server:2022-latest
```

--------------------------------

### Configure Minimal Environment

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Optimizes resource usage for constrained environments by using the embedded provider and smaller cache sizes.

```properties
# application-minimal.properties
zonky.test.database.type=auto
zonky.test.database.provider=embedded
zonky.test.database.prefetching.max-prepared-templates=5
zonky.test.database.prefetching.pipeline-cache-size=3
```

--------------------------------

### Enable tmpfs for Performance

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Configure in-memory filesystem settings to improve I/O performance at the cost of system memory.

```properties
zonky.test.database.postgres.docker.tmpfs.enabled=true
zonky.test.database.postgres.docker.tmpfs.options=rw,noexec,nosuid,size=2G
```

--------------------------------

### Select Database Provider

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Use the default provider for flexibility, or specify embedded/docker providers based on environment requirements.

```java
// ❌ Docker in all environments
@AutoConfigureEmbeddedDatabase(provider = DatabaseProvider.DOCKER)
public class AllEnvironmentsTest { }

// ✓ AUTO provider for flexibility
@AutoConfigureEmbeddedDatabase(provider = DatabaseProvider.DEFAULT)
public class FlexibleTest { }

// For specific needs:
@AutoConfigureEmbeddedDatabase(provider = DatabaseProvider.EMBEDDED)  // No Docker
public class NoDockerTest { }
```

--------------------------------

### Observe Database State Transitions

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Demonstrates how database state shifts from FRESH to AHEAD and DIRTY during test method execution.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase(refresh = RefreshMode.AFTER_EACH_TEST_METHOD)
public class ContextStateTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Test
    void testStateTransitions() throws SQLException {
        // State: FRESH (database is clean)
        
        try (Statement stmt = dataSource.getConnection().createStatement()) {
            stmt.execute("INSERT INTO users VALUES (1, 'Test')");
        }
        // State: AHEAD (test has made changes)
        
        // After @Test completes:
        // State: DIRTY (changes pending reset)
        
        // Before next @Test:
        // State transitions to FRESH (refresh applied)
    }
    
    @Test
    void testStateAfterRefresh() throws SQLException {
        // State: FRESH (database reset from previous test)
        // Verify previous test's changes are gone
    }
}
```

--------------------------------

### Testing Against Different Databases

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Demonstrates using DatabaseType.AUTO for generic tests and DatabaseType.POSTGRES for tests requiring specific database features.

```java
public class DatabaseAgnosticTest {
    
    @ExtendWith(SpringExtension.class)
    @AutoConfigureEmbeddedDatabase(type = DatabaseType.AUTO)
    public static class GenericTest {
        
        @Autowired
        private DataSource dataSource;
        
        @Test
        void testGenericDatabaseFeatures() throws SQLException {
            // Works with any database type
            try (Connection conn = dataSource.getConnection()) {
                String dbName = conn.getMetaData().getDatabaseProductName();
                assertNotNull(dbName);
            }
        }
    }
    
    @ExtendWith(SpringExtension.class)
    @AutoConfigureEmbeddedDatabase(type = DatabaseType.POSTGRES)
    public static class PostgresSpecificTest {
        
        @Autowired
        private DataSource dataSource;
        
        @Test
        void testPostgresSpecificFeatures() throws SQLException {
            // PostgreSQL-specific features
            try (Statement stmt = dataSource.getConnection().createStatement()) {
                stmt.execute("CREATE EXTENSION IF NOT EXISTS uuid-ossp");
            }
        }
    }
}
```

--------------------------------

### Configure MySQL Docker Image

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Sets the Docker image and tmpfs settings for the MySQL provider.

```properties
zonky.test.database.mysql.docker.image=mysql:8.2
zonky.test.database.mysql.docker.tmpfs.enabled=true
```

--------------------------------

### Configure CI/CD Environment

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Prioritizes consistency and reproducibility with frequent refreshes and reduced memory usage.

```properties
# application-ci.properties
zonky.test.database.type=postgres
zonky.test.database.provider=docker
zonky.test.database.refresh=after_each_test_method
zonky.test.database.prefetching.max-prepared-templates=10
# Reduce prefetching to save CI container memory
zonky.test.database.prefetching.concurrency=2
```

--------------------------------

### MySQLContainerCustomizer

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Interface for customizing MySQL containers before startup.

```APIDOC
## MySQLContainerCustomizer

### Description
Callback interface for customizing MySQL containers before startup.

### Method
void customize(MySQLContainer container)

### Usage Example
```java
@Bean
public MySQLContainerCustomizer mysqlContainerCustomizer() {
    return container -> {
        container.withRootPassword("rootpassword");
        container.withDatabaseName("testdb");
    };
}
```
```

--------------------------------

### Configure PostgreSQL properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Defines the structure for passing additional options to the PostgreSQL initdb command and server configuration.

```properties
zonky.test.database.postgres.initdb.properties.*= # Additional PostgreSQL options to pass to initdb command during the database initialization.
zonky.test.database.postgres.server.properties.*= # Additional PostgreSQL options used to configure the embedded database server.
```

--------------------------------

### Configure DockerPostgresDatabaseProvider

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Properties for configuring the Docker image and tmpfs settings.

```properties
zonky.test.database.postgres.docker.image=postgres:16-alpine
zonky.test.database.postgres.docker.tmpfs.enabled=true
zonky.test.database.postgres.docker.tmpfs.options=rw,noexec,nosuid
```

--------------------------------

### Customize DockerPostgresDatabaseProvider

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Customizes the Docker container startup timeout.

```java
@Bean
public PostgreSQLContainerCustomizer postgresCustomizer() {
    return container -> container.withStartupTimeout(Duration.ofSeconds(60L));
}
```

--------------------------------

### Configure Database Prefetching Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Adjust these properties in your configuration to balance test parallelism against system resource consumption.

```properties
# Balance between parallelism and resources
zonky.test.database.prefetching.concurrency=8
# Number of prepared databases per pipeline (queue)
zonky.test.database.prefetching.pipeline-cache-size=15
# Total templates to maintain in cache
zonky.test.database.prefetching.max-prepared-templates=20
```

--------------------------------

### DatabasePreparer Interface

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

The DatabasePreparer interface provides methods to estimate the duration of preparation tasks and execute them against a provided DataSource.

```APIDOC
## DatabasePreparer Interface

### Description
Represents a single unit of database initialization work, such as running migrations or executing SQL scripts.

### Method Signature
`void prepare(DataSource dataSource) throws SQLException`

### Parameters
- **dataSource** (DataSource) - Required - The database connection source to perform initialization work on.

### Method Signature
`long estimatedDuration()`

### Returns
- **long** - The estimated preparation time in milliseconds.
```

--------------------------------

### Define DatabasePreparer interface

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

The core interface for implementing custom database initialization logic.

```java
public interface DatabasePreparer {
    long estimatedDuration();
    void prepare(DataSource dataSource) throws SQLException;
}
```

--------------------------------

### Use default Docker provider

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Demonstrates the basic usage of the @AutoConfigureEmbeddedDatabase annotation for the default Docker provider.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase
public class DefaultProviderIntegrationTest {
    // class body...
}
```

--------------------------------

### Configure Database with Migrations

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/10-quick-reference.md

Integrates Flyway migrations by specifying the location of migration scripts.

```java
@AutoConfigureEmbeddedDatabase
@FlywayTest(locationsForMigrate = "db/migration")
public class Test { }
```

--------------------------------

### Configure MySQL Docker image

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Specifies the Docker image to use for the MySQL instance.

```properties
zonky.test.database.mysql.docker.image=mysql:8.2
```

--------------------------------

### Configure Migration Caching

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Properties to tune the performance of template database prefetching and cache size.

```properties
zonky.test.database.prefetching.max-prepared-templates=20
zonky.test.database.prefetching.pipeline-cache-size=10
```

--------------------------------

### Configure Spring Boot SQL initialization

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Define SQL initialization behavior using standard Spring Boot properties in application.properties or equivalent.

```properties
spring.sql.init.mode=always
spring.sql.init.platform=postgresql
spring.sql.init.data-locations=classpath:data.sql
spring.sql.init.schema-locations=classpath:schema.sql
spring.sql.init.encoding=UTF-8
```

--------------------------------

### Configure DatabaseProviderFactory via Spring Bean

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

Demonstrates using the fluent API to customize templating and prefetching settings within a Spring configuration class.

```java
@Configuration
public class EmbeddedDatabaseConfiguration {
    
    @Bean
    public DatabaseProviderFactory customizedFactory(DatabaseProviderFactory factory) {
        return factory
            .customizeTemplating(config -> config.withMaxPreparedTemplates(20))
            .customizePrefetching(config -> config.withConcurrency(5));
    }
}
```

--------------------------------

### Configure error handling during initialization

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Sets whether the database initialization process should continue if a script error occurs.

```properties
zonky.test.database.init.continue-on-error=false
```

--------------------------------

### Initialize database with Flyway

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Use @FlywayTest to automatically clean and migrate the embedded database using Flyway.

```java
@ExtendWith(SpringExtension.class)
@FlywayTest // performs clean and migrate operations, with the same effect as the refresh mode
@AutoConfigureEmbeddedDatabase
@ContextConfiguration("path/to/application-config.xml")
public class FlywayMigrationIntegrationTest {
    // class body...
}
```

--------------------------------

### Configure PostgreSQL Client Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Sets additional PostgreSQL client properties for DataSource configuration.

```properties
zonky.test.database.postgres.client.properties.stringtype=unspecified
zonky.test.database.postgres.client.properties.loggerLevel=OFF
```

--------------------------------

### Define Core Configuration Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/10-quick-reference.md

Set these properties in your application.properties or test configuration files to customize database type, initialization scripts, and performance settings.

```properties
# Database type and provider
zonky.test.database.type=postgres
zonky.test.database.provider=docker
zonky.test.database.refresh=after_each_test_method
zonky.test.database.replace=any

# Initialization
zonky.test.database.init.script-locations=classpath:schema.sql
zonky.test.database.init.separator=;
zonky.test.database.init.continue-on-error=false

# Performance
zonky.test.database.prefetching.concurrency=8
zonky.test.database.prefetching.max-prepared-templates=20
zonky.test.database.prefetching.pipeline-cache-size=15

# PostgreSQL
zonky.test.database.postgres.docker.image=postgres:16-alpine
zonky.test.database.postgres.docker.tmpfs.enabled=true
zonky.test.database.postgres.server.properties.shared_buffers=512MB
zonky.test.database.postgres.server.properties.max_connections=100
```

--------------------------------

### Mount Docker Volumes

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Use a PostgreSQLContainerCustomizer bean to bind host directories to the container filesystem.

```java
@Bean
public PostgreSQLContainerCustomizer dockerVolumeCustomizer() {
    return container -> {
        container.withFileSystemBind(
            "/host/path/to/scripts",
            "/var/lib/postgresql/scripts",
            BindMode.READ_ONLY
        );
    };
}
```

--------------------------------

### Configure Docker PostgreSQL image

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Specify the Docker image name for the Docker provider using a property configuration.

```properties
zonky.test.database.postgres.docker.image=postgres:16-alpine
```

--------------------------------

### Configure MySQL client properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Sets additional client properties for the MySQL connection.

```properties
zonky.test.database.mysql.client.properties.characterEncoding=UTF-8
```

--------------------------------

### Configure MariaDB Docker image

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Specifies the Docker image to use for the MariaDB instance.

```properties
zonky.test.database.mariadb.docker.image=mariadb:11.3
```

--------------------------------

### Verify Docker Environment

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Use these commands to check if the Docker daemon is accessible and permissions are correct.

```bash
# Verify Docker is running
docker ps

# Check permissions
ls -la /var/run/docker.sock
```

--------------------------------

### Configure maximum prepared templates

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Sets the maximum number of prepared database templates to maintain in the system.

```properties
zonky.test.database.prefetching.max-prepared-templates=20
```

--------------------------------

### Configure Container Customizers

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/10-quick-reference.md

Bean definitions for customizing PostgreSQL, MSSQL, and MySQL containers with specific timeouts and credentials.

```java
@Bean
public PostgreSQLContainerCustomizer postgresCustomizer() {
    return container -> {
        container.withStartupTimeout(Duration.ofSeconds(60L));
        container.withPassword("password");
    };
}

@Bean
public MSSQLServerContainerCustomizer mssqlCustomizer() {
    return container -> {
        container.acceptLicense();
        container.withStartupTimeout(Duration.ofSeconds(90L));
    };
}

@Bean
public MySQLContainerCustomizer mysqlCustomizer() {
    return container -> {
        container.withStartupTimeout(Duration.ofSeconds(60L));
        container.withRootPassword("password");
    };
}
```

--------------------------------

### Configure database provider

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Specifies the underlying provider used to create the database instance.

```properties
zonky.test.database.provider=embedded
```

--------------------------------

### Accept MSSQL License

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Methods to accept the Microsoft SQL Server license.

```java
container.acceptLicense();
```

```bash
export MSSQL_SA_PASSWORD=YourStrong@Passw0rd
```

--------------------------------

### Set Yandex Provider Configuration Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Define the PostgreSQL binary version using properties in the zonky.test.database.postgres.yandex-provider group.

```properties
zonky.test.database.postgres.yandex-provider.postgres-version=11.10-1 # Version of EnterpriseDB PostgreSQL binaries (https://www.enterprisedb.com/download-postgresql-binaries).
```

--------------------------------

### DatabaseTemplate Interface

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

Represents a template database used for quick initialization of new databases via binary copying.

```APIDOC
## DatabaseTemplate Interface

### Description
Represents a template database that can be used to quickly initialize new databases via binary copying.

### Methods
- **getTemplateName()** (String) - Returns the unique identifier of the template database.
- **close()** (void) - Closes the template and removes associated resources.
```

--------------------------------

### Configure Multiple Databases

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/10-quick-reference.md

Supports multiple database instances by assigning unique bean names and using @Qualifier for injection.

```java
@AutoConfigureEmbeddedDatabase(beanName = "db1")
@AutoConfigureEmbeddedDatabase(beanName = "db2")
public class Test {
    @Autowired
    @Qualifier("db1")
    private DataSource dataSource1;
}
```

--------------------------------

### Configure SQL script locations

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Defines the locations of SQL scripts to be applied during database initialization.

```properties
zonky.test.database.init.script-locations=classpath:db/test-schema.sql,classpath:db/test-data.sql
```

--------------------------------

### Configure Comprehensive Test with Migration and Refresh

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Integrates Spring test extensions with Flyway migrations and SQL fixtures to ensure a fresh database state for each test method.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase(
    refresh = RefreshMode.AFTER_EACH_TEST_METHOD
)
@FlywayTest(locationsForMigrate = "db/migration")
@Sql("classpath:db/test-fixtures.sql")
public class ComprehensiveTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Test
    void testOne() {
        // 1. Fresh database (template or new)
        // 2. Flyway migrations applied
        // 3. @Sql fixtures applied
        // 4. Test executes
        // 5. Database refreshed after test
    }
    
    @Test
    void testTwo() {
        // Sequence repeats with fresh database
    }
}
```

--------------------------------

### Switch to Embedded Provider

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Use this annotation to bypass Docker and use the embedded database provider directly.

```java
@AutoConfigureEmbeddedDatabase(provider = DatabaseProvider.EMBEDDED)
```

--------------------------------

### DatabaseContext State Transitions

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

Visual representation of the lifecycle states for the database context.

```text
INITIALIZING → FRESH → AHEAD → DIRTY → (reset) → FRESH
```

--------------------------------

### Configure PostgreSQL version via BOM

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Use the embedded-postgres-binaries-bom dependency to manage PostgreSQL versions for the Zonky provider.

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.zonky.test.postgres</groupId>
            <artifactId>embedded-postgres-binaries-bom</artifactId>
            <version>18.3.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

--------------------------------

### Configure MSSQL client properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Sets additional client properties for the MSSQL DataSource.

```properties
zonky.test.database.mssql.client.properties.trustServerCertificate=true
```

--------------------------------

### Customize Zonky Provider Configuration

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Define a Consumer bean to customize the EmbeddedPostgres.Builder before database startup.

```java
import io.zonky.test.db.postgres.embedded.EmbeddedPostgres;

@Configuration
public class EmbeddedPostgresConfiguration {
    
    @Bean
    public Consumer<EmbeddedPostgres.Builder> embeddedPostgresCustomizer() {
        return builder -> builder.setPGStartupWait(Duration.ofSeconds(60L));
    }
}
```

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase(provider = ZONKY)
@ContextConfiguration(classes = EmbeddedPostgresConfiguration.class)
public class EmbeddedPostgresIntegrationTest {
    // class body...
}
```

--------------------------------

### Configure Database Customizers and Listeners

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Define beans for PostgreSQL or MSSQL container customization, factory prefetching, and event handling within a configuration class.

```java
@Configuration
public class EmbeddedDatabaseTestConfiguration {
    
    // PostgreSQL Docker customization
    @Bean
    public PostgreSQLContainerCustomizer postgresCustomizer() {
        return container -> {
            container.withStartupTimeout(Duration.ofSeconds(60L));
            container.withPassword("postgres");
            container.withInitScript("init-postgres.sql");
        };
    }
    
    // MSSQL Docker customization
    @Bean
    public MSSQLServerContainerCustomizer mssqlCustomizer() {
        return container -> {
            container.acceptLicense();
            container.withStartupTimeout(Duration.ofSeconds(90L));
            container.withPassword("YourStrong@Passw0rd");
        };
    }
    
    // Factory customization for prefetching
    @Bean
    public DatabaseProviderFactory customDatabaseProviderFactory(
            DatabaseProviderFactory factory) {
        return factory
            .customizePrefetching(config -> config
                .withConcurrency(8)
                .withMaxPreparedTemplates(20))
            .customizeTemplating(config -> config
                .withMaxPreparedTemplates(20));
    }
    
    // Event listeners
    @Bean
    public Object testEventListener() {
        return new Object() {
            @EventListener
            public void onTestStarted(TestExecutionStartedEvent event) {
                System.out.println("Starting: " + event.getTestMethod());
            }
            
            @EventListener
            public void onTestFinished(TestExecutionFinishedEvent event) {
                System.out.println("Finished: " + event.getTestMethod());
            }
        };
    }
}
```

--------------------------------

### Performance Optimization

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Optimizes test performance using prefetching, tmpfs for Docker, and PostgreSQL server properties via @TestPropertySource.

```java
@ExtendWith(SpringExtension.class)
@AutoConfigureEmbeddedDatabase(
    type = DatabaseType.POSTGRES,
    provider = DatabaseProvider.DOCKER,
    refresh = RefreshMode.AFTER_EACH_TEST_METHOD
)
@FlywayTest(locationsForMigrate = "db/migration")
@TestPropertySource(properties = {
    // Prefetching configuration for performance
    "zonky.test.database.prefetching.concurrency=8",
    "zonky.test.database.prefetching.max-prepared-templates=20",
    "zonky.test.database.prefetching.pipeline-cache-size=15",
    
    // Docker tmpfs for faster I/O
    "zonky.test.database.postgres.docker.tmpfs.enabled=true",
    "zonky.test.database.postgres.docker.tmpfs.options=rw,noexec,nosuid,size=2G",
    
    // PostgreSQL server optimization
    "zonky.test.database.postgres.server.properties.shared_buffers=512MB",
    "zonky.test.database.postgres.server.properties.effective_cache_size=1GB",
    "zonky.test.database.postgres.server.properties.work_mem=64MB"
})
public class OptimizedPerformanceTest {
    
    @Autowired
    private DataSource dataSource;
    
    @Test
    void testOne() {
        // Test executes with optimized database setup
        // First test: ~2 seconds (migrations applied)
    }
    
    @Test
    void testTwo() {
        // Subsequent tests: ~100ms (from template cache)
    }
}
```

--------------------------------

### Flyway Migration Script Naming Conventions

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Standard naming patterns for versioned, repeatable, and undo migration scripts.

```text
V1__initial_schema.sql       # Version 1
V2__add_users_table.sql      # Version 2
V3__add_user_indices.sql     # Version 3
R__report_views.sql          # Repeatable (runs on hash change)
U1__undo_last_change.sql     # Undo script (requires Flyway Pro)
```

--------------------------------

### Add HSQLDB Maven Dependency

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Include this dependency to enable HSQLDB support. This provider supports prefetching but not template databases.

```xml
<dependency>
    <groupId>org.hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <version>2.7.4</version>
</dependency>
```

--------------------------------

### Performance Tuning Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/10-quick-reference.md

Configuration properties for optimizing database prefetching and memory usage across development, CI/CD, and memory-constrained environments.

```properties
# Development (fast feedback)
zonky.test.database.prefetching.concurrency=8
zonky.test.database.postgres.docker.tmpfs.enabled=true

# CI/CD (resource-constrained)
zonky.test.database.prefetching.concurrency=2
zonky.test.database.prefetching.max-prepared-templates=10

# Memory-constrained
zonky.test.database.prefetching.max-prepared-templates=5
zonky.test.database.prefetching.pipeline-cache-size=3
```

--------------------------------

### Optimize Database Caching with Templates

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Leverage template database caching by performing migrations in the template and using refresh modes for test isolation.

```java
// ❌ Complex migrations per test (slow)
@FlywayTest(invokeCleanDB = true)  // Creates new template each time
public class SlowTest { }

// ✓ Migrations in template, use refresh mode for isolation (fast)
@AutoConfigureEmbeddedDatabase(refresh = RefreshMode.AFTER_EACH_TEST_METHOD)
@FlywayTest
public class FastTest { }
```

--------------------------------

### Customize Provider Pipeline

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Wrap database providers with decorators to add optimization, prefetching, or templating capabilities.

```java
@Configuration
public class CustomProviderPipeline {
    
    @Bean
    public DatabaseProviderFactory customFactory(DatabaseProviderFactory factory) {
        return factory
            // Optimize database creation
            .customizeProvider((builder, provider) -> 
                builder.optimizingProvider(provider))
            
            // Enable prefetching
            .customizeProvider((builder, provider) -> 
                builder.prefetchingProvider(provider))
            
            // Enable templating (if provider supports it)
            .customizeProvider((builder, provider) -> {
                if (provider instanceof TemplatableDatabaseProvider) {
                    return builder.templatingProvider(provider);
                }
                return provider;
            });
    }
}
```

--------------------------------

### Configure PostgreSQL Locale via Properties

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Set collation and encoding properties in your configuration file to ensure consistent locale behavior.

```properties
# UTF-8 collation for Czech
zonky.test.database.postgres.initdb.properties.lc-collate=cs_CZ.UTF-8
zonky.test.database.postgres.initdb.properties.lc-monetary=cs_CZ.UTF-8
zonky.test.database.postgres.initdb.properties.lc-numeric=cs_CZ.UTF-8

# Encoding
zonky.test.database.postgres.initdb.properties.encoding=UTF8
```

--------------------------------

### Configure PostgreSQL Docker Image

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/09-special-topics.md

Overrides the default PostgreSQL image to avoid potential Alpine Linux libc compatibility issues.

```properties
zonky.test.database.postgres.docker.image=postgres:16
```

--------------------------------

### Add Microsoft SQL Server Maven Dependency

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/README.md

Include this dependency to enable Microsoft SQL Server support. Note that an EULA must be accepted for the docker image.

```xml
<dependency>
    <groupId>com.microsoft.sqlserver</groupId>
    <artifactId>mssql-jdbc</artifactId>
    <version>13.2.1.jre11</version>
</dependency>
```

--------------------------------

### Configure prefetching pipeline cache size

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/04-configuration-properties.md

Defines the maximum number of prepared databases to keep in the cache per pipeline.

```properties
zonky.test.database.prefetching.pipeline-cache-size=10
```

--------------------------------

### Initialize DefaultDatabaseContext

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/03-core-interfaces.md

Constructor for the default implementation of DatabaseContext managing the database lifecycle.

```java
public DefaultDatabaseContext(ObjectFactory<DatabaseProvider> providerFactory)
```

--------------------------------

### Optimize Test Performance

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Adjust prefetching and template settings in properties to improve execution speed.

```properties
zonky.test.database.prefetching.concurrency=8
zonky.test.database.prefetching.max-prepared-templates=20
zonky.test.database.postgres.docker.tmpfs.enabled=true
```

--------------------------------

### Enable Docker tmpfs for Postgres

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/07-migration-tools.md

Enables in-memory storage for Docker-based Postgres instances to reduce I/O latency.

```properties
zonky.test.database.postgres.docker.tmpfs.enabled=true
```

--------------------------------

### Customize MariaDB Container

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/06-database-providers.md

Provides a customizer bean to configure startup timeout and root password for the MariaDB container.

```java
@Bean
public MariaDBContainerCustomizer mariadbCustomizer() {
    return container -> {
        container.withStartupTimeout(Duration.ofSeconds(60L));
        container.withRootPassword("rootpassword");
    };
}
```

--------------------------------

### PostgreSQLContainerCustomizer

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Interface for customizing PostgreSQL containers before startup. Users implement this interface as a Spring Bean to modify container settings.

```APIDOC
## PostgreSQLContainerCustomizer

### Description
Callback interface for customizing PostgreSQL containers before startup. Implement this interface and register it as a Spring Bean to apply custom configurations.

### Method
void customize(PostgreSQLContainer container)

### Parameters
- **container** (PostgreSQLContainer) - The container instance to be customized.

### Usage Example
```java
@Bean
public PostgreSQLContainerCustomizer postgresContainerCustomizer() {
    return container -> {
        container.withStartupTimeout(Duration.ofSeconds(60L));
        container.withPassword("testpassword");
    };
}
```
```

--------------------------------

### Configure EmbeddedPostgres via Consumer

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/05-customizers-and-extensions.md

Define a bean of type Consumer<EmbeddedPostgres.Builder> to customize the embedded database startup parameters.

```java
@Configuration
public class EmbeddedPostgresConfiguration {
    
    @Bean
    public Consumer<EmbeddedPostgres.Builder> embeddedPostgresCustomizer() {
        return builder -> {
            builder.setPGStartupWait(Duration.ofSeconds(60L));
            builder.setCleanInstall(false);  // Reuse existing installation
            builder.setLocaleConfig(new LocaleConfig());
        };
    }
}
```

--------------------------------

### Select Appropriate Database Type

Source: https://github.com/zonkyio/embedded-database-spring-test/blob/master/_autodocs/08-usage-examples.md

Use DatabaseType.AUTO for general unit tests to avoid unnecessary resource consumption, reserving specific types for integration tests.

```java
// ❌ Always use PostgreSQL for all tests (resource waste)
@AutoConfigureEmbeddedDatabase(type = DatabaseType.POSTGRES)
public class WastefulTest { }

// ✓ Use AUTO for unit tests, specific type when needed
@AutoConfigureEmbeddedDatabase(type = DatabaseType.AUTO)
public class EfficientTest { }
```
Tokens:
Raw