Exposed Fastjson2 Serialization

Library module

Problem

This module maps Kotlin values to Exposed JSON and JSONB columns with Fastjson2. It also supplies typed row readers and dialect-aware contains, exists, and extract expressions. The database stores JSON, not the Kotlin type or serializer configuration, so the application must own that compatibility contract.

When to use it

Use it when Fastjson2 is already the application’s JSON stack and database rows must be read as domain values. Prefer Jackson 2 or 3 when their annotation/module ecosystem is the stronger compatibility requirement. Do not select a codec from a generic performance claim; measure the payloads and configuration used in production.

Coordinates

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-fastjson2")
}

Core concepts

• fastjson<T> uses the dialect JSON type; fastjsonb<T> uses JSONB and reports binary format.
• DefaultFastjsonSerializer delegates to the shared Fastjson2 serializer.
• ResultRow and R2DBC Readable extensions deserialize typed values, objects, and arrays.
• contains, exists, and extract render through the active Exposed dialect; supported paths differ by database.

Quick start

data class Settings(val theme: String, val alerts: Boolean)

object Accounts : LongIdTable("accounts") {
    val settings = fastjson<Settings>("settings")
}

transaction {
    Accounts.insert { it[settings] = Settings("dark", true) }
    val stored = Accounts.selectAll().single()[Accounts.settings]
}

API by task

Task	Stable 1.11 API
JSON/JSONB column	fastjson, fastjsonb, FastjsonColumnType, FastjsonBColumnType
Typed row read	getFastjson, getFastjsonOrNull
Dynamic tree read	getFastjsonObject, getFastjsonArray and nullable variants
JSON predicates	contains, exists
Path extraction	extract<T>

Recommended patterns

Keep one serializer policy for every writer and reader of a column. Add fields with defaults when old rows must remain readable. For breaking shape or type changes, deploy a reader that accepts both shapes, backfill rows, and remove the old reader only after the migration is complete.

Integrations

The column DSL works with Exposed core and can be read from JDBC ResultRow or R2DBC Readable. JSON SQL operators depend on the selected database dialect; test every predicate against the production database rather than assuming PostgreSQL behavior elsewhere.

Configuration

Pass a custom FastjsonSerializer when naming, polymorphism, date/time, or unknown-field behavior differs from the default. Treat that configuration as persisted-data schema: changing it can make existing rows unreadable even when the SQL column is unchanged.

Failure modes

• A serializer returning null for non-null T raises IllegalArgumentException.
• Malformed or incompatible JSON fails while reading the row.
• An unexpected driver value type raises IllegalStateException.
• A JSON path or operator unsupported by the dialect fails at SQL generation or execution.
• A Kotlin rename without an alias/default can break old rows.

Operations

Log codec failures with table, column, and record identity, but never dump sensitive JSON. Track decode failures during a dual-reader migration. JSONB may improve database-side querying, but it does not remove the need to plan indexes and validate query plans.

Testing

Round-trip representative payloads, missing and unknown fields, nullable columns, malformed JSON, and the oldest supported stored shape. Run dialect tests for JSON and JSONB plus each contains/exists/extract query used by the application.

./gradlew :bluetape4k-exposed-fastjson2:test

Workshops and learning path

Start with the serialization and encryption guide. Then inspect the module tests for JSON/JSONB round trips and row-reader behavior, and continue with transaction boundaries before placing codec calls in a repository.

Limitations

The module does not version JSON documents, migrate stored rows, choose indexes, or guarantee that JSON functions behave identically across dialects. Fastjson2, Jackson 2, and Jackson 3 modules are alternatives for a column contract; switching one for another requires stored-data compatibility proof.

Release diagrams

These diagrams are loaded directly from README assets published with the 1.11.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

Fastjson2 JSON column boundary

Release README: exposed/fastjson2/README.md

Fastjson2 JSON round trip

Release README: exposed/fastjson2/README.md

Sources

• Gradle build file
• JSON column type
• JSONB column type
• JSON expressions
• Round-trip tests