{"record":{"id":"d173d7c512207a2a","repo":"apache/shardingsphere","slug":"nativesql","errorCode":null,"errorMessage":"nativeSQL","messagePattern":"nativeSQL","errorType":"exception","errorClass":"SQLFeatureNotSupportedException","httpStatus":null,"severity":"error","filePath":"jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/unsupported/AbstractUnsupportedOperationConnection.java","lineNumber":59,"sourceCode":"    \n    @Override\n    public final CallableStatement prepareCall(final String sql) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"prepareCall\");\n    }\n    \n    @Override\n    public final CallableStatement prepareCall(final String sql, final int resultSetType, final int resultSetConcurrency) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"prepareCall\");\n    }\n    \n    @Override\n    public final CallableStatement prepareCall(final String sql, final int resultSetType, final int resultSetConcurrency, final int resultSetHoldability) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"prepareCall\");\n    }\n    \n    @Override\n    public final String nativeSQL(final String sql) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"nativeSQL\");\n    }\n    \n    @Override\n    public final void abort(final Executor executor) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"abort\");\n    }\n    \n    @Override\n    public final Map<String, Class<?>> getTypeMap() throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getTypeMap\");\n    }\n    \n    @Override\n    public final void setTypeMap(final Map<String, Class<?>> map) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"setTypeMap\");\n    }\n    \n    @Override","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/unsupported/AbstractUnsupportedOperationConnection.java#L41-L77","documentation":"ShardingSphere's JDBC driver does not implement the java.sql.Connection method nativeSQL (converting JDBC SQL grammar into the database's native SQL dialect). The abstract base class AbstractUnsupportedOperationConnection, which ShardingSphereConnection extends, overrides it as final and unconditionally throws SQLFeatureNotSupportedException. ShardingSphere rewrites SQL itself during routing, so it exposes no pass-through native-SQL translation and declares the method unsupported. The exception is thrown the moment the method is invoked on any connection produced by the ShardingSphere Driver.","triggerScenarios":"Calling Connection.nativeSQL(sql) on a Connection produced by the ShardingSphere driver.","commonSituations":"Logging/debugging utilities that print the 'native' SQL a driver would send; frameworks that pre-translate SQL (e.g. EscapeSyntax processors for date/time/literal escapes like {fn ...} or {ts ...}); tools that call nativeSQL for dialect detection.","solutions":["Remove or skip the nativeSQL call when the connection is a ShardingSphere connection.","If you need the actual SQL sent to a real database, use ShardingSphere's SQL show / audit logging (sql-show=true or proxy logging) instead of nativeSQL.","Unwrap the real connection (connection.unwrap(UnderlyingConnection.class)) and call nativeSQL on it if the underlying driver's translation is acceptable."],"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.nativeSQL(/* args */);\n} catch (final SQLFeatureNotSupportedException e) {\n    // expected on ShardingSphere connections: fall back to supported API\n    log.debug(\"Driver does not support nativeSQL, using fallback\", e);\n}","preventionTips":["Do not use nativeSQL for dialect detection with ShardingSphere; detect via DatabaseMetaData.getURL() or configuration instead.","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"}