Data Types

Overview

Most of the data types are self explanatory and are adapted to the database in use. Refer to the database documentation for its data types specifics.

Every type below lives in org.dbunit.dataset.datatype. Which SQL type maps to which of these is normally decided automatically — see the DataType Factory property for how to override or extend the mapping, and Database-Specific Guides for vendor-specific types (Oracle SDO_GEOMETRY, PostgreSQL citext/interval/inet, MSSQL uniqueidentifier/datetimeoffset, and more) not covered here.

Type	Java Type	Notes
`BigIntegerDataType`	`java.math.BigInteger`	The default mapping for SQL `BIGINT`.
`BinaryStreamDataType`	`byte[]`	Reads via `ResultSet.getBinaryStream()` instead of `getBytes()`. Not registered by default — used by vendor factories for large binary values, e.g. Oracle’s `LONG RAW` and streamed `BLOB` (`OracleDataTypeFactory`/`Oracle10DataTypeFactory`).
`BitDataType`	`Boolean`	The default mapping for SQL `BIT`; extends `BooleanDataType`.
`BlobDataType`	`byte[]`	The default mapping for SQL `BLOB`. See Blob below for the `[TEXT\|BASE64\|FILE\|URL]` load syntax.
`BooleanDataType`	`Boolean`	The default mapping for SQL `BOOLEAN`.
`BytesDataType`	`byte[]`	Abstract base for the binary types above/below; not itself registered for any SQL type.
`ClobDataType`	`String`	The default mapping for SQL `CLOB`; extends `StringDataType`.
`DateDataType`	`java.sql.Date`	The default mapping for SQL `DATE`. See Relative Date, Time, and Timestamp below.
`DoubleDataType`	`Double`	The default mapping for SQL `DOUBLE` and SQL `FLOAT` — see the naming note under `FloatDataType`.
`FloatDataType`	`Float`	The default mapping for SQL `REAL`. Confusingly, SQL `FLOAT` maps to `DoubleDataType`/Java `Double` while SQL `REAL` maps here, to Java `Float` — this mirrors `java.sql.Types`, not a dbUnit choice.
`IntegerDataType`	`Integer`	The default mapping for SQL `TINYINT`, `SMALLINT`, and `INTEGER`.
`LongDataType`	`Long`	An alternate `BIGINT` mapping using Java `Long` instead of `BigInteger`. Not registered by default (`DataType.BIGINT` uses `BigIntegerDataType`); wire it in yourself via a custom `IDataTypeFactory` if you prefer `Long`.
`NumberDataType`	`java.math.BigDecimal`	The default mapping for SQL `NUMERIC`/`DECIMAL`.
`NumberTolerantDataType`	`java.math.BigDecimal`	A `NumberDataType` variant comparing within a tolerance instead of requiring an exact match. See NumberTolerantDataType below.
`StringDataType`	`String`	The default mapping for SQL `CHAR`, `VARCHAR`, `LONGVARCHAR`, `NCHAR`, `NVARCHAR`, and `LONGNVARCHAR`.
`StringIgnoreCaseDataType`	`String`	A `StringDataType` variant comparing case-insensitively. See StringIgnoreCaseDataType below.
`TimeDataType`	`java.sql.Time`	The default mapping for SQL `TIME`. See Relative Date, Time, and Timestamp below.
`TimestampDataType`	`java.sql.Timestamp`	The default mapping for SQL `TIMESTAMP`. See Relative Date, Time, and Timestamp below.
`UuidAwareBytesDataType`	`byte[]`	The default mapping for SQL `BINARY`/`VARBINARY`/`LONGVARBINARY` — a `BytesDataType` variant additionally recognizing a UUID literal. See UuidAwareBytesDataType below.

Blob

Blob JavaDoc

Blobs contain binary data. DbUnit, however, processes data with XML or CSV files containing textual data sets, not binary. To push binary data into a database blob from dbUnit data set files, use the following syntax in a data set field:

... field_name="[TEXT|BASE64|FILE|URL <optional argument>] optional text"

The following sections show how to use each of the forms available to load binary data into a blob.

TEXT

Insert text in a blob. By default the encoding used is UTF-8, but optionally any encoding can be provided.

Example with UTF-8 encoding:

<!DOCTYPE dataset SYSTEM "my-dataset.dtd">
<dataset>
    <TABLE_WITHBLOB COL0="[TEXT]This is my text, saved in UTF-8 (default) encoding.  Java: bon café!"
                    COL1="row 0 col 1"
                    COL2="row 0 col 2"/>
</dataset>

Example with ISO-8859-1 encoding:

<!DOCTYPE dataset SYSTEM "my-dataset.dtd">
<dataset>
    <TABLE_WITHBLOB COL0="[TEXT ISO-8859-1]This is my text, saved in ISO-8859-1 encoding.  Java: bon café!"
                    COL1="row 0 col 1"
                    COL2="row 0 col 2"/>
</dataset>

BASE64

Insert binary in a blob using Base64.

Example:

<!DOCTYPE dataset SYSTEM "my-dataset.dtd">
<dataset>
    <TABLE_WITHBLOB COL0="[BASE64]VGhpcyBpcyBteSB0ZXh0Lg=="
                    COL1="row 0 col 1"
                    COL2="row 0 col 2"/>
</dataset>

FILE

Insert the content of a binary file in a blob. The path may contains spaces.

Example:

<!DOCTYPE dataset SYSTEM "my-dataset.dtd">
<dataset>
    <TABLE_WITHBLOB COL0="[FILE]/path/to file to insert contents"
                    COL1="row 0 col 1"
                    COL2="row 0 col 2"/>
</dataset>

URL

Insert the content pointed by a URL in a blob.

Example:

<!DOCTYPE dataset SYSTEM "my-dataset.dtd">
<dataset>
    <TABLE_WITHBLOB COL0="[URL]http://url%20here"
                    COL1="row 0 col 1"
                    COL2="row 0 col 2"/>
</dataset>

NumberTolerantDataType

NumberTolerantDataType JavaDoc

A NumberDataType that accepts a value within a tolerated delta instead of requiring an exact match — comparable to JUnit’s assertEquals(double, double, double delta). The delta can be an absolute amount or a percentage of the expected value.

Register a tolerance per table/column by adding a ToleratedDeltaMap.ToleratedDelta to a DefaultDataTypeFactory (or a vendor factory extending it):

DefaultDataTypeFactory factory = new DefaultDataTypeFactory();
// allow ACCOUNT.BALANCE actual/expected values to differ by up to 0.01
factory.addToleratedDelta(new ToleratedDeltaMap.ToleratedDelta("ACCOUNT", "BALANCE", 0.01));
config.setProperty(DatabaseConfig.PROPERTY_DATATYPE_FACTORY, factory);

Pass true as a fourth constructor argument to treat the delta as a percentage of the expected value instead of an absolute amount. For comparisons that don’t need per-column DataType registration, see the ValueComparer-based tolerance implementations instead — ValueComparer Comparison.

StringIgnoreCaseDataType

StringIgnoreCaseDataType JavaDoc

A StringDataType that compares values with String.compareToIgnoreCase() instead of exact equality. Like NumberTolerantDataType, register it for specific columns through a custom IDataTypeFactory (or by returning it directly from createDataType() for the columns that need case-insensitive comparison) set via DatabaseConfig.PROPERTY_DATATYPE_FACTORY — see the DataType Factory property.

UuidAwareBytesDataType

UuidAwareBytesDataType JavaDoc

The default DataType for SQL BINARY/VARBINARY/LONGVARBINARY columns. It behaves like BytesDataType, plus recognizes a UUID literal so you don’t have to base64- or hex-encode UUIDs stored in binary columns by hand. For the literal to be detected, the field value must be in the form uuid’xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' (hex-encoded, big-endian):

<company id="uuid'791ae85a-d8d0-11e2-8c43-50e549c9b654'" name="ACME"/>

Relative date, time, and timestamp

It is possible to push date, time, and timestamp values relative to the current date/time by using the following syntax in a data set field (since 2.7.0):

... field_name="[now{diff...}{time}]"

diff consists of two parts 1) a number with a leading plus or minus sign and 2) a character represents temporal unit. See the list below for the supported units. There can be multiple `diff`s and they can be specified in any order.

time is a string that can be parsed by LocalTime#parse(). If specified, it is used instead of the current time.

Both diff and time are optional. Whitespaces are allowed before and after each diff.

y : years
M : months
d : days
h : hours
m : minutes
s : seconds

Here are some examples:

[now] : current date time
[now-1d] : the same time yesterday
[now+1y+1M-2h] : a year and a month from today, two hours earlier
[now+1d 10:00] : 10 o’clock tomorrow