GH-929: Add UUID support in JDBC driver

dataset/pom.xml

@@ -33,7 +33,7 @@ under the License.
   <properties>
     <arrow.cpp.build.dir>../../../cpp/release-build/</arrow.cpp.build.dir>
     <parquet.version>1.16.0</parquet.version>
-    <avro.version>1.12.0</avro.version>
+    <avro.version>1.12.1</avro.version>
   </properties>
 
   <dependencies>

docs/source/jdbc.rst

@@ -213,7 +213,8 @@ Type Mapping
 ------------
 
 The Arrow to JDBC type mapping can be obtained at runtime via
-a method on ColumnBinder.
+a method on ColumnBinder. The Flight SQL JDBC driver follows the same
+mapping, with additional support for the UUID extension type noted below.
 
 +----------------------------+----------------------------+-------+
 | Arrow Type                 | JDBC Type                  | Notes |
@@ -232,6 +233,8 @@ a method on ColumnBinder.
 +----------------------------+----------------------------+-------+
 | FixedSizeBinary            | BINARY (setBytes)          |       |
 +----------------------------+----------------------------+-------+
+| Uuid (extension)           | OTHER (setObject)          | \(3)  |
++----------------------------+----------------------------+-------+
 | Float32                    | REAL (setFloat)            |       |
 +----------------------------+----------------------------+-------+
 | Int8                       | TINYINT (setByte)          |       |
@@ -276,3 +279,6 @@ a method on ColumnBinder.
   <https://docs.oracle.com/en/java/javase/11/docs/api/java.sql/java/sql/PreparedStatement.html#setTimestamp(int,java.sql.Timestamp)>`_,
   which will lead to the driver using the "default timezone" (that of
   the Java VM).
+* \(3) For the Flight SQL JDBC driver, the Arrow UUID extension type
+  (``arrow.uuid``) maps to JDBC ``OTHER`` and is surfaced as
+  ``java.util.UUID`` values.

flight/flight-sql-jdbc-core/pom.xml

@@ -151,7 +151,7 @@ under the License.
     <dependency>
       <groupId>com.github.ben-manes.caffeine</groupId>
       <artifactId>caffeine</artifactId>
-      <version>3.2.0</version>
+      <version>3.2.3</version>
     </dependency>
   </dependencies>
 

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/ArrowDatabaseMetadata.java

@@ -75,10 +75,12 @@
 import org.apache.arrow.vector.VarBinaryVector;
 import org.apache.arrow.vector.VarCharVector;
 import org.apache.arrow.vector.VectorSchemaRoot;
+import org.apache.arrow.vector.extension.UuidType;
 import org.apache.arrow.vector.ipc.ReadChannel;
 import org.apache.arrow.vector.ipc.message.MessageSerializer;
 import org.apache.arrow.vector.types.Types;
 import org.apache.arrow.vector.types.pojo.ArrowType;
+import org.apache.arrow.vector.types.pojo.ExtensionTypeRegistry;
 import org.apache.arrow.vector.types.pojo.Field;
 import org.apache.arrow.vector.types.pojo.Schema;
 import org.apache.arrow.vector.util.Text;
@@ -164,6 +166,9 @@ public class ArrowDatabaseMetadata extends AvaticaDatabaseMetaData {
         LONGNVARCHAR, SqlSupportsConvert.SQL_CONVERT_LONGVARCHAR_VALUE);
     sqlTypesToFlightEnumConvertTypes.put(DATE, SqlSupportsConvert.SQL_CONVERT_DATE_VALUE);
     sqlTypesToFlightEnumConvertTypes.put(TIMESTAMP, SqlSupportsConvert.SQL_CONVERT_TIMESTAMP_VALUE);
+
+    // Register the UUID extension type so it is always available for the driver
+    ExtensionTypeRegistry.register(UuidType.INSTANCE);
   }
 
   ArrowDatabaseMetadata(final AvaticaConnection connection) {

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/accessor/ArrowFlightJdbcAccessorFactory.java

@@ -19,6 +19,7 @@
 import java.util.function.IntSupplier;
 import org.apache.arrow.driver.jdbc.accessor.impl.ArrowFlightJdbcNullVectorAccessor;
 import org.apache.arrow.driver.jdbc.accessor.impl.binary.ArrowFlightJdbcBinaryVectorAccessor;
+import org.apache.arrow.driver.jdbc.accessor.impl.binary.ArrowFlightJdbcUuidVectorAccessor;
 import org.apache.arrow.driver.jdbc.accessor.impl.calendar.ArrowFlightJdbcDateVectorAccessor;
 import org.apache.arrow.driver.jdbc.accessor.impl.calendar.ArrowFlightJdbcDurationVectorAccessor;
 import org.apache.arrow.driver.jdbc.accessor.impl.calendar.ArrowFlightJdbcIntervalVectorAccessor;
@@ -65,6 +66,7 @@
 import org.apache.arrow.vector.UInt2Vector;
 import org.apache.arrow.vector.UInt4Vector;
 import org.apache.arrow.vector.UInt8Vector;
+import org.apache.arrow.vector.UuidVector;
 import org.apache.arrow.vector.ValueVector;
 import org.apache.arrow.vector.VarBinaryVector;
 import org.apache.arrow.vector.VarCharVector;
@@ -138,6 +140,9 @@ public static ArrowFlightJdbcAccessor createAccessor(
     } else if (vector instanceof LargeVarBinaryVector) {
       return new ArrowFlightJdbcBinaryVectorAccessor(
           (LargeVarBinaryVector) vector, getCurrentRow, setCursorWasNull);
+    } else if (vector instanceof UuidVector) {
+      return new ArrowFlightJdbcUuidVectorAccessor(
+          (UuidVector) vector, getCurrentRow, setCursorWasNull);
     } else if (vector instanceof FixedSizeBinaryVector) {
       return new ArrowFlightJdbcBinaryVectorAccessor(
           (FixedSizeBinaryVector) vector, getCurrentRow, setCursorWasNull);

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/accessor/impl/binary/ArrowFlightJdbcUuidVectorAccessor.java

@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.arrow.driver.jdbc.accessor.impl.binary;
+
+import java.util.UUID;
+import java.util.function.IntSupplier;
+import org.apache.arrow.driver.jdbc.accessor.ArrowFlightJdbcAccessor;
+import org.apache.arrow.driver.jdbc.accessor.ArrowFlightJdbcAccessorFactory;
+import org.apache.arrow.vector.UuidVector;
+import org.apache.arrow.vector.util.UuidUtility;
+
+/**
+ * Accessor for the Arrow UUID extension type ({@link UuidVector}).
+ *
+ * <p>This accessor provides JDBC-compatible access to UUID values stored in Arrow's canonical UUID
+ * extension type ('arrow.uuid'). It follows PostgreSQL JDBC driver conventions:
+ *
+ * <ul>
+ *   <li>{@link #getObject()} returns {@link java.util.UUID}
+ *   <li>{@link #getString()} returns the hyphenated string format (e.g.,
+ *       "550e8400-e29b-41d4-a716-446655440000")
+ *   <li>{@link #getBytes()} returns the 16-byte binary representation
+ * </ul>
+ */
+public class ArrowFlightJdbcUuidVectorAccessor extends ArrowFlightJdbcAccessor {
+
+  private final UuidVector vector;
+
+  /**
+   * Creates a new accessor for a UUID vector.
+   *
+   * @param vector the UUID vector to access
+   * @param currentRowSupplier supplier for the current row index
+   * @param setCursorWasNull consumer to set the wasNull flag
+   */
+  public ArrowFlightJdbcUuidVectorAccessor(
+      UuidVector vector,
+      IntSupplier currentRowSupplier,
+      ArrowFlightJdbcAccessorFactory.WasNullConsumer setCursorWasNull) {
+    super(currentRowSupplier, setCursorWasNull);
+    this.vector = vector;
+  }
+
+  @Override
+  public Object getObject() {
+    UUID uuid = vector.getObject(getCurrentRow());
+    this.wasNull = uuid == null;
+    this.wasNullConsumer.setWasNull(this.wasNull);
+    return uuid;
+  }
+
+  @Override
+  public Class<?> getObjectClass() {
+    return UUID.class;
+  }
+
+  @Override
+  public String getString() {
+    UUID uuid = (UUID) getObject();
+    if (uuid == null) {
+      return null;
+    }
+    return uuid.toString();
+  }
+
+  @Override
+  public byte[] getBytes() {
+    UUID uuid = (UUID) getObject();
+    if (uuid == null) {
+      return null;
+    }
+    return UuidUtility.getBytesFromUUID(uuid);
+  }
+}

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/converter/impl/UuidAvaticaParameterConverter.java

@@ -0,0 +1,103 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.arrow.driver.jdbc.converter.impl;
+
+import static org.apache.arrow.driver.jdbc.utils.SqlTypes.getSqlTypeIdFromArrowType;
+import static org.apache.arrow.driver.jdbc.utils.SqlTypes.getSqlTypeNameFromArrowType;
+
+import java.nio.ByteBuffer;
+import java.util.UUID;
+import org.apache.arrow.driver.jdbc.converter.AvaticaParameterConverter;
+import org.apache.arrow.vector.FieldVector;
+import org.apache.arrow.vector.UuidVector;
+import org.apache.arrow.vector.types.pojo.Field;
+import org.apache.arrow.vector.util.UuidUtility;
+import org.apache.calcite.avatica.AvaticaParameter;
+import org.apache.calcite.avatica.remote.TypedValue;
+import org.apache.calcite.avatica.util.ByteString;
+
+/**
+ * AvaticaParameterConverter for UUID Arrow extension type.
+ *
+ * <p>Handles conversion of UUID values from JDBC parameters to Arrow's UUID extension type. Accepts
+ * both {@link UUID} objects and String representations of UUIDs.
+ */
+public class UuidAvaticaParameterConverter implements AvaticaParameterConverter {
+
+  public UuidAvaticaParameterConverter() {}
+
+  @Override
+  public boolean bindParameter(FieldVector vector, TypedValue typedValue, int index) {
+    if (!(vector instanceof UuidVector)) {
+      return false;
+    }
+
+    UuidVector uuidVector = (UuidVector) vector;
+    Object value = typedValue.toJdbc(null);
+
+    if (value == null) {
+      uuidVector.setNull(index);
+      return true;
+    }
+
+    UUID uuid;
+    if (value instanceof UUID) {
+      uuid = (UUID) value;
+    } else if (value instanceof String) {
+      uuid = UUID.fromString((String) value);
+    } else if (value instanceof byte[]) {
+      byte[] bytes = (byte[]) value;
+      if (bytes.length != 16) {
+        throw new IllegalArgumentException("UUID byte array must be 16 bytes, got " + bytes.length);
+      }
+      uuid = uuidFromBytes(bytes);
+    } else if (value instanceof ByteString) {
+      byte[] bytes = ((ByteString) value).getBytes();
+      if (bytes.length != 16) {
+        throw new IllegalArgumentException("UUID byte array must be 16 bytes, got " + bytes.length);
+      }
+      uuid = uuidFromBytes(bytes);
+    } else {
+      throw new IllegalArgumentException(
+          "Cannot convert " + value.getClass().getName() + " to UUID");
+    }
+
+    uuidVector.setSafe(index, UuidUtility.getBytesFromUUID(uuid));
+    return true;
+  }
+
+  @Override
+  public AvaticaParameter createParameter(Field field) {
+    final String name = field.getName();
+    final int jdbcType = getSqlTypeIdFromArrowType(field.getType());
+    final String typeName = getSqlTypeNameFromArrowType(field.getType());
+    final String className = UUID.class.getCanonicalName();
+    return new AvaticaParameter(false, 0, 0, jdbcType, typeName, className, name);
+  }
+
+  private static UUID uuidFromBytes(byte[] bytes) {
+    final long mostSignificantBits;
+    final long leastSignificantBits;
+    ByteBuffer bb = ByteBuffer.wrap(bytes);
+    // Reads the first eight bytes
+    mostSignificantBits = bb.getLong();
+    // Reads the first eight bytes at this buffer's current
+    leastSignificantBits = bb.getLong();
+
+    return new UUID(mostSignificantBits, leastSignificantBits);
+  }
+}

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/AvaticaParameterBinder.java

@@ -41,10 +41,14 @@
 import org.apache.arrow.driver.jdbc.converter.impl.UnionAvaticaParameterConverter;
 import org.apache.arrow.driver.jdbc.converter.impl.Utf8AvaticaParameterConverter;
 import org.apache.arrow.driver.jdbc.converter.impl.Utf8ViewAvaticaParameterConverter;
+import org.apache.arrow.driver.jdbc.converter.impl.UuidAvaticaParameterConverter;
 import org.apache.arrow.memory.BufferAllocator;
 import org.apache.arrow.vector.FieldVector;
 import org.apache.arrow.vector.VectorSchemaRoot;
+import org.apache.arrow.vector.extension.UuidType;
 import org.apache.arrow.vector.types.pojo.ArrowType;
+import org.apache.arrow.vector.types.pojo.ArrowType.ArrowTypeVisitor;
+import org.apache.arrow.vector.types.pojo.ArrowType.ExtensionType;
 import org.apache.calcite.avatica.remote.TypedValue;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
@@ -290,5 +294,15 @@ public Boolean visit(ArrowType.RunEndEncoded type) {
       throw new UnsupportedOperationException(
           "No Avatica parameter binder implemented for type " + type);
     }
+
+    @Override
+    public Boolean visit(ExtensionType type) {
+      if (type instanceof UuidType) {
+        return new UuidAvaticaParameterConverter().bindParameter(vector, typedValue, index);
+      }
+
+      // fallback to default implementation
+      return ArrowTypeVisitor.super.visit(type);
+    }
   }
 }

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/ConvertUtils.java

@@ -43,8 +43,12 @@
 import org.apache.arrow.driver.jdbc.converter.impl.UnionAvaticaParameterConverter;
 import org.apache.arrow.driver.jdbc.converter.impl.Utf8AvaticaParameterConverter;
 import org.apache.arrow.driver.jdbc.converter.impl.Utf8ViewAvaticaParameterConverter;
+import org.apache.arrow.driver.jdbc.converter.impl.UuidAvaticaParameterConverter;
 import org.apache.arrow.flight.sql.FlightSqlColumnMetadata;
+import org.apache.arrow.vector.extension.UuidType;
 import org.apache.arrow.vector.types.pojo.ArrowType;
+import org.apache.arrow.vector.types.pojo.ArrowType.ArrowTypeVisitor;
+import org.apache.arrow.vector.types.pojo.ArrowType.ExtensionType;
 import org.apache.arrow.vector.types.pojo.Field;
 import org.apache.calcite.avatica.AvaticaParameter;
 import org.apache.calcite.avatica.ColumnMetaData;
@@ -294,5 +298,15 @@ public AvaticaParameter visit(ArrowType.RunEndEncoded type) {
       throw new UnsupportedOperationException(
           "No Avatica parameter binder implemented for type " + type);
     }
+
+    @Override
+    public AvaticaParameter visit(ExtensionType type) {
+      if (type instanceof UuidType) {
+        return new UuidAvaticaParameterConverter().createParameter(field);
+      }
+
+      // fallback to default implementation
+      return ArrowTypeVisitor.super.visit(type);
+    }
   }
 }

flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/SqlTypes.java

@@ -20,11 +20,13 @@
 import java.sql.Types;
 import java.util.HashMap;
 import java.util.Map;
+import org.apache.arrow.vector.extension.UuidType;
 import org.apache.arrow.vector.types.FloatingPointPrecision;
 import org.apache.arrow.vector.types.pojo.ArrowType;
 
 /** SQL Types utility functions. */
 public class SqlTypes {
+
   private static final Map<Integer, String> typeIdToName = new HashMap<>();
 
   static {
@@ -110,6 +112,9 @@ public static int getSqlTypeIdFromArrowType(ArrowType arrowType) {
       case BinaryView:
         return Types.VARBINARY;
       case FixedSizeBinary:
+        if (arrowType instanceof UuidType) {
+          return Types.OTHER;
+        }
         return Types.BINARY;
       case LargeBinary:
         return Types.LONGVARBINARY;