apache/shardingsphere · error · SQLWrapperException

HY000

HY000

Error message

Underlying SQL state: %s, underlying error code: %s.

What it means

Thrown by StandaloneMetaDataManagerPersistService.alterSingleRuleConfiguration when refreshing the in-memory rule configuration after persisting a SingleRuleConfiguration fails with a SQLException; the SQLWrapperException surfaces the underlying SQL state and error code (generic HY000). This is the standalone-mode counterpart of the cluster rule-refresh wrapper: persist succeeded, refresh failed.

Source

Thrown at mode/type/standalone/core/src/main/java/org/apache/shardingsphere/mode/manager/standalone/persist/service/StandaloneMetaDataManagerPersistService.java:212

            metaDataPersistFacade.getDatabaseMetaDataFacade().persistReloadDatabase(database.getName(), rebuildDatabaseSchemaIndex(database.getName(), reloadMetaDataContexts),
                    originalMetaDataContexts.getMetaData().getDatabase(database.getName()));
        }
        clearServicesCache();
    }
    
    private Collection<String> getToBeDroppedResourceNames(final String databaseName, final Collection<String> toBeDroppedResourceNames) {
        Map<String, DataSourcePoolProperties> propsMap = metaDataPersistFacade.getDataSourceUnitService().load(databaseName);
        return toBeDroppedResourceNames.stream().filter(propsMap::containsKey).collect(Collectors.toList());
    }
    
    @Override
    public void alterSingleRuleConfiguration(final ShardingSphereDatabase database, final RuleMetaData ruleMetaData) {
        SingleRuleConfiguration singleRuleConfig = ruleMetaData.getSingleRule(SingleRule.class).getConfiguration();
        metaDataPersistFacade.getDatabaseRuleService().persist(database.getName(), Collections.singleton(singleRuleConfig));
        try {
            metaDataContextManager.getDatabaseRuleConfigurationManager().refresh(database.getName(), singleRuleConfig);
        } catch (final SQLException ex) {
            throw new SQLWrapperException(ex);
        }
        clearServicesCache();
    }
    
    @Override
    public void alterRuleConfiguration(final ShardingSphereDatabase database, final RuleConfiguration toBeAlteredRuleConfig) {
        if (null == toBeAlteredRuleConfig) {
            return;
        }
        if (toBeAlteredRuleConfig instanceof SingleRuleConfiguration) {
            alterSingleRuleConfigurationItem(database, (SingleRuleConfiguration) toBeAlteredRuleConfig);
            return;
        }
        Collection<MetaDataVersion> metaDataVersions = metaDataPersistFacade.getDatabaseRuleService().persist(database.getName(), Collections.singleton(toBeAlteredRuleConfig));
        alterRuleItem(database.getName(), metaDataVersions);
        persistAndAlterSchemaTables(database, toBeAlteredRuleConfig.getLogicTableNames());
        clearServicesCache();
    }

View on GitHub (pinned to e952770a21)

Solutions

1. Read the cause SQLException's SQLState and vendor error code to identify the storage-side failure and fix it (connectivity, credentials, invalid rule references).
2. Validate the new rule configuration against the live datasources before submitting the alteration.
3. After fixing storage, re-submit the alteration so persist+refresh complete together and state converges.

try {
    persistService.alterSingleRuleConfiguration(database, ruleMetaData);
} catch (final SQLWrapperException ex) {
    SQLException cause = (SQLException) ex.getCause();
    // persist succeeded but refresh failed: fix storage, resubmit so persist+refresh converge
}

When it happens

Trigger: Altering a single rule configuration in standalone mode where databaseRuleConfigurationManager.refresh executes SQL against storage that fails — invalid datasource in the rule, backend down at refresh time, or dialect-unsupported refresh SQL.

Common situations: Standalone setups (no governance cluster) where the rule change is persisted locally but the storage node it references is misconfigured or unreachable, leaving persisted state and in-memory state inconsistent until refresh succeeds.

Related errors

• HY000
• database_gateway_execute_query only supports parser-approved
• database_gateway_execute_update does not accept read-only SQ
• Query did not return a result set.
• Statement class is not supported.

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