Add the README

Author: bytefish

PgBulkInsert/src/main/java/de/bytefish/pgbulkinsert/PgBulkInsert.java

@@ -10,6 +10,8 @@
 import java.io.IOException;
 import java.math.BigDecimal;
 import java.math.BigInteger;
+import java.net.Inet4Address;
+import java.net.InetAddress;
 import java.nio.charset.StandardCharsets;
 import java.sql.Connection;
 import java.sql.SQLException;
@@ -31,6 +33,16 @@ public interface ToShortFunction<T> {
         short applyAsShort(T value);
     }
 
+    // Geometric Types
+    public record PgPoint(double x, double y) {}
+    public record PgLine(double a, double b, double c) {}
+    public record PgLseg(PgPoint p1, PgPoint p2) {}
+    public record PgBox(PgPoint p1, PgPoint p2) {}
+    public record PgPath(boolean closed, List<PgPoint> points) {}
+    public record PgPolygon(List<PgPoint> points) {}
+    public record PgCircle(PgPoint center, double radius) {}
+
+
     public record PgRange<T>(T lower, T upper, boolean lowerInclusive, boolean upperInclusive, boolean lowerInfinite,
                              boolean upperInfinite, boolean empty) {
         public static <T> PgRange<T> emptyRange() {
@@ -114,8 +126,23 @@ public interface BinaryRowWriter {
 
         void writeHstore(Map<String, String> v) throws IOException;
 
+        // Network
+        void writeInet(InetAddress v) throws IOException;
+        void writeMacAddress(String v) throws IOException;
+
+        // Geometry
+        void writePoint(PgPoint v) throws IOException;
+        void writeLine(PgLine v) throws IOException;
+        void writeLseg(PgLseg v) throws IOException;
+        void writeBox(PgBox v) throws IOException;
+        void writePath(PgPath v) throws IOException;
+        void writePolygon(PgPolygon v) throws IOException;
+        void writeCircle(PgCircle v) throws IOException;
+
+        // Arrays
         <E> void writeArray(Collection<?> elements, PgType<E> baseElementType) throws IOException;
 
+        // Ranges
         <E> void writeRange(PgRange<E> range, PgType<E> elementType) throws IOException;
     }
 
@@ -297,15 +324,54 @@ public void writeHstore(Map<String, String> v) throws IOException {
             }
         }
 
+        @Override public void writeInet(InetAddress v) throws IOException {
+            byte[] addr = v.getAddress();
+            out.writeInt(addr.length + 4);
+            out.writeByte(v instanceof Inet4Address ? 2 : 3); // PGSQL_AF_INET or INET6
+            out.writeByte(addr.length * 8); // mask
+            out.writeByte(0); // is_res
+            out.writeByte(addr.length);
+            out.write(addr);
+        }
+
+        @Override public void writeMacAddress(String v) throws IOException {
+            String[] hex = v.split("[:-]");
+            out.writeInt(6);
+            for (String s : hex) out.writeByte(Integer.parseInt(s, 16));
+        }
+
+        @Override public void writePoint(PgPoint v) throws IOException { out.writeInt(16); out.writeDouble(v.x()); out.writeDouble(v.y()); }
+
+        @Override public void writeLine(PgLine v) throws IOException { out.writeInt(24); out.writeDouble(v.a()); out.writeDouble(v.b()); out.writeDouble(v.c()); }
+
+        @Override public void writeLseg(PgLseg v) throws IOException { out.writeInt(32); writePointInternal(v.p1()); writePointInternal(v.p2()); }
+
+        @Override public void writeBox(PgBox v) throws IOException { out.writeInt(32); writePointInternal(v.p1()); writePointInternal(v.p2()); }
+
+        @Override public void writePath(PgPath v) throws IOException {
+            out.writeInt(1 + 4 + (v.points().size() * 16));
+            out.writeByte(v.closed() ? 1 : 0);
+            out.writeInt(v.points().size());
+            for (PgPoint p : v.points()) writePointInternal(p);
+        }
+
+        @Override public void writePolygon(PgPolygon v) throws IOException {
+            out.writeInt(4 + (v.points().size() * 16));
+            out.writeInt(v.points().size());
+            for (PgPoint p : v.points()) writePointInternal(p);
+        }
+
+        @Override public void writeCircle(PgCircle v) throws IOException { out.writeInt(24); writePointInternal(v.center()); out.writeDouble(v.radius()); }
+
+        private void writePointInternal(PgPoint p) throws IOException { out.writeDouble(p.x()); out.writeDouble(p.y()); }
 
         @Override public <E> void writeArray(Collection<?> elements, PgType<E> baseElementType) throws IOException {
             if (elements == null) { writeNull(); return; }
 
             // Determine dimensions
             List<Integer> dims = new ArrayList<>();
             Object current = elements;
-            while (current instanceof Collection) {
-                Collection<?> c = (Collection<?>) current;
+            while (current instanceof Collection<?> c) {
                 dims.add(c.size());
                 if (c.isEmpty()) break;
                 current = c.iterator().next();
@@ -685,6 +751,24 @@ public void write(BinaryRowWriter w, Instant v) throws IOException {
             }
         };
 
+        // Geometry
+        public static final PgType<PgPoint> POINT = createType(600, BinaryRowWriter::writePoint);
+        public static final PgType<PgLine> LINE = createType(628, BinaryRowWriter::writeLine);
+        public static final PgType<PgLseg> LSEG = createType(601, BinaryRowWriter::writeLseg);
+        public static final PgType<PgBox> BOX = createType(603, BinaryRowWriter::writeBox);
+        public static final PgType<PgPath> PATH = createType(602, BinaryRowWriter::writePath);
+        public static final PgType<PgPolygon> POLYGON = createType(604, BinaryRowWriter::writePolygon);
+        public static final PgType<PgCircle> CIRCLE = createType(718, BinaryRowWriter::writeCircle);
+
+        // Ranges
+        public static final PgType<PgRange<Integer>> INT4RANGE = createType(3904, (w, v) -> w.writeRange(v, INT4));
+        public static final PgType<PgRange<Long>> INT8RANGE = createType(3926, (w, v) -> w.writeRange(v, INT8));
+        public static final PgType<PgRange<BigDecimal>> NUMRANGE = createType(3906, (w, v) -> w.writeRange(v, NUMERIC));
+        public static final PgType<PgRange<LocalDateTime>> TSRANGE = createType(3908, (w, v) -> w.writeRange(v, TIMESTAMP));
+        public static final PgType<PgRange<Instant>> TSTZRANGE = createType(3910, (w, v) -> w.writeRange(v, TIMESTAMPTZ));
+        public static final PgType<PgRange<LocalDate>> DATERANGE = createType(3912, (w, v) -> w.writeRange(v, DATE));
+
+        // Arrays
         public static <E> PgType<Collection<E>> array(PgType<E> baseType) {
             return createType(0, (w, v) -> w.writeArray(v, baseType));
         }

PgBulkInsert/src/test/java/de/bytefish/pgbulkinsert/test/IntegrationTest.java

@@ -4,6 +4,9 @@
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.io.InputStream;
 import java.math.BigDecimal;
 import java.sql.Connection;
 import java.sql.DriverManager;
@@ -18,22 +21,23 @@
 import java.util.Arrays;
 import java.util.List;
 import java.math.BigInteger;
+import java.util.Properties;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 public class IntegrationTest {
 
-    // Passe diese Verbindungsdaten an deinen laufenden Docker-Container an
-    private static final String JDBC_URL = "jdbc:postgresql://localhost:5432/postgres";
-    private static final String DB_USER = "postgres";
-    private static final String DB_PASSWORD = "password";
-
     private static Connection connection;
 
     @BeforeAll
     public static void setupDatabase() throws Exception {
-        connection = DriverManager.getConnection(JDBC_URL, DB_USER, DB_PASSWORD);
+        Properties properties = getProperties("db.properties");
+
+        connection = DriverManager.getConnection(
+                properties.getProperty("db.url"),
+                properties.getProperty("db.user"),
+                properties.getProperty("db.password"));
 
         // Create Test Table handle all the various data types
         try (Statement stmt = connection.createStatement()) {
@@ -137,7 +141,7 @@ public void testBulkInsertSavesDataCorrectly() throws Exception {
             // Verify first element
             assertTrue(rs.next());
             assertEquals(1L, rs.getLong("id"));
-            assertEquals("Normaler Text", rs.getString("text_val"));
+            assertEquals("Normal Text", rs.getString("text_val"));
             assertEquals(new BigDecimal("42.1234"), rs.getBigDecimal("numeric_val"));
             assertEquals(new BigInteger("98765432101234567890987654321"), rs.getBigDecimal("numeric_int_val").toBigInteger());
             assertTrue(rs.getBoolean("is_active"));
@@ -160,7 +164,7 @@ public void testBulkInsertSavesDataCorrectly() throws Exception {
             // Verify Null-Byte Handling
             assertTrue(rs.next());
             assertEquals(2L, rs.getLong("id"));
-            assertEquals("Fieser  Text", rs.getString("text_val")); // \u0000 wurde restlos entfernt!
+            assertEquals("Bad  Text", rs.getString("text_val"));
             assertEquals(new BigDecimal("-99.99"), rs.getBigDecimal("numeric_val"));
             assertEquals(new BigInteger("-12345678909876543210123456789"), rs.getBigDecimal("numeric_int_val").toBigInteger());
 
@@ -183,4 +187,20 @@ public void testBulkInsertSavesDataCorrectly() throws Exception {
             assertTrue(!rs.next());
         }
     }
+
+    private static Properties getProperties(String filename) {
+
+        Properties props = new Properties();
+
+        InputStream is = ClassLoader.getSystemResourceAsStream(filename);
+
+        try {
+            props.load(is);
+        }
+        catch (IOException e) {
+            throw new RuntimeException("Could not load unittest.properties", e);
+        }
+
+        return props;
+    }
 }

README.md

@@ -25,10 +25,146 @@ You can add the following dependencies to your pom.xml to include [PgBulkInsert]
 <dependency>
     <groupId>de.bytefish</groupId>
     <artifactId>pgbulkinsert</artifactId>
-    <version>8.1.8</version>
+    <version>9.0.0</version>
 </dependency>
 ```
 
+## PgBulkInsert 9: Modern, Functional API ##
+
+PgBulkInsert 9.0.0 comes with a new API, that focuses on a functional API surface leveraging modern Java 
+features (Lambdas, Method References, and Records) and reduces memory allocation-overhead.
+
+## Quick Start ##
+
+The new API separates the What (Structure and Mapping) from the How (Execution and Configuration).
+
+### 1. Define your Data Model ###
+
+The library works with Java Records, POJOs, or any other data carrier.
+
+```java
+public record UserSession(
+    UUID id,
+    long visits,         // Primitive
+    String userAgent,    // Nullable String
+    Instant createdAt,   // Precise Timestamp
+    double[] latLon,     // Array
+    PgPoint location     // Geometric Point
+) {}
+```
+
+### 2. Define your Mapping ###
+
+The `PgMapper` is the heart of the library. It is stateless and thread-safe.
+
+```java
+PgMapper<UserSession> mapper = PgMapper.forClass(UserSession.class)
+    .map("id", PostgresTypes.UUID.from(UserSession::id))
+    
+    // ZERO-ALLOCATION: Direct access to primitives via ToLongFunction
+    .map("visits", PostgresTypes.INT8.primitive(UserSession::visits))
+    
+    // SAFE STRINGS: Strips invalid \u0000 characters to prevent COPY errors
+    .map("user_agent", PostgresTypes.TEXT.removeNullCharacters().from(UserSession::userAgent))
+    
+    // TYPE-SAFE TIME: Validated at compile-time to prevent timezone issues
+    .map("created_at", PostgresTypes.TIMESTAMPTZ.instant(UserSession::createdAt))
+    
+    // GEOMETRY: Native support for Postgres geometric types
+    .map("location", PostgresTypes.POINT.from(UserSession::location));
+```
+
+### 3. Configure and Execute ###
+
+The `PgBulkWriter` handles execution details like buffer sizes and stream management.
+
+```java
+PgBulkWriter<UserSession> writer = new PgBulkWriter<>(mapper)
+    .withBufferSize(256 * 1024); // 256 KB Buffer
+
+try (Connection conn = dataSource.getConnection()) {
+    writer.saveAll(conn, "public.user_sessions", sessionList);
+}
+```
+
+## Streaming and Lazy Evaluation ##
+
+One of the key strengths of the `saveAll` method is that it accepts an `Iterable<T>`. This means you are never 
+forced to load your entire dataset into memory.
+
+If you are working with a Java Stream (e.g., from a file, a reactive source, or another database), you 
+can pass it directly using a method reference:
+
+```java
+Stream<UserSession> massiveStream = getMassiveStreamFromSource();
+
+try (Connection conn = dataSource.getConnection()) {
+    // Uses the stream's iterator to pull data lazily
+    writer.saveAll(conn, "public.user_sessions", massiveStream::iterator);
+}
+```
+
+This approach ensures that records are transformed and written to the PostgreSQL wire format on-the-fly, 
+keeping your application's memory usage constant regardless of the total number of rows.
+
+## Mastering the Fluent API ##
+
+The API is designed around a so called `PostgresType`. This class serves as your single 
+entry point for all PostgreSQL data types.
+
+### The Power of PostgresTypes ###
+
+Instead of a generic `map()` method that tries to guess your intent, the API uses a "Type-First" 
+approach. When you type `PostgresTypes.INT4.`, your IDE will offer specific choices:
+
+* `.primitive(ToIntFunction<T>)`: High-performance path. No objects created on the heap.
+* `.boxed(Function<T, Integer>)`: Use this for nullable database columns or if your POJO uses Integer.
+* `.from(Function<T, Integer>)`: Standard object mapping.
+
+### Eliminating Timezone Confusion ###
+
+One of the most common bugs is the confusion between `timestamp` and `timestamptz`.
+
+The API solves this:
+
+* `PostgresTypes.TIMESTAMP` only allows `.localDateTime()`.
+* `PostgresTypes.TIMESTAMPTZ` allows `.instant()`, `.zonedDateTime()`, or `.offsetDateTime()`.
+
+## Advanced Type Mapping ##
+
+### N-Dimensional Arrays (Matrices & Tensors) ###
+
+```java
+// Mapping a 2D Matrix (Collection of Collections)
+.map("data_matrix", PostgresTypes.array2D(PostgresTypes.INT4).from(MyEntity::getMatrix))
+
+// Mapping a 3D Tensor
+.map("data_tensor", PostgresTypes.array3D(PostgresTypes.FLOAT8).from(MyEntity::getTensor))
+```
+
+### Ranges ###
+
+```java
+// Mapping an integer range
+.map("age_limit", PostgresTypes.INT4RANGE.from(MyEntity::getAgeRange))
+
+// Mapping a timestamp range
+.map("validity", PostgresTypes.TSRANGE.from(MyEntity::getValidityPeriod))
+```
+
+### Geometric Types ###
+
+Native support for all PostgreSQL geometric types using dedicated helper records:
+
+* `POINT`: `PostgresTypes.POINT`
+* `CIRCLE`: `PostgresTypes.CIRCLE`
+* `POLYGON`: `PostgresTypes.POLYGON`
+* `PATH` / `LSEG` / `BOX` / `LINE`
+
+```java
+.map("area", PostgresTypes.POLYGON.from(MyEntity::getBoundaries))
+```
+
 ## Supported PostgreSQL Types ##
 
 * [Numeric Types](http://www.postgresql.org/docs/current/static/datatype-numeric.html)

docker/docker-compose.yaml

@@ -2,7 +2,7 @@ version: '3.8'
 
 services:
   postgres:
-    image: postgres:16
+    image: postgres:18
     container_name: postgres
     ports:
       - "5431:5432"