Exposed PostgreSQL Extensions

Latest stable Based on Exposed release 1.11.0

bluetape4k-exposed-postgresql adds pgvector, PostGIS, and tstzrange types and operators to the ordinary Exposed JDBC PostgreSQL path. Connection and transaction ownership remain with bluetape4k-exposed-jdbc and the application.

Problem

PostgreSQL-specific values otherwise leak as raw SQL or driver objects. This module maps vectors, geometry, and timestamp ranges to typed Exposed columns and expressions.

When to use it

Use it only when a schema uses pgvector, PostGIS, or tstzrange. Plain PostgreSQL CRUD needs the JDBC module and driver, not this extension module.

Coordinates

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.exposed:bluetape4k-exposed-postgresql")
    runtimeOnly("org.postgresql:postgresql")
    // add pgvector-java or postgis-jdbc only for the feature used
}

Core concepts

vector(dimension) supports cosine, L2, and inner-product expressions; PostGIS columns map JTS point/polygon/geometry with spatial predicates; tstzRange maps bounded timestamp ranges and overlap/contains/adjacency operators.

Quick start

object Embeddings : Table() { val value = vector("value", 768) }
transaction(db) {
    connection.registerVectorType()
    Embeddings.select(Embeddings.value.cosineDistance(queryVector.literal())).limit(20)
}

API by task

Task	API
Vector column/search	`vector`, `cosineDistance`, `l2Distance`, `innerProduct`
Spatial columns	`geoPoint`, `geoPolygon`, `geoGeometry`
Spatial predicates	`stDWithin`, `stContains`, `stIntersects`, `stArea`
Time range	`tstzRange`, `overlaps`, `contains`, `isAdjacentTo`

Recommended patterns

Install the matching server extension through migrations, register pgvector on every physical connection, and create workload-specific indexes. Page ordered results with a stable tie-breaker. Use JDBC batch APIs from the JDBC module; this extension does not redefine batching.

Integrations

The PostgreSQL driver, pgvector, PostGIS JDBC, and Exposed JDBC/time APIs are compile-only so the application chooses runtime components. Tests use Testcontainers PostgreSQL and cover range behavior plus type conversion; feature-specific server extensions remain explicit prerequisites.

Configuration

Keep SRID, vector dimension, range bounds, and extension versions in schema contracts. Configure pooling and JDBC transaction isolation in the application.

Failure modes

Missing extensions, mismatched dimensions/SRIDs, unregistered vector types, or absent indexes cause startup, conversion, or performance failures. A generated expression does not create the server extension or index.

Operations

Observe query plans, index use, distance scan size, spatial selectivity, lock time, and batch latency. Analyze representative parameter values rather than assuming an operator always uses an index.

Testing

Use Testcontainers PostgreSQL with the same extensions and migrations as production. Test value round trips, nullable columns, boundary inclusivity, operator SQL, paging order, rollback, and batch failure.

Workshops and learning path

Start with the adapter matrix, then add one extension at a time to a JDBC repository. Keep ordinary transaction rules from the transaction guide.

Limitations

The module does not manage connections, install extensions, choose indexes, or bundle optional PostgreSQL/pgvector/PostGIS drivers at runtime. It covers the types and operators present in release 1.11 only.

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.

PostgreSQL extension feature coverage

Release README: exposed/postgresql/README.md

PostgreSQL column conversion flow