ClickHouse/docs/en/engines/database-engines/materialize-mysql.md

toc_priority	toc_title
29	MaterializeMySQL

MaterializeMySQL

Creates ClickHouse database with all the tables existing in MySQL, and all the data in those tables.

ClickHouse server works as MySQL replica. It reads binlog and performs DDL and DML queries.

This feature is experimental.

Creating a Database

CREATE DATABASE [IF NOT EXISTS] db_name [ON CLUSTER cluster]
ENGINE = MaterializeMySQL('host:port', ['database' | database], 'user', 'password') [SETTINGS ...]

Engine Parameters

• host:port — MySQL server endpoint.
• database — MySQL database name.
• user — MySQL user.
• password — User password.

Virtual columns

When working with the MaterializeMySQL database engine, ReplacingMergeTree tables are used with virtual _sign and _version columns.

• _version — Transaction counter. Type UInt64.
• _sign — Deletion mark. Type Int8. Possible values:
  • 1 — Row is not deleted,
  • -1 — Row is deleted.

Data Types Support

MySQL	ClickHouse
TINY	Int8
SHORT	Int16
INT24	Int32
LONG	UInt32
LONGLONG	UInt64
FLOAT	Float32
DOUBLE	Float64
DECIMAL, NEWDECIMAL	Decimal
DATE, NEWDATE	Date
DATETIME, TIMESTAMP	DateTime
DATETIME2, TIMESTAMP2	DateTime64
ENUM	Enum
STRING	String
VARCHAR, VAR_STRING	String
BLOB	String

Other types are not supported. If MySQL table contains a column of such type, ClickHouse throws exception "Unhandled data type" and stops replication.

Nullable is supported.

Specifics and Recommendations

DDL Queries

MySQL DDL queries are converted into the corresponding ClickHouse DDL queries (ALTER, CREATE, DROP, RENAME). If ClickHouse cannot parse some DDL query, the query is ignored.

Data Replication

MaterializeMySQL does not support direct INSERT, DELETE and UPDATE queries. However, they are supported in terms of data replication:

• MySQL INSERT query is converted into INSERT with _sign=1.

• MySQL DELETE query is converted into INSERT with _sign=-1.

• MySQL UPDATE query is converted into INSERT with _sign=-1 and INSERT with _sign=1.

Selecting from MaterializeMySQL Tables

SELECT query from MaterializeMySQL tables has some specifics:

• If _version is not specified in the SELECT query, FINAL modifier is used. So only rows with MAX(_version) are selected.

• If _sign is not specified in the SELECT query, WHERE _sign=1 is used by default. So the deleted rows are not included into the result set.

Index Conversion

MySQL PRIMARY KEY and INDEX clauses are converted into ORDER BY tuples in ClickHouse tables.

ClickHouse has only one physical order, which is determined by ORDER BY clause. To create a new physical order, use materialized views.

Notes

• Rows with _sign=-1 are not deleted physically from the tables.
• Cascade UPDATE/DELETE queries are not supported by the MaterializeMySQL engine.
• Replication can be easily broken.
• Manual operations on database and tables are forbidden.
• MaterializeMySQL is influenced by optimize_on_insert setting. The data is merged in the corresponding table in the MaterializeMySQL database when a table in the MySQL server changes.

Examples of Use

Queries in MySQL:

mysql> CREATE DATABASE db;
mysql> CREATE TABLE db.test (a INT PRIMARY KEY, b INT);
mysql> INSERT INTO db.test VALUES (1, 11), (2, 22);
mysql> DELETE FROM db.test WHERE a=1;
mysql> ALTER TABLE db.test ADD COLUMN c VARCHAR(16);
mysql> UPDATE db.test SET c='Wow!', b=222;
mysql> SELECT * FROM test;

+---+------+------+ 
| a |    b |    c |
+---+------+------+ 
| 2 |  222 | Wow! |
+---+------+------+

Database in ClickHouse, exchanging data with the MySQL server:

The database and the table created:

CREATE DATABASE mysql ENGINE = MaterializeMySQL('localhost:3306', 'db', 'user', '***');
SHOW TABLES FROM mysql;

┌─name─┐
│ test │
└──────┘

After inserting data:

SELECT * FROM mysql.test;

┌─a─┬──b─┐ 
│ 1 │ 11 │ 
│ 2 │ 22 │ 
└───┴────┘

After deleting data, adding the column and updating:

SELECT * FROM mysql.test;

┌─a─┬───b─┬─c────┐ 
│ 2 │ 222 │ Wow! │ 
└───┴─────┴──────┘

Original article