Type Handlers

A Type Handler converts between Java types and database column types for reading and writing. For example, using String to read and write a VARCHAR column.

Type Handlers can effectively handle special database types such as geospatial types, currency types, timezone-aware times, enums, and serialization.

Type Handler Selection Priority

When no Type Handler is explicitly specified, dbVisitor automatically selects one in the following priority order:

1. Java type + JDBC type (combo type table)
2. Java type (single type table), most common
3. JDBC type
4. Use UnknownTypeHandler (fallback)

Example: specify via javaType

select * from users where name = #{name, javaType=java.lang.String}

• Java type java.lang.String maps to StringTypeHandler (see the single type table).

Example: specify via javaType + jdbcType

select * from users where name = #{name, jdbcType=varchar, javaType=java.lang.String}

• JDBC type VARCHAR + Java type java.lang.String maps to StringTypeHandler (see the combo type table).

info

• Most Type Handlers do not require a JDBC type when reading or writing data.
• Usually you only need to specify the Java type for parameter setting and result set reading (stored procedure OUT parameters are the main exception).

If the built-in Type Handlers do not meet your needs, you can create a custom Type Handler to handle special cases.

Usage Guide

• Basic Type Handlers: learn about the rich set of built-in Type Handlers in dbVisitor.

• Enum Type Handling: enum types automatically use EnumTypeHandler, with support for custom mapping.

• Serialization Handlers: serialize Java objects as JSON into database columns.

• Geospatial Types: read/write OpenGIS WKT/WKB geospatial data via JTS.

• Stream Type Handlers: read/write streaming data via InputStream/Reader.

• Array type handlers, for reading and writing SQL arrays.

• Vector type handlers, for PostgreSQL and ClickHouse vector fields.