alibaba/canal: turning the MySQL binlog into a subscribable change stream

The problem canal solves, and who actually has it

The README opens with the origin story: Alibaba ran dual data centres in Hangzhou and the United States and needed to move changes between them. The first approach used database triggers to capture incremental changes. From 2010 the teams moved to parsing the database log instead, and that work turned into canal. The listed use cases are database mirroring, real-time backup, index construction and maintenance (split or heterogeneous indexes, inverted indexes), cache refresh, and incremental processing that carries business logic.

So the audience is narrow and specific. You have a MySQL primary, you want downstream systems to react to row-level changes, and you do not want to poll tables or bolt triggers onto the schema. Canal is aimed at the team that owns that MySQL instance and is willing to run another piece of infrastructure next to it. If you only need a nightly copy of a table, canal is more machinery than the job requires.

Impersonating a replica: the actual mechanism

Canal does not read tables. It reads the log the primary already writes for its own replicas.

MySQL replication works in three steps, as the README describes them. The master writes data changes into the binary log, where each record is a binary log event, visible through show binlog events. A slave copies those events into its relay log. The slave then replays the relay log to apply the changes to its own data.

Canal inserts itself at step two. It speaks the slave interaction protocol, presents itself as a MySQL slave, and sends a dump request to the master. The master accepts the request and starts pushing binary log events to it, exactly as it would to a real replica. Canal then parses the binary log object, which arrives as a raw byte stream, into structured change records.

That design has a consequence worth stating plainly: canal consumes the replication stream, so it inherits the same constraints as a real replica. The source must have binary logging enabled, and the account canal uses needs the replication privileges that the dump handshake implies. The supported source versions are listed as MySQL 5.1.x, 5.5.x, 5.6.x, 5.7.x and 8.0.x.

Client-server over protobuf, and why the language list is long

Canal is split into a server and clients. The interaction protocol uses protobuf 3.0, and the README states that clients can be written in different languages to implement different consumption logic. The repository links Java, C#, Go, PHP, Python, Rust and Node.js clients. Only the Java client is hosted under the alibaba/canal wiki; the rest are third-party repositories, which means their maintenance is not canal's maintenance.

The alternative path avoids writing a client at all. Canal can deliver change records into a message queue, Kafka or RocketMQ, and the README points out that this lets you use the MQ's own multi-language support instead of the protobuf protocol. For most teams this is the more sensible integration: your consumers become ordinary queue consumers, and canal's job shrinks to producing well-formed events.

Both paths are documented in the wiki rather than in the README, so the README gives you the shape of the system and the wiki gives you the wiring.

Getting it running: what the material actually specifies

The README does not contain a command sequence. It points to a QuickStart wiki page and to several variants: Docker QuickStart, Canal Kafka/RocketMQ QuickStart, Aliyun RDS for MySQL QuickStart, and Prometheus QuickStart. Docker images are listed as a 1.1.x feature, referencing issue #801.

The only concrete operational facts the README supplies are these. Supported source versions are MySQL 5.1.x through 8.0.x. The protocol is protobuf 3.0. Kafka and RocketMQ delivery are native in 1.1.x. Prometheus monitoring is native in 1.1.x. Aliyun RDS binlog subscription is native in 1.1.x, and the README says it addresses automatic primary/standby failover and offline parsing of OSS binlog. From 1.1.4 there is a separate canal-admin project providing a web UI for managing canal, including configuration, tasks and logs.

From the documentation, a working setup has at least three moving parts: the MySQL source with binary logging and a replication-capable account, the canal server, and either a client or a message queue. Canal-admin adds a fourth. Budget for that before you start, because the QuickStart pages assume you have already made those decisions.

The admin layer is a separate project, and that matters

Canal-admin arrived in 1.1.4 and is described as supporting web-based dynamic management of canal, with online configuration, task and log operations. It is a separate project in the admin/ directory, with its own QuickStart, Guide, ServerGuide and Docker pages in the wiki.

That is a reasonable split, but it changes the adoption cost. A single-node canal instance with a Java client is a small footprint. Adding the admin layer means another service to deploy, secure and upgrade, and it implies coordination state that the admin server manages on behalf of the instances. The README does not spell out that coordination mechanism, so anyone planning a multi-instance deployment should read the Canal Admin ServerGuide and Canal Admin Guide in the wiki before assuming the admin console is optional.

For a single team running one canal instance against one MySQL primary, the admin console is probably overhead. For an organisation with several instances and several destinations, it is the difference between editing files on hosts and editing configuration in one place.

Where canal is the wrong tool

The clearest limitation is stated by the project's own scope: the source is MySQL. The README lists MySQL 5.1.x through 8.0.x and links separate binlog-change pages for MySQL 5.6 and MariaDB, but the project is not a general database change-capture layer. If your primary is PostgreSQL, Oracle or a proprietary engine, canal is not the answer, and the README's related-projects section points at yugong for Oracle migration work rather than at canal.

The second limitation is operational. Canal is a replica. It needs binary logging, it needs replication privileges, and it sits in the same replication stream as your real replicas. A team that cannot change MySQL server settings or grant replication grants cannot run it. A team that treats its production MySQL as untouchable should look at a managed service instead.

The third is that the README's performance claim is a single number with no context: 1.1.x is described as improving overall performance by 150%, referencing issue #726 and a Performance wiki page. That figure depends entirely on the workload behind it. Treat it as evidence that the maintainers did optimisation work in that release, not as a number you can plan capacity against.

Finally, the README notes that issues filed on GitHub are mirrored into Alibaba Cloud's developer community. That is a support-channel detail, not a defect, but it means the discussion around a problem may not live entirely in the GitHub thread you are reading.

The alternative worth comparing: queue-native producers and managed CDC

Debezium is the obvious comparison, and the difference is architectural rather than cosmetic. Debezium is built around Kafka Connect: the connector runs inside a Connect cluster, and the output is Kafka topics by default. Canal is a standalone server that you point at MySQL, with Kafka and RocketMQ delivery as one of several output modes and a protobuf client protocol as another.

That distinction drives the operational shape. With Debezium you are already running Kafka Connect, and the connector is a plugin you configure through Connect's REST API. With canal you run a canal server, decide whether you also want canal-admin, and then either run a client or attach a queue. If your stack is Kafka-first, Connect is the smaller addition. If you want a non-Kafka consumer, or you want the same change stream readable by a Go or Rust service over protobuf without a broker in between, canal's design is the more direct fit.

A second alternative is to skip log parsing entirely and use triggers, which is what Alibaba did before 2010. The README records that from 2010 the business gradually moved to log parsing instead. Triggers write into your schema and add work to the transaction path; canal reads a log the server is already writing. That is the whole reason the project exists.

Licence, releases and the cost of staying current

Canal is Apache-2.0, which permits commercial use, modification and redistribution under the terms of that licence. That is a permissive licence and it is the same one used by many data-infrastructure projects. This is a description of the licence identifier, not legal advice; if the licence terms matter to your organisation's policy, read the text and talk to whoever handles that.

The release cadence visible in the release history is uneven. 1.1.8-alpha-2 landed in May 2024, 1.1.8-alpha-3 in September 2024, and the 1.1.8 release in January 2025. Before that, the README's own version notes concentrate on the 1.1.x line and on 1.1.4, which introduced canal-admin. That means a team adopting canal today is adopting a project whose feature work is grouped into large releases with long alpha phases, not one that ships small increments continuously.

Upgrade cost is the part the README does not address. There is a ReleaseNotes link and a releases page, and that is where you would look for breaking changes between the version you run and the version you want. Because canal sits between MySQL and your downstream consumers, an upgrade touches the protocol boundary and the MQ delivery format at once. Pin a version, read the release notes for every version between your current one and the target, and test the consumer side before the server side. The last push to the repository is dated 2026-07-30, so the project is active, but activity is not the same as a documented upgrade path.

Editorial conclusion

Adopt canal if you already run MySQL and want change events in Kafka or RocketMQ without buying a managed CDC service, and if you are willing to operate the server, canal-admin if you use it, and the destination MQ yourself. Do not adopt it if you need a fully managed connector, if your source is not MySQL or a compatible fork, or if you cannot grant the replication access the dump handshake requires. Before committing, verify three things against your own cluster: that your MySQL version and topology are covered by the supported list, that binary logging is enabled on the source, and that the specific canal release you install is the one whose release notes you have read.

Frequently asked questions

Official sources

1. alibaba/canal on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases