Available in versions: Dev (3.18) | Latest (3.17) | 3.16 | 3.15 | 3.14 | 3.13 | 3.12 | 3.11 | 3.10 | 3.9 | 3.8

This documentation is for the unreleased development version of jOOQ. Click on the above version links to get this documentation for a supported version of jOOQ.

Custom data type conversion

Applies to ✅ Open Source Edition   ✅ Express Edition   ✅ Professional Edition   ✅ Enterprise Edition

Apart from a few extra features (user-defined types), jOOQ only supports basic types as supported by the JDBC API. In your application, you may choose to transform these data types into your own ones, without writing too much boiler-plate code. This can be done using jOOQ's org.jooq.Converter types. A converter essentially allows for two-way conversion between two Java data types <T> and <U>. By convention, the <T> type corresponds to the type in your database whereas the <U> type corresponds to your own user type. The Converter API is given here:

public interface Converter<T, U> extends Serializable {

     * Convert a database object to a user object
    U from(T databaseObject);

     * Convert a user object to a database object
    T to(U userObject);

     * The database type
    Class<T> fromType();

     * The user type
    Class<U> toType();

Such a converter can be used in many parts of the jOOQ API. Some examples have been illustrated in the manual's section about fetching.

A Converter for GregorianCalendar

Here is a some more elaborate example involving a Converter for java.util.GregorianCalendar:

// You may prefer Java Calendars over JDBC Timestamps
public class CalendarConverter implements Converter<Timestamp, GregorianCalendar> {

    public GregorianCalendar from(Timestamp databaseObject) {
        GregorianCalendar calendar = (GregorianCalendar) Calendar.getInstance();
        return calendar;

    public Timestamp to(GregorianCalendar userObject) {
        return new Timestamp(userObject.getTime().getTime());

    public Class<Timestamp> fromType() {
        return Timestamp.class;

    public Class<GregorianCalendar> toType() {
        return GregorianCalendar.class;

// Now you can fetch calendar values from jOOQ's API:
List<GregorianCalendar> dates1 = create.selectFrom(BOOK).fetch().getValues(BOOK.PUBLISHING_DATE, new CalendarConverter());
List<GregorianCalendar> dates2 = create.selectFrom(BOOK).fetch(BOOK.PUBLISHING_DATE, new CalendarConverter());

Enum Converters

jOOQ ships with a built-in default org.jooq.impl.EnumConverter, that you can use to map VARCHAR values to enum literals or NUMBER values to enum ordinals (both modes are supported). Let's say, you want to map a YES / NO / MAYBE column to a custom Enum:

// Define your Enum
public enum YNM {

// Define your converter
public class YNMConverter extends EnumConverter<String, YNM> {
    public YNMConverter() {
        super(String.class, YNM.class);

// And you're all set for converting records to your custom Enum:
for (BookRecord book : create.selectFrom(BOOK).fetch()) {
    switch (book.getValue(BOOK.I_LIKE, new YNMConverter())) {
        case YES:    System.out.println("I like this book             : " + book.getTitle()); break;
        case NO:     System.out.println("I didn't like this book      : " + book.getTitle()); break;
        case MAYBE:  System.out.println("I'm not sure about this book : " + book.getTitle()); break;

If you're using forcedTypes in your code generation configuration, you can configure the application of an EnumConverter by adding <enumConverter>true</enumConverter> to your <forcedType/> configuration.

Using Converters in generated source code

jOOQ also allows for generated source code to reference your own custom converters, in order to permanently replace a table column's <T> type by your own, custom <U> type. See the manual's section about custom data types for details.

References to this page


Do you have any feedback about this page? We'd love to hear it!

The jOOQ Logo