Usage

The execution of this plugin’s mojo can be bound to a phase of build lifecycle. Use the <dependencies> in <plugin> to specify the artifact that has your JDBC driver.

<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <groupId>org.dbunit</groupId>
        <artifactId>dbunit-maven-plugin</artifactId>
        <version>1.3.1-SNAPSHOT</version>

        <!--jar file that has the jdbc driver -->
        <dependencies>
          <dependency>
            <groupId></groupId>
            <artifactId></artifactId>
            <version></version>
          </dependency>
        </dependencies>

        <!-- common configurations -->
        <configuration>
          <driver></driver>
          <url></url>
          <username></username>
          <password></password>
          [...]
        </configuration>

        <executions>
          <execution>
            <phase></phase>
            <goals>
              <goal></goal>
            </goals>
            <!-- specific configurations -->
            <configuration>
              [...]
            </configuration>
          </execution>
          <execution>
            <phase></phase>
            <goals>
              <goal></goal>
            </goals>
            <!-- specific configurations -->
            <configuration>
              [...]
            </configuration>
          </execution>
          [...]
        </executions>

        [...]
      </plugin>
      [...]
    </plugins>
    [...]
  </build>
  [...]
</project>

Configuring DatabaseConfig via `<dbconfig>`

The preferred way to configure DatabaseConfig properties is via the <dbconfig> element. Each child element’s name is a DatabaseConfig property short name and its content is the value — the same short names used by the dbUnit Ant task (see Ant task docs and the full DatabaseConfig properties reference). Note that explicit deprecated elements beneath <configuration> (outside <dbconfig>) are still accepted for backwards compatibility, but <dbconfig> values always take precedence.

[...]
<configuration>
  <dbconfig>
    <datatypeFactory>org.dbunit.ext.hsqldb.HsqldbDataTypeFactory</datatypeFactory>
    <tableType>TABLE,SYNONYM</tableType>
    <batchedStatements>true</batchedStatements>
    <caseSensitiveTableNames>true</caseSensitiveTableNames>
  </dbconfig>
</configuration>
[...]

Token Replacement in Datasets

The operation and compare goals both support a <replacementDataSetClass> parameter that accepts a fully-qualified class name of a ReplacementDataSet subclass (from org.dbunit:dbunit-core). The plugin instantiates the class via reflection, passing the loaded dataset to its single-IDataSet-argument constructor, and uses the resulting wrapped dataset for the operation or comparison. This lets you map placeholder tokens in your dataset files to actual Java objects (e.g. null, today’s date) without any coupling to the plugin.

Implement the subclass in your project (or test code):

public class NullReplacementDataSet extends ReplacementDataSet {
    public NullReplacementDataSet(final IDataSet wrapped) {
        super(wrapped);
        addReplacementObject("[NULL]", null);
    }
}

Then reference it in your POM configuration:

<configuration>
  <replacementDataSetClass>com.example.NullReplacementDataSet</replacementDataSetClass>
</configuration>

Or from the command line:

mvn dbunit:operation -Ddbunit.replacementDataSetClass=com.example.NullReplacementDataSet ...

Filtering Tables in the Export Goal

When no explicit <tables> or <queries> are configured, the export goal auto-discovers all tables via JDBC metadata. Use <excludes> and/or <excludeEmptyTables> to filter which tables are included. Both parameters are ignored when <tables> or <queries> are set.

Excluding tables by name pattern (`excludes`)

The <excludes> parameter accepts a list of Java regular expression patterns matched against the table name as returned by JDBC metadata. Table name case is database-specific (e.g. HSQLDB and many others return uppercase names). Use the (?i) prefix for case-insensitive matching.

<configuration>
  <excludes>
    <exclude>(?i)flyway_.*</exclude>
    <exclude>(?i)quartz_.*</exclude>
  </excludes>
</configuration>

Excluding empty tables (`excludeEmptyTables`)

Set <excludeEmptyTables>true</excludeEmptyTables> to omit tables that contain no rows. Useful for producing a clean snapshot that skips unpopulated reference or staging tables.

<configuration>
  <excludeEmptyTables>true</excludeEmptyTables>
</configuration>

Both parameters can be combined:

<configuration>
  <excludes>
    <exclude>(?i)flyway_.*</exclude>
  </excludes>
  <excludeEmptyTables>true</excludeEmptyTables>
</configuration>

Exporting a DTD Schema

The export-dtd goal exports a flat DTD schema from the connected database. Tables are automatically ordered by foreign key constraints so the DTD reflects the correct insertion order. The generated DTD can be used to validate flat XML dataset files and enable IDE auto-completion.

<configuration>
  <dest>src/test/resources/dataset.dtd</dest>
</configuration>

Or from the command line:

mvn dbunit:export-dtd \
  -Ddbunit.driver=org.hsqldb.jdbcDriver \
  -Ddbunit.url=jdbc:hsqldb:mem:mydb \
  -Ddbunit.username=sa \
  -Ddbunit.password= \
  -Ddbunit.dest=src/test/resources/dataset.dtd

Command-Line Usage

All plugin parameters can be set from the command line using the dbunit. property prefix, which avoids conflicts with Maven’s own built-in properties (url, username, password, etc.).

mvn dbunit:operation \
  -Ddbunit.driver=org.hsqldb.jdbcDriver \
  -Ddbunit.url=jdbc:hsqldb:mem:mydb \
  -Ddbunit.username=sa \
  -Ddbunit.password= \
  -Ddbunit.type=CLEAN_INSERT \
  -Ddbunit.src=src/test/data/insert.xml \
  -Ddbunit.format=xml

POM-based <configuration> uses the bare field names unchanged (e.g. <driver>, <url>).