apache/shardingsphere · error · SQLFeatureNotSupportedException

setRef

Error message

setRef

What it means

SQLFeatureNotSupportedException('setRef') thrown by AbstractUnsupportedOperationPreparedStatement.setRef(int, Ref). SQL REF columns (references to structured SQL3 types) are essentially unimplemented across mainstream databases and cannot be re-bound by ShardingSphere's pipeline, so the final override always throws.

Source

Thrown at jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/unsupported/AbstractUnsupportedOperationPreparedStatement.java:84

    
    @Override
    public final void setNCharacterStream(final int parameterIndex, final Reader x) throws SQLException {
        throw new SQLFeatureNotSupportedException("setNCharacterStream");
    }
    
    @Override
    public final void setNCharacterStream(final int parameterIndex, final Reader x, final long length) throws SQLException {
        throw new SQLFeatureNotSupportedException("setNCharacterStream");
    }
    
    @Override
    public final void setRowId(final int parameterIndex, final RowId x) throws SQLException {
        throw new SQLFeatureNotSupportedException("setRowId");
    }
    
    @Override
    public final void setRef(final int parameterIndex, final Ref x) throws SQLException {
        throw new SQLFeatureNotSupportedException("setRef");
    }
    
    @Override
    public final ResultSet executeQuery(final String sql) throws SQLException {
        throw new SQLFeatureNotSupportedException("executeQuery with SQL for PreparedStatement");
    }
    
    @Override
    public final int executeUpdate(final String sql) throws SQLException {
        throw new SQLFeatureNotSupportedException("executeUpdate with SQL for PreparedStatement");
    }
    
    @Override
    public final int executeUpdate(final String sql, final int autoGeneratedKeys) throws SQLException {
        throw new SQLFeatureNotSupportedException("executeUpdate with SQL for PreparedStatement");
    }
    
    @Override

View on GitHub (pinned to e952770a21)

Solutions

1. Model the relationship with an ordinary foreign-key column and bind its value (setLong/setString) instead of a REF.
2. Delete the setRef branch from generic binders — no mainstream backend path through ShardingSphere supports it.
3. If REF semantics are truly required, bypass the sharded datasource for that specific operation.

Example fix

// before
ps.setRef(1, ref);

// after
ps.setLong(1, targetId); // store the referenced object's key

if (value instanceof Ref) { throw new IllegalArgumentException("SQL REF unsupported; bind the referenced key instead"); } else { ps.setObject(idx, value); }

When it happens

Trigger: ps.setRef(1, ref) on a ShardingSphere PreparedStatement; only reachable through code explicitly handling java.sql.Ref — generic framework dispatch or legacy SQL3-era database code.

Common situations: Porting ancient SQL3/Object-Relational code paths; coverage-completeness wrappers that implement every PreparedStatement setter; almost never seen with real MySQL/PostgreSQL/OpenGauss schemas.

Related errors

• getMetaData
• setNString
• setNClob
• setNCharacterStream
• setRowId

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