Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add some documentation for supported MySQL replication modes #1906

Merged
merged 1 commit into from
Dec 31, 2024
+9 −1
Merged

Add some documentation for supported MySQL replication modes #1906

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion content/en/docs/22.0/reference/features/mysql-replication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,17 @@ These requirements will changed based on the durability policy.

With regard to replication lag, note that this does **not** guarantee there is always at least one replica from which queries will always return up-to-date results. Semi-sync guarantees that at least one replica has the transaction in its relay log, but it has not necessarily been applied yet. The only way Vitess guarantees a fully up-to-date read is to send the request to the primary.

## MySQL Replication Modes

Vitess requires the use of [Row-Based Replication (RBR)](https://dev.mysql.com/doc/refman/en/replication-formats.html) with [GTIDs](https://dev.mysql.com/doc/refman/en/replication-gtids.html) enabled: [`--binlog-row-format=ROW`](https://dev.mysql.com/doc/refman/en/replication-options-binary-log.html#sysvar_binlog_format) and [`--gtid-mode=ON`](https://dev.mysql.com/doc/refman/en/replication-options-gtids.html#sysvar_gtid_mode).

Vitess also recommends [`FULL`](https://dev.mysql.com/doc/refman/en/replication-options-binary-log.html#sysvar_binlog_row_image) binary log images in order to support all manner of transformations in [VReplication workflows](../../vreplication/vreplication/), but in v17 we added *experimental* support for [`--binlog-row-image=NOBLOB`](https://dev.mysql.com/doc/refman/en/replication-options-binary-log.html#sysvar_binlog_row_image) (see [#1290](https://github.com/vitessio/vitess/pull/12905) for more details).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would it take to move NOBLOB out of "experimental"? I'm curious why this was done as experimental whereas we seem to be more confident about our ability to support PARTIAL_JSON.

Copy link
Collaborator Author

@mattlord mattlord Dec 31, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We expect and know that some things will fail with NOBLOB, because we lose information in the binary log events. There's no before OR after image value for the BLOB/TEXT columns when not updated in the row, which means we lose information and we know that some OnlineDDL and Materialize workflows will fail because we lack information to perform accurate transformations. We also know e.g. that changing the PK definitions on a table on the target will cause MoveTables workflows to fail if you update the PK column values in the table. That's what this is about: https://github.com/vitessio/vitess/pull/17345/files#r1892674955

With PARTIAL_JSON nothing should fail. That's because we don't lose information: there's always the BEFORE image value along with a diff in the AFTER image that can be applied to that before value in order to get the full after value.


Vitess v22 and later fully supports the usage of [`--binlog-row-value-options=PARTIAL_JSON`](https://dev.mysql.com/doc/refman/en/replication-options-binary-log.html#sysvar_binlog_row_value_options) with MySQL 8.0 and later.

## Database Schema Considerations

* Row-based replication requires that replicas have the same schema as the primary, and corruption will likely occur if the column order does not match. Earlier versions of Vitess which used Statement-Based replication recommended applying schema changes on replicas first, and then swapping their role to primary. This method is no longer recommended in favour of the use of Online-DDL. More information can be found [here](../../../user-guides/schema-changes).
* Row-based replication requires that replicas have the same schema as the primary, and corruption will likely occur if the column order does not match.

* Using a column of type `FLOAT` or `DOUBLE` as part of a Primary Key is not supported. This limitation is because Vitess may try to execute a query for a value (for example 2.2) which MySQL will return zero results, even when the approximate value is present.

Expand Down