{"record":{"id":"3f486768f80776d1","repo":"apache/shardingsphere","slug":"hy000","errorCode":"HY000","errorMessage":"Underlying SQL state: %s, underlying error code: %s.","messagePattern":"Underlying SQL state: (.+?), underlying error code: (.+?)\\.","errorType":"exception","errorClass":"SQLWrapperException","httpStatus":null,"severity":"error","filePath":"mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/manager/rule/DatabaseRuleItemManager.java","lineNumber":65,"sourceCode":"     * Alter rule item.\n     *\n     * @param databaseRuleNodePath database rule node path\n     * @throws SQLWrapperException SQL wrapper exception\n     */\n    @SuppressWarnings({\"rawtypes\", \"unchecked\"})\n    public void alter(final DatabaseRuleNodePath databaseRuleNodePath) {\n        RuleItemConfigurationChangedProcessor processor = TypedSPILoader.getService(RuleItemConfigurationChangedProcessor.class,\n                new RuleChangedItemType(databaseRuleNodePath.getRuleType(), databaseRuleNodePath.getDatabaseRuleItem().getType()));\n        String yamlContent = metaDataPersistFacade.getVersionService().loadContent(new VersionNodePath(databaseRuleNodePath));\n        String databaseName = databaseRuleNodePath.getDatabase().getDatabaseName();\n        RuleConfiguration currentRuleConfig = processor.findRuleConfiguration(metaDataContexts.getMetaData().getDatabase(databaseName));\n        String itemName = databaseRuleNodePath.getDatabaseRuleItem().getName();\n        synchronized (this) {\n            processor.changeRuleItemConfiguration(itemName, currentRuleConfig, processor.swapRuleItemConfiguration(itemName, yamlContent));\n            try {\n                databaseRuleConfigManager.refresh(databaseName, currentRuleConfig);\n            } catch (final SQLException ex) {\n                throw new SQLWrapperException(ex);\n            }\n        }\n    }\n    \n    /**\n     * Drop rule item.\n     *\n     * @param databaseRuleNodePath database rule node path\n     * @throws SQLWrapperException SQL wrapper exception\n     */\n    @SuppressWarnings({\"rawtypes\", \"unchecked\"})\n    public void drop(final DatabaseRuleNodePath databaseRuleNodePath) {\n        String databaseName = databaseRuleNodePath.getDatabase().getDatabaseName();\n        Preconditions.checkState(metaDataContexts.getMetaData().containsDatabase(databaseName), \"No database '%s' exists.\", databaseName);\n        RuleItemConfigurationChangedProcessor processor = TypedSPILoader.getService(RuleItemConfigurationChangedProcessor.class,\n                new RuleChangedItemType(databaseRuleNodePath.getRuleType(), null == databaseRuleNodePath.getDatabaseRuleItem() ? null : databaseRuleNodePath.getDatabaseRuleItem().getType()));\n        RuleConfiguration currentRuleConfig = processor.findRuleConfiguration(metaDataContexts.getMetaData().getDatabase(databaseName));\n        String itemName = null == databaseRuleNodePath.getDatabaseRuleItem() ? null : databaseRuleNodePath.getDatabaseRuleItem().getName();","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/manager/rule/DatabaseRuleItemManager.java#L47-L83","documentation":"Thrown by DatabaseRuleItemManager.alter when refreshing the in-memory database after a rule item change (processor.swapRuleItemConfiguration + changeRuleItemConfiguration followed by databaseRuleConfigManager.refresh) raises a SQLException. The SQLWrapperException preserves the underlying SQLState and vendor error code (reported as HY000 at the generic layer); the original SQLException is the cause.","triggerScenarios":"A governance-node update to a single rule item (e.g. one sharding algorithm or encryptor entry) where re-refreshing the rule configuration executes SQL against storage nodes that fails — bad storage unit config, dropped backend table, connection failure during refresh, or invalid generated SQL from the new rule config.","commonSituations":"Altering a rule whose new configuration references a nonexistent storage unit or algorithm, a backend database that became unreachable between plan and apply, or a dialect incompatibility where refresh-time SQL (e.g. metadata reload) is invalid on the storage engine.","solutions":["Inspect the wrapped cause (SQLException) — its SQLState and vendor error code, named in this exception's message, identify the real failure; fix that (restore connectivity, correct the rule config, repair referenced objects).","Validate the new rule item configuration against the actual storage nodes before persisting it to the governance node.","Revert or correct the rule item change and let the node watcher re-run alter so metadata converges to a consistent state."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    databaseRuleItemManager.alter(path);\n} catch (final SQLWrapperException ex) {\n    SQLException cause = (SQLException) ex.getCause();\n    // log cause.getSQLState() + cause.getErrorCode(); fix the storage-side problem it names\n}","preventionTips":["Dry-run rule changes against live storage before persisting to governance","Keep backend datasources reachable during rule change windows","Monitor refresh failures so persisted vs in-memory drift is caught early"],"tags":["governance","rule-configuration","metadata-refresh","sql"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}