apache/shardingsphere · error · SQLFeatureNotSupportedException

createStruct

Error message

createStruct

What it means

ShardingSphere's JDBC driver does not implement the java.sql.Connection method createStruct (creating a java.sql.Struct for sending SQL structured/object types (e.g. Oracle OBJECT types) to the database). The abstract base class AbstractUnsupportedOperationConnection, which ShardingSphereConnection extends, overrides it as final and unconditionally throws SQLFeatureNotSupportedException. Structured type mapping is not supported by ShardingSphere's SQL rewriting engine, so the factory always throws. The exception is thrown the moment the method is invoked on any connection produced by the ShardingSphere Driver.

Source

Thrown at jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/unsupported/AbstractUnsupportedOperationConnection.java:114

    
    @Override
    public Clob createClob() throws SQLException {
        throw new SQLFeatureNotSupportedException("createClob");
    }
    
    @Override
    public final NClob createNClob() throws SQLException {
        throw new SQLFeatureNotSupportedException("createNClob");
    }
    
    @Override
    public final SQLXML createSQLXML() throws SQLException {
        throw new SQLFeatureNotSupportedException("createSQLXML");
    }
    
    @Override
    public final Struct createStruct(final String typeName, final Object[] attributes) throws SQLException {
        throw new SQLFeatureNotSupportedException("createStruct");
    }
    
    @Override
    public final Properties getClientInfo() throws SQLException {
        throw new SQLFeatureNotSupportedException("getClientInfo");
    }
    
    @Override
    public final String getClientInfo(final String name) throws SQLException {
        throw new SQLFeatureNotSupportedException("getClientInfo name");
    }
    
    @Override
    public final void setClientInfo(final String name, final String value) {
        throw new UnsupportedSQLOperationException("setClientInfo name value");
    }
    
    @Override

View on GitHub (pinned to e952770a21)

Solutions

  1. Rewrite the object-type binding as plain columns (a normalized table or JSON serialization) that ShardingSphere can route.
  2. Keep a native Oracle connection (separate DataSource) for the STRUCT-dependent statements.
  3. Unwrap the underlying Oracle connection, create the Struct on it, and bind it only after verifying ShardingSphere passes the parameter through unchanged.
Defensive patterns

Strategy: try-catch

Validate before calling

boolean supportsOp = false;
try {
    connection.getMetaData(); // connection is alive
    // JDBC has no capability flag for individual methods; probe once per JVM:
    supportsOp = probeSupport(connection); // reflective/one-time guarded call
} catch (final SQLException ignored) {
}
// Simpler and recommended: capability-check by driver URL
boolean isShardingSphere = url.startsWith("jdbc:shardingsphere:");
if (isShardingSphere) {
    // skip the unsupported call, use the alternative API path
}

Try / catch

try {
    connection.createStruct(/* args */);
} catch (final SQLFeatureNotSupportedException e) {
    // expected on ShardingSphere connections: fall back to supported API
    log.debug("Driver does not support createStruct, using fallback", e);
}

Prevention

When it happens

Trigger: Calling Connection.createStruct(typeName, attributes) on a ShardingSphere connection.

Common situations: Oracle applications using SQL OBJECT types / AQ payloads; legacy JDBC code migrating to sharded topology where STRUCT binding previously worked.

Related errors

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/4da9f710da490399. Report an issue: GitHub.