apache/shardingsphere · error · SQLFeatureNotSupportedException

nativeSQL

Error message

nativeSQL

What it means

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.

Source

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

    
    @Override
    public final CallableStatement prepareCall(final String sql) throws SQLException {
        throw new SQLFeatureNotSupportedException("prepareCall");
    }
    
    @Override
    public final CallableStatement prepareCall(final String sql, final int resultSetType, final int resultSetConcurrency) throws SQLException {
        throw new SQLFeatureNotSupportedException("prepareCall");
    }
    
    @Override
    public final CallableStatement prepareCall(final String sql, final int resultSetType, final int resultSetConcurrency, final int resultSetHoldability) throws SQLException {
        throw new SQLFeatureNotSupportedException("prepareCall");
    }
    
    @Override
    public final String nativeSQL(final String sql) throws SQLException {
        throw new SQLFeatureNotSupportedException("nativeSQL");
    }
    
    @Override
    public final void abort(final Executor executor) throws SQLException {
        throw new SQLFeatureNotSupportedException("abort");
    }
    
    @Override
    public final Map<String, Class<?>> getTypeMap() throws SQLException {
        throw new SQLFeatureNotSupportedException("getTypeMap");
    }
    
    @Override
    public final void setTypeMap(final Map<String, Class<?>> map) throws SQLException {
        throw new SQLFeatureNotSupportedException("setTypeMap");
    }
    
    @Override

View on GitHub (pinned to e952770a21)

Solutions

  1. Remove or skip the nativeSQL call when the connection is a ShardingSphere connection.
  2. 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.
  3. Unwrap the real connection (connection.unwrap(UnderlyingConnection.class)) and call nativeSQL on it if the underlying driver's translation is acceptable.
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.nativeSQL(/* args */);
} catch (final SQLFeatureNotSupportedException e) {
    // expected on ShardingSphere connections: fall back to supported API
    log.debug("Driver does not support nativeSQL, using fallback", e);
}

Prevention

When it happens

Trigger: Calling Connection.nativeSQL(sql) on a Connection produced by the ShardingSphere driver.

Common situations: 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.

Related errors

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