{"record":{"id":"4c77a5da7ec89e37","repo":"apache/dolphinscheduler","slug":"upgrade-version-error-sql","errorCode":null,"errorMessage":"Upgrade version error, sql: ","messagePattern":"Upgrade version error, sql: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/UpgradeDao.java","lineNumber":170,"sourceCode":"     *\n     * @param version version\n     */\n    public void updateVersion(String version) {\n        // Change version in the version table to the new version\n        String versionName = T_VERSION_NAME;\n        if (!SchemaUtils.isAGreatVersion(\"1.2.0\", version)) {\n            versionName = \"t_ds_version\";\n        }\n        String upgradeSQL = String.format(\"update %s set version = ?\", versionName);\n        try (\n                Connection conn = dataSource.getConnection();\n                PreparedStatement pstmt = conn.prepareStatement(upgradeSQL)) {\n            pstmt.setString(1, version);\n            pstmt.executeUpdate();\n\n        } catch (SQLException e) {\n            log.error(\"Update version error, sql: {}\", upgradeSQL, e);\n            throw new RuntimeException(\"Upgrade version error, sql: \" + upgradeSQL, e);\n        }\n    }\n}\n","sourceCodeStart":152,"sourceCodeEnd":174,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/upgrader/UpgradeDao.java#L152-L174","documentation":"UpgradeDao.updateVersion executes 'update <t_ds_version> set version = ?' to stamp the new schema version. A SQLException is rethrown as RuntimeException 'Upgrade version error, sql: <sql>'. The DDL/DML upgrades succeeded but recording the new version failed, leaving the recorded version stale.","triggerScenarios":"Calling updateVersion when the UPDATE throws SQLException: missing UPDATE privilege on t_ds_version, connection dropped during the upgrade, the version table exists but the version row is missing/locked, or read-only replica connection.","commonSituations":"Upgrade run with a read-only or low-privilege DB account; connection timeouts during long upgrades; version table empty (no row to update); DB in read-only/replica mode.","solutions":["Grant UPDATE on t_ds_version to the upgrade DB user, then re-run the version update.","Verify a row exists in t_ds_version; insert one with the current version if the table is empty.","Check DB connectivity/timeouts and re-run the upgrade (DDL/DML are typically idempotent-guarded by version checks).","Ensure you are not connected to a read-only replica; point at the primary database."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-check: version table has an updatable row and user has UPDATE privilege\ntry (Statement s = conn.createStatement();\n     ResultSet rs = s.executeQuery(\"select count(*) from t_ds_version\")) {\n    rs.next();\n    if (rs.getInt(1) == 0) throw new IllegalStateException(\"t_ds_version is empty; insert current version row first\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    manager.upgradeDolphinScheduler();\n} catch (RuntimeException e) {\n    if (e.getMessage().startsWith(\"Upgrade version error\")) {\n        log.error(\"Version stamp update failed (privileges/readonly DB): {}\",\n                e.getCause() != null ? e.getCause().getMessage() : null, e);\n        // fix privileges, then manually: UPDATE t_ds_version SET version='<new>';\n    } else throw e;\n}","preventionTips":["Run upgrades with an account holding UPDATE on t_ds_version.","Never run upgrades against read-only replicas.","Ensure t_ds_version contains a version row before upgrading.","After an upgrade, verify SELECT version FROM t_ds_version matches the target version."],"tags":["database","upgrade","version"],"backgroundTag":"database-write-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}