{"record":{"id":"4da9f710da490399","repo":"apache/shardingsphere","slug":"createstruct","errorCode":null,"errorMessage":"createStruct","messagePattern":"createStruct","errorType":"exception","errorClass":"SQLFeatureNotSupportedException","httpStatus":null,"severity":"error","filePath":"jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/unsupported/AbstractUnsupportedOperationConnection.java","lineNumber":114,"sourceCode":"    \n    @Override\n    public Clob createClob() throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"createClob\");\n    }\n    \n    @Override\n    public final NClob createNClob() throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"createNClob\");\n    }\n    \n    @Override\n    public final SQLXML createSQLXML() throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"createSQLXML\");\n    }\n    \n    @Override\n    public final Struct createStruct(final String typeName, final Object[] attributes) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"createStruct\");\n    }\n    \n    @Override\n    public final Properties getClientInfo() throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getClientInfo\");\n    }\n    \n    @Override\n    public final String getClientInfo(final String name) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getClientInfo name\");\n    }\n    \n    @Override\n    public final void setClientInfo(final String name, final String value) {\n        throw new UnsupportedSQLOperationException(\"setClientInfo name value\");\n    }\n    \n    @Override","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/unsupported/AbstractUnsupportedOperationConnection.java#L96-L132","documentation":"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.","triggerScenarios":"Calling Connection.createStruct(typeName, attributes) on a ShardingSphere connection.","commonSituations":"Oracle applications using SQL OBJECT types / AQ payloads; legacy JDBC code migrating to sharded topology where STRUCT binding previously worked.","solutions":["Rewrite the object-type binding as plain columns (a normalized table or JSON serialization) that ShardingSphere can route.","Keep a native Oracle connection (separate DataSource) for the STRUCT-dependent statements.","Unwrap the underlying Oracle connection, create the Struct on it, and bind it only after verifying ShardingSphere passes the parameter through unchanged."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"boolean supportsOp = false;\ntry {\n    connection.getMetaData(); // connection is alive\n    // JDBC has no capability flag for individual methods; probe once per JVM:\n    supportsOp = probeSupport(connection); // reflective/one-time guarded call\n} catch (final SQLException ignored) {\n}\n// Simpler and recommended: capability-check by driver URL\nboolean isShardingSphere = url.startsWith(\"jdbc:shardingsphere:\");\nif (isShardingSphere) {\n    // skip the unsupported call, use the alternative API path\n}","typeGuard":null,"tryCatchPattern":"try {\n    connection.createStruct(/* args */);\n} catch (final SQLFeatureNotSupportedException e) {\n    // expected on ShardingSphere connections: fall back to supported API\n    log.debug(\"Driver does not support createStruct, using fallback\", e);\n}","preventionTips":["Do not use SQL STRUCT/OBJECT types through ShardingSphere; normalize to columns or use a native connection.","Check the JDBC URL before calling optional JDBC 4 methods: connections starting with jdbc:shardingsphere: never support the lob/network-timeout/client-info/callable APIs.","Catch java.sql.SQLFeatureNotSupportedException (parent of ShardingSphere's UnsupportedSQLOperationException) around optional driver-capability calls so the application degrades gracefully."],"tags":["jdbc","shardingsphere","unsupported-operation","connection-api"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}