refactor: centralize type logic via HyperType

Introduce a Hyper-native internal type model (HyperType) in a new
com.salesforce.datacloud.jdbc.core.types package and route every
Arrow, pg_catalog, prepared-statement, and Spark conversion through
it. Translation to java.sql.JDBCType / Types only happens at the JDBC
API boundary via HyperTypes.

New types package:
- HyperTypeKind enum (BOOL, INT8-INT64, OID, FLOAT4/8, DECIMAL, CHAR,
  VARCHAR, BINARY, VARBINARY, DATE, TIME[_TZ], TIMESTAMP[_TZ], ARRAY,
  NULL, INTERVAL, JSON)
- HyperType @value class with factories per kind and a visitor
- HyperTypes utility: toJdbcType/Code/Name, toJavaClass, getPrecision,
  getScale, getDisplaySize, isSigned, isCaseSensitive,
  needsDecimalDigits/CharOctetLength, fromJdbcTypeCode, typeInfoRows
- ArrowToHyperTypeMapper: Arrow Field -> HyperType (reads hyper:type /
  hyper:max_string_length metadata)
- HyperTypeToArrow: HyperType -> Arrow FieldType for prepared-statement
  parameter schemas
- PgCatalogTypeParser: Hyper format_type() string -> HyperType, throws
  IllegalArgumentException for any unrecognized name (no UNKNOWN
  catch-all; unsupported types fail loudly at the JDBC boundary)

Deleted:
- ColumnType.java, ArrowToColumnTypeMapper.java (replaced by
  HyperType and ArrowToHyperTypeMapper)
- QueryMetadataUtil.dbTypeToSql map (which used PG internal aliases
  int2/int4/int8/bool/float4/float8 that Hyper's format_type never
  emits) and the isDecimalType/isCharType string helpers
- ArrowUtils.SQL_TYPE_TO_FIELD_TYPE map (replaced by HyperTypeToArrow)

Migrated callers:
- ColumnMetadata holds HyperType
- DataCloudResultSetMetaData delegates to HyperTypes.*
- StreamingResultSet, DataCloudArray, DataCloudConnection.getSchemaForQueryId,
  ArrowUtils.toColumnMetaData route through ArrowToHyperTypeMapper
- QueryMetadataUtil.constructColumnData routes through PgCatalogTypeParser
- SimpleResultSet switches from JDBCType to HyperTypeKind; also picks
  up TINYINT numeric coercions and the getFloat wasNull/range-check
  fix that were planned as Phase 0 work
- ParameterBinding holds HyperType; DataCloudPreparedStatement setXxx
  methods build HyperType factories directly
- VectorPopulator.VectorValueSetterFactory keyed by HyperTypeKind
- TypeMapping.scala (Spark): switches expanded to cover TINYINT,
  NUMERIC, CHAR, NULL, FLOAT, NCHAR, NVARCHAR, LONGNVARCHAR
- DataCloudDatabaseMetadata.getTypeInfo() returns a real 18-column
  result derived from HyperTypeKind (was empty before)

Observable behaviour changes in DatabaseMetaData.getColumns():
- TYPE_NAME is now consistently JDBC-uppercase ("BIGINT", "BOOLEAN",
  "INTEGER", "DECIMAL", ...) instead of a mix of Hyper-lowercase and
  uppercase strings. INTERVAL and JSON show the Hyper-uppercase form.
- DATA_TYPE is always a java.sql.Types value (was a raw PG OID for
  types unmapped by the old dbTypeToSql).
- Numeric/decimal unified to DECIMAL (both Arrow Decimal and Hyper
  numeric map to HyperTypeKind.DECIMAL / JDBCType.DECIMAL).
- Unsupported column types throw SQLException (state 42704) rather
  than silently surfacing as Types.OTHER with a raw name.

Exception contract:
- PgCatalogTypeParser, HyperTypes.fromJdbcTypeCode, HyperTypeToArrow,
  and ArrowToHyperTypeMapper throw IllegalArgumentException for types
  they do not model. Every JDBC entry point that reaches them
  (DataCloudDatabaseMetadata.getColumns, DataCloudConnection.getSchemaForQueryId,
  DataCloudPreparedStatement.setNull / setObject / getQueryParamBuilder,
  StreamingResultSet.of) catches and wraps in SQLException with an
  appropriate SQL state (42704 / HYC00 / HY000 / 0A000).

Also fixes pre-existing DataCloudDatabaseMetadataTest expectations
that hadn't been updated when the recent "DatabaseMetaData spec
violations" commit landed (e.g. testGetJDBCMajorVersion expecting 1
rather than 4, testGetProcedures expecting .isNull() on a method now
throwing SQLFeatureNotSupportedException).

Made-with: Cursor

Author: mkaufmann

jdbc-core/src/main/java/com/salesforce/datacloud/jdbc/core/ColumnNameResolver.java

@@ -4,7 +4,7 @@
  */
 package com.salesforce.datacloud.jdbc.core;
 
-import com.salesforce.datacloud.jdbc.core.metadata.ColumnMetadata;
+import com.salesforce.datacloud.jdbc.protocol.data.ColumnMetadata;
 import java.sql.SQLException;
 import java.util.HashMap;
 import java.util.List;

jdbc-core/src/main/java/com/salesforce/datacloud/jdbc/core/DataCloudConnection.java

@@ -7,10 +7,9 @@
 import static com.salesforce.datacloud.jdbc.config.DriverVersion.formatDriverInfo;
 import static com.salesforce.datacloud.jdbc.exception.QueryExceptionHandler.createException;
 import static com.salesforce.datacloud.jdbc.logging.ElapsedLogger.logTimedValue;
-import static com.salesforce.datacloud.jdbc.util.ArrowUtils.toColumnMetaData;
+import static com.salesforce.datacloud.jdbc.protocol.data.ArrowUtils.toColumnMetaData;
 
 import com.google.protobuf.Empty;
-import com.salesforce.datacloud.jdbc.core.metadata.ColumnMetadata;
 import com.salesforce.datacloud.jdbc.core.metadata.DataCloudResultSetMetaData;
 import com.salesforce.datacloud.jdbc.core.partial.DataCloudQueryPolling;
 import com.salesforce.datacloud.jdbc.exception.DataCloudJDBCException;
@@ -22,6 +21,8 @@
 import com.salesforce.datacloud.jdbc.protocol.RowRangeIterator;
 import com.salesforce.datacloud.jdbc.protocol.async.core.AsyncStreamObserverIterator;
 import com.salesforce.datacloud.jdbc.protocol.async.core.SyncIteratorAdapter;
+import com.salesforce.datacloud.jdbc.protocol.data.ColumnMetadata;
+import com.salesforce.datacloud.jdbc.protocol.data.DefaultParameterAccumulator;
 import com.salesforce.datacloud.jdbc.protocol.grpc.QueryAccessGrpcClient;
 import com.salesforce.datacloud.jdbc.util.Deadline;
 import com.salesforce.datacloud.jdbc.util.JdbcURL;
@@ -182,7 +183,7 @@ public PreparedStatement prepareStatement(String sql) {
     }
 
     private DataCloudPreparedStatement getQueryPreparedStatement(String sql) {
-        return new DataCloudPreparedStatement(this, sql, new DefaultParameterManager());
+        return new DataCloudPreparedStatement(this, sql, new DefaultParameterAccumulator());
     }
 
     /**
@@ -281,6 +282,12 @@ public ResultSetMetaData getSchemaForQueryId(String queryId) throws SQLException
             return new DataCloudResultSetMetaData(columns);
         } catch (StatusRuntimeException ex) {
             throw createException(connectionProperties.isIncludeCustomerDetailInReason(), null, queryId, ex);
+        } catch (IllegalArgumentException ex) {
+            // Thrown by ArrowToHyperTypeMapper for Arrow types the driver does not model.
+            throw new SQLException(
+                    "Unsupported column type in query schema for queryId=" + queryId + ": " + ex.getMessage(),
+                    "0A000",
+                    ex);
         }
     }
 

jdbc-core/src/main/java/com/salesforce/datacloud/jdbc/core/DataCloudDatabaseMetadata.java

@@ -13,6 +13,8 @@
 
 import com.google.common.collect.ImmutableList;
 import com.salesforce.datacloud.jdbc.config.DriverVersion;
+import com.salesforce.datacloud.jdbc.core.metadata.DataCloudResultSetMetaData;
+import com.salesforce.datacloud.jdbc.core.types.HyperTypes;
 import com.salesforce.datacloud.jdbc.util.JdbcURL;
 import com.salesforce.datacloud.jdbc.util.ThrowingJdbcSupplier;
 import java.sql.Connection;
@@ -753,7 +755,8 @@ public ResultSet getCrossReference(
 
     @Override
     public ResultSet getTypeInfo() throws SQLException {
-        return DataCloudMetadataResultSet.empty();
+        return DataCloudMetadataResultSet.of(
+                new DataCloudResultSetMetaData(MetadataSchemas.TYPE_INFO), HyperTypes.typeInfoRows());
     }
 
     @Override

jdbc-core/src/main/java/com/salesforce/datacloud/jdbc/core/DataCloudMetadataResultSet.java

@@ -4,10 +4,10 @@
  */
 package com.salesforce.datacloud.jdbc.core;
 
-import com.salesforce.datacloud.jdbc.core.metadata.ColumnMetadata;
 import com.salesforce.datacloud.jdbc.core.metadata.DataCloudResultSetMetaData;
 import com.salesforce.datacloud.jdbc.core.resultset.ColumnAccessor;
 import com.salesforce.datacloud.jdbc.core.resultset.SimpleResultSet;
+import com.salesforce.datacloud.jdbc.protocol.data.ColumnMetadata;
 import java.sql.SQLException;
 import java.sql.Statement;
 import java.util.Collections;

jdbc-core/src/main/java/com/salesforce/datacloud/jdbc/core/DataCloudPreparedStatement.java

@@ -4,13 +4,15 @@
  */
 package com.salesforce.datacloud.jdbc.core;
 
-import static com.salesforce.datacloud.jdbc.util.ArrowUtils.toArrowByteArray;
+import static com.salesforce.datacloud.jdbc.protocol.data.ArrowUtils.toArrowByteArray;
 import static com.salesforce.datacloud.jdbc.util.DateTimeUtils.getUTCDateFromDateAndCalendar;
 import static com.salesforce.datacloud.jdbc.util.DateTimeUtils.getUTCTimeFromTimeAndCalendar;
 
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Maps;
 import com.google.protobuf.ByteString;
+import com.salesforce.datacloud.jdbc.protocol.data.HyperType;
+import com.salesforce.datacloud.jdbc.protocol.data.ParameterAccumulator;
 import com.salesforce.datacloud.jdbc.util.QueryTimeout;
 import com.salesforce.datacloud.jdbc.util.SqlErrorCodes;
 import java.io.IOException;
@@ -51,25 +53,29 @@
 @Slf4j
 public class DataCloudPreparedStatement extends DataCloudStatement implements PreparedStatement {
     private String sql;
-    private final ParameterManager parameterManager;
+    private final ParameterAccumulator parameterManager;
     private final Calendar calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"));
     // True if we are currently fetching metadata from the server, this influences the query param generation
     // to not return any data.
     private boolean fetchingMetadata = false;
 
-    DataCloudPreparedStatement(DataCloudConnection connection, ParameterManager parameterManager) {
+    DataCloudPreparedStatement(DataCloudConnection connection, ParameterAccumulator parameterManager) {
         super(connection);
         this.parameterManager = parameterManager;
     }
 
-    DataCloudPreparedStatement(DataCloudConnection connection, String sql, ParameterManager parameterManager) {
+    DataCloudPreparedStatement(DataCloudConnection connection, String sql, ParameterAccumulator parameterManager) {
         super(connection);
         this.sql = sql;
         this.parameterManager = parameterManager;
     }
 
-    private <T> void setParameter(int parameterIndex, int sqlType, T value) throws SQLException {
-        parameterManager.setParameter(parameterIndex, sqlType, value);
+    private <T> void setParameter(int parameterIndex, HyperType type, T value) throws SQLException {
+        try {
+            parameterManager.setParameter(parameterIndex, type, value);
+        } catch (IllegalArgumentException ex) {
+            throw new SQLException(ex.getMessage(), ex);
+        }
     }
 
     @Override
@@ -94,6 +100,10 @@ protected QueryParam.Builder getQueryParamBuilder(
             encodedRow = toArrowByteArray(parameterManager.getParameters(), calendar);
         } catch (IOException e) {
             throw new SQLException("Failed to encode parameters on prepared statement", e);
+        } catch (IllegalArgumentException e) {
+            // Thrown when a parameter is bound with a HyperType we cannot currently encode as
+            // Arrow (e.g. INTERVAL, JSON). Surface as a JDBC spec-compliant SQLException.
+            throw new SQLException("Failed to encode parameters on prepared statement: " + e.getMessage(), "HY000", e);
         }
 
         if (fetchingMetadata) {
@@ -131,52 +141,61 @@ public int executeUpdate() throws SQLException {
 
     @Override
     public void setNull(int parameterIndex, int sqlType) throws SQLException {
-        setParameter(parameterIndex, sqlType, null);
+        setParameter(parameterIndex, hyperTypeForJdbcCode(sqlType), null);
+    }
+
+    private static HyperType hyperTypeForJdbcCode(int sqlType) throws SQLException {
+        try {
+            return com.salesforce.datacloud.jdbc.core.types.HyperTypes.fromJdbcTypeCode(sqlType, true);
+        } catch (IllegalArgumentException ex) {
+            throw new SQLException("Unsupported JDBC type code: " + sqlType, "HYC00", ex);
+        }
     }
 
     @Override
     public void setBoolean(int parameterIndex, boolean x) throws SQLException {
-        setParameter(parameterIndex, Types.BOOLEAN, x);
+        setParameter(parameterIndex, HyperType.bool(false), x);
     }
 
     @Override
     public void setByte(int parameterIndex, byte x) throws SQLException {
-        setParameter(parameterIndex, Types.TINYINT, x);
+        setParameter(parameterIndex, HyperType.int8(false), x);
     }
 
     @Override
     public void setShort(int parameterIndex, short x) throws SQLException {
-        setParameter(parameterIndex, Types.SMALLINT, x);
+        setParameter(parameterIndex, HyperType.int16(false), x);
     }
 
     @Override
     public void setInt(int parameterIndex, int x) throws SQLException {
-        setParameter(parameterIndex, Types.INTEGER, x);
+        setParameter(parameterIndex, HyperType.int32(false), x);
     }
 
     @Override
     public void setLong(int parameterIndex, long x) throws SQLException {
-        setParameter(parameterIndex, Types.BIGINT, x);
+        setParameter(parameterIndex, HyperType.int64(false), x);
     }
 
     @Override
     public void setFloat(int parameterIndex, float x) throws SQLException {
-        setParameter(parameterIndex, Types.FLOAT, x);
+        setParameter(parameterIndex, HyperType.float8(false), x);
     }
 
     @Override
     public void setDouble(int parameterIndex, double x) throws SQLException {
-        setParameter(parameterIndex, Types.DOUBLE, x);
+        setParameter(parameterIndex, HyperType.float8(false), x);
     }
 
     @Override
     public void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException {
-        setParameter(parameterIndex, Types.DECIMAL, x);
+        HyperType type = x != null ? HyperType.decimal(x.precision(), x.scale(), true) : HyperType.decimal(0, 0, true);
+        setParameter(parameterIndex, type, x);
     }
 
     @Override
     public void setString(int parameterIndex, String x) throws SQLException {
-        setParameter(parameterIndex, Types.VARCHAR, x);
+        setParameter(parameterIndex, HyperType.varcharUnlimited(true), x);
     }
 
     @Override
@@ -186,17 +205,17 @@ public void setBytes(int parameterIndex, byte[] x) throws SQLException {
 
     @Override
     public void setDate(int parameterIndex, Date x) throws SQLException {
-        setParameter(parameterIndex, Types.DATE, x);
+        setParameter(parameterIndex, HyperType.date(true), x);
     }
 
     @Override
     public void setTime(int parameterIndex, Time x) throws SQLException {
-        setParameter(parameterIndex, Types.TIME, x);
+        setParameter(parameterIndex, HyperType.time(true), x);
     }
 
     @Override
     public void setTimestamp(int parameterIndex, Timestamp x) throws SQLException {
-        setParameter(parameterIndex, Types.TIMESTAMP, toWallClockAsUtc(x, null));
+        setParameter(parameterIndex, HyperType.timestamp(true), toWallClockAsUtc(x, null));
     }
 
     @Override
@@ -229,17 +248,17 @@ public void setObject(int parameterIndex, Object x, int targetSqlType) throws SQ
         // or store LocalDateTime digits directly.
         if (targetSqlType == Types.TIMESTAMP) {
             if (x instanceof Timestamp) {
-                setParameter(parameterIndex, Types.TIMESTAMP, toWallClockAsUtc((Timestamp) x, null));
+                setParameter(parameterIndex, HyperType.timestamp(true), toWallClockAsUtc((Timestamp) x, null));
                 return;
             }
             if (x instanceof LocalDateTime) {
                 LocalDateTime ldt = (LocalDateTime) x;
                 // Encode LDT digits as if they were in UTC — no JVM-TZ shift applied.
-                setParameter(parameterIndex, Types.TIMESTAMP, Timestamp.from(ldt.toInstant(ZoneOffset.UTC)));
+                setParameter(parameterIndex, HyperType.timestamp(true), Timestamp.from(ldt.toInstant(ZoneOffset.UTC)));
                 return;
             }
         }
-        setParameter(parameterIndex, targetSqlType, x);
+        setParameter(parameterIndex, hyperTypeForJdbcCode(targetSqlType), x);
     }
 
     @Override
@@ -307,18 +326,18 @@ public ResultSetMetaData getMetaData() throws SQLException {
     @Override
     public void setDate(int parameterIndex, Date x, Calendar cal) throws SQLException {
         val utcDate = getUTCDateFromDateAndCalendar(x, cal);
-        setParameter(parameterIndex, Types.DATE, utcDate);
+        setParameter(parameterIndex, HyperType.date(true), utcDate);
     }
 
     @Override
     public void setTime(int parameterIndex, Time x, Calendar cal) throws SQLException {
         val utcTime = getUTCTimeFromTimeAndCalendar(x, cal);
-        setParameter(parameterIndex, Types.TIME, utcTime);
+        setParameter(parameterIndex, HyperType.time(true), utcTime);
     }
 
     @Override
     public void setTimestamp(int parameterIndex, Timestamp x, Calendar cal) throws SQLException {
-        setParameter(parameterIndex, Types.TIMESTAMP, toWallClockAsUtc(x, cal));
+        setParameter(parameterIndex, HyperType.timestamp(true), toWallClockAsUtc(x, cal));
     }
 
     /**