{"record":{"id":"46979e7f211970d9","repo":"alibaba/canal","slug":"apply-history-to-db-failed-caused-by-errormessa","errorCode":null,"errorMessage":"apply history to db failed caused by : {errorMessage}","messagePattern":"apply history to db failed caused by : (.+?)","errorType":"exception","errorClass":"CanalParseException","httpStatus":null,"severity":"error","filePath":"parse/src/main/java/com/alibaba/otter/canal/parse/inbound/mysql/tsdb/DatabaseTableMeta.java","lineNumber":445,"sourceCode":"        if (ddlResults.size() > 0) {\n            DdlResult ddlResult = ddlResults.get(0);\n            metaDO.setSqlSchema(ddlResult.getSchemaName());\n            metaDO.setSqlTable(ddlResult.getTableName());\n            metaDO.setSqlType(ddlResult.getType().name());\n            metaDO.setSqlText(ddl);\n            metaDO.setExtra(extra);\n        }\n        try {\n            // 会建立唯一约束,解决:\n            // 1. 重复的binlog file+offest\n            // 2. 重复的masterId+timestamp\n            metaHistoryDAO.insert(metaDO);\n        } catch (Throwable e) {\n            if (isUkDuplicateException(e)) {\n                // 忽略掉重复的位点\n                logger.warn(\"dup apply for sql : \" + ddl);\n            } else {\n                throw new CanalParseException(\"apply history to db failed caused by : \" + e.getMessage(), e);\n            }\n\n        }\n        return true;\n    }\n\n    /**\n     * 发布数据到console上\n     */\n    private boolean applySnapshotToDB(EntryPosition position, boolean init) {\n        // 获取一份快照\n        Map<String, String> schemaDdls = null;\n        lock.readLock().lock();\n        try {\n            if (!init && !hasNewDdl) {\n                // 如果是持续构建,则识别一下是否有DDL变更过,如果没有就忽略了\n                return false;\n            }","sourceCodeStart":427,"sourceCodeEnd":463,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/parse/src/main/java/com/alibaba/otter/canal/parse/inbound/mysql/tsdb/DatabaseTableMeta.java#L427-L463","documentation":"Thrown as CanalParseException by DatabaseTableMeta.applyHistoryToDB() when inserting a MetaHistoryDO record into the database fails with a non-duplicate-key exception. Duplicate key exceptions are silently ignored (idempotent replay), but all other DB exceptions propagate here.","triggerScenarios":"metaHistoryDAO.insert() throws a non-UK-duplicate exception: connection failure, table doesn't exist, column type mismatch, data too long for a column, database is read-only, or deadlocks that aren't classified as UK violations.","commonSituations":"TSDB database (MySQL) is unreachable or credentials changed; the canal_tsdb table schema is out of date after a canal upgrade; the DDL text is too long for the sql_text column; database connection pool exhausted; the TSDB MySQL was restarted mid-operation.","solutions":["Check the cause exception (e) for the specific database error — getMessage() contains the DB error message.","Verify the TSDB database connection is valid and the canal user has INSERT permission on the meta_history table.","If 'Data too long', increase the column size for the sql_text or extra fields in the TSDB schema.","If 'Table doesn't exist', run the canal TSDB DDL migration scripts.","If connection issues, check datasource configuration and database availability."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    tableMeta.apply(position, schema, ddl, extra);\n} catch (CanalParseException e) {\n    if (e.getMessage().contains(\"apply history to db failed\")) {\n        Throwable dbCause = e.getCause();\n        // handle DB-specific failure (connection, schema, etc.)\n    }\n}","preventionTips":["Keep the TSDB database schema up to date with canal migration scripts.","Monitor TSDB database connectivity and connection pool health.","Ensure the sql_text and extra columns can accommodate large DDL statements (use TEXT or LONGTEXT)."],"tags":["tsdb","ddl","database","dao","canal-parse"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}