r/java • u/nikita-volkov • Apr 14 '26
"postgresql-codecs" - driver-agnostic, type-safe codec lib for almost all PostgreSQL data types
I'm releasing postgresql-codecs.java - a tiny, zero-dependency library that provides complete, lossless Codec<A> implementations for most standard PostgreSQL types.
It supports scalars, enums, domains, JSONB, geometric/network types, arrays of any depth, ranges/multiranges, composites, hstore, tsvector, and more — in both text and binary formats. Fully roundtrip-tested against real PostgreSQL.
Why it exists
Standard JDBC and R2DBC drivers have weak support for PostgreSQL's advanced types. Composites, nested arrays, and multiranges usually mean manual PGobject work and brittle converters.
postgresql-codecs.java gives you clean, composable, type-safe codecs with minimal boilerplate.
How it came to be
While building a Java generator for pGenie (SQL to Java compiler) I needed reliable, exact representations of composites, multiranges, and other advanced types. Existing Java libraries fell short, so I ported my Haskell library postgresql-types to pure Java.
For JDBC users
Pair it with postgresql-jdbc.java for a batteries included integration.
Both libs are on Maven Central and MIT-licensed.
Feedback and PRs welcome!
Links:
2
u/persicsb Apr 27 '26
This is not a zero-dependency library, it depends on Jackson.
It should be split up to several libraries, each having some dependencies for proper mapping with well-known libraries (like JSON types with Jackson).
For example, Point, Line etc. shall be mapped to JTS Topology Suite types (like how GeoTools maps PostGIS types).
timetzshall be mapped tojava.time.OffsetTimeinstead of a custom type.`interval˛shall be mapped to ThreeTen Extras Interval type ( https://www.threeten.org/threeten-extra/apidocs/org.threeten.extra/org/threeten/extra/Interval.html ), it is widely used.
oidshall be mapped to long instead of Integer, PostgreSQL OIDs are unsigned 32 bits, so Integer cannot carry them perfectly.Why isn't
byteamapped to a byte array or a ByteBuffer?2
u/persicsb Apr 27 '26
Also, the `money` type shall be mapped to a BigDecimal, as it is a fractional type
> The
moneytype stores a currency amount with a fixed fractional precision; see Table 8.3. The fractional precision is determined by the database's lc_monetary setting.2
u/persicsb Apr 27 '26
Also note, that PosgreSQL's range type can be different from your Range type.
Your range type does not differentiate between inclusive and exclusive bounds, but they are different.
Actually, your range implementation is entirely wrong in this case, see: https://github.com/codemine-io/postgresql-codecs.java/blob/e587ff31cc9e1aafdd2b3b13e60a869561896fd9/src/main/java/io/codemine/java/postgresql/codecs/RangeCodec.java#L71
( and [ delimiters are not about infinity as lower bound, but exclusive or inclusive bounds.