GH-929: Add UUID support in JDBC driver

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

@@ -40,11 +40,15 @@
 import org.apache.arrow.driver.jdbc.converter.impl.TimestampAvaticaParameterConverter;
 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.UuidAvaticaParameterConverter;
 import org.apache.arrow.driver.jdbc.converter.impl.Utf8ViewAvaticaParameterConverter;
 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;