|
| 1 | +- name: mysql-source-prereq |
| 2 | + content: | |
| 3 | + To create a source from MySQL 5.7+, you must first: |
| 4 | +
|
| 5 | + - **Configure upstream MySQL instance** |
| 6 | + - Enable GTID-based binlog replication |
| 7 | + - Create a replication user and password for Materialize to use to connect. |
| 8 | + - **Configure network security** |
| 9 | + - Ensure Materialize can connect to your MySQL instance. |
| 10 | + - **Create a connection to MySQL in Materialize** |
| 11 | + - The connection setup depends on the network security configuration. |
| 12 | +
|
| 13 | + For details, see the [MySQL integration |
| 14 | + guides](/ingest-data/mysql/#integration-guides). |
| 15 | +
|
| 16 | +- name: mysql-supported-types |
| 17 | + content: | |
| 18 | + Materialize natively supports the following MySQL types: |
| 19 | +
|
| 20 | + <ul style="column-count: 3"> |
| 21 | + <li><code>bigint</code></li> |
| 22 | + <li><code>binary</code></li> |
| 23 | + <li><code>bit</code></li> |
| 24 | + <li><code>blob</code></li> |
| 25 | + <li><code>boolean</code></li> |
| 26 | + <li><code>char</code></li> |
| 27 | + <li><code>date</code></li> |
| 28 | + <li><code>datetime</code></li> |
| 29 | + <li><code>decimal</code></li> |
| 30 | + <li><code>double</code></li> |
| 31 | + <li><code>float</code></li> |
| 32 | + <li><code>int</code></li> |
| 33 | + <li><code>json</code></li> |
| 34 | + <li><code>longblob</code></li> |
| 35 | + <li><code>longtext</code></li> |
| 36 | + <li><code>mediumblob</code></li> |
| 37 | + <li><code>mediumint</code></li> |
| 38 | + <li><code>mediumtext</code></li> |
| 39 | + <li><code>numeric</code></li> |
| 40 | + <li><code>real</code></li> |
| 41 | + <li><code>smallint</code></li> |
| 42 | + <li><code>text</code></li> |
| 43 | + <li><code>time</code></li> |
| 44 | + <li><code>timestamp</code></li> |
| 45 | + <li><code>tinyblob</code></li> |
| 46 | + <li><code>tinyint</code></li> |
| 47 | + <li><code>tinytext</code></li> |
| 48 | + <li><code>varbinary</code></li> |
| 49 | + <li><code>varchar</code></li> |
| 50 | + </ul> |
| 51 | +
|
| 52 | +- name: mysql-unsupported-types |
| 53 | + content: | |
| 54 | + When replicating tables that contain the **unsupported [data |
| 55 | + types](/sql/types/)**, you can: |
| 56 | +
|
| 57 | + - Use [`TEXT COLUMNS` |
| 58 | + option](/sql/create-source/mysql/#handling-unsupported-types) for the |
| 59 | + following unsupported MySQL types: |
| 60 | +
|
| 61 | + - `enum` |
| 62 | + - `year` |
| 63 | +
|
| 64 | + The specified columns will be treated as `text` and will not offer the |
| 65 | + expected MySQL type features. |
| 66 | +
|
| 67 | + - Use the [`EXCLUDE COLUMNS`](/sql/create-source/mysql/#excluding-columns) |
| 68 | + option to exclude any columns that contain unsupported data types. |
| 69 | +
|
| 70 | +- name: mysql-truncation-restriction |
| 71 | + content: | |
| 72 | + Avoid truncating upstream tables that are being replicated into Materialize. |
| 73 | + If a replicated upstream table is truncated, the corresponding |
| 74 | + subsource in Materialize becomes inaccessible and will not |
| 75 | + produce any data until it is recreated. |
| 76 | +
|
| 77 | + Instead of truncating, use an unqualified `DELETE` to remove all rows from |
| 78 | + the upstream table: |
| 79 | +
|
| 80 | + ```mzsql |
| 81 | + DELETE FROM t; |
| 82 | + ``` |
| 83 | +
|
| 84 | +- name: mysql-compatible-schema-changes-legacy |
| 85 | + content: | |
| 86 | +
|
| 87 | + - Adding columns to tables. Materialize will **not ingest** new columns |
| 88 | + added upstream unless you use [`DROP SOURCE`](/sql/alter-source/#context) to |
| 89 | + first drop the affected subsource, and then add the table back to the source |
| 90 | + using [`ALTER SOURCE...ADD SUBSOURCE`](/sql/alter-source/). |
| 91 | +
|
| 92 | + - Dropping columns that were added after the source was created. These |
| 93 | + columns are never ingested, so you can drop them without issue. |
| 94 | +
|
| 95 | + - Adding or removing `NOT NULL` constraints to tables that were nullable |
| 96 | + when the source was created. |
| 97 | +
|
| 98 | +- name: mysql-incompatible-schema-changes-legacy |
| 99 | + content: | |
| 100 | + All other schema changes to upstream tables will set the corresponding |
| 101 | + subsource into an error state, which prevents you from reading from the |
| 102 | + subsource. |
| 103 | +
|
| 104 | + To handle incompatible [schema changes](#schema-changes), use [`DROP |
| 105 | + SOURCE`](/sql/alter-source/#context) to first drop the affected subsource, |
| 106 | + and then [`ALTER SOURCE...ADD SUBSOURCE`](/sql/alter-source/) to add the |
| 107 | + subsource back to the source. When you add the subsource, it will have the |
| 108 | + updated schema from the corresponding upstream table. |
| 109 | +
|
| 110 | +- name: mysql-considerations |
| 111 | + content: | |
| 112 | + ### Schema changes |
| 113 | +
|
| 114 | + {{< include-md file="shared-content/schema-changes-in-progress.md" >}} |
| 115 | +
|
| 116 | + Materialize supports schema changes in the upstream database as follows: |
| 117 | +
|
| 118 | + #### Compatible schema changes |
| 119 | +
|
| 120 | + {{% include-from-yaml data="mysql_source_details" |
| 121 | + name="mysql-compatible-schema-changes-legacy" %}} |
| 122 | +
|
| 123 | + #### Incompatible schema changes |
| 124 | +
|
| 125 | + {{% include-from-yaml data="mysql_source_details" |
| 126 | + name="mysql-incompatible-schema-changes-legacy" %}} |
| 127 | +
|
| 128 | + ### Supported types |
| 129 | +
|
| 130 | + {{% include-from-yaml data="mysql_source_details" |
| 131 | + name="mysql-supported-types" %}} |
| 132 | +
|
| 133 | + {{% include-from-yaml data="mysql_source_details" |
| 134 | + name="mysql-unsupported-types" %}} |
| 135 | +
|
| 136 | + ### Truncation |
| 137 | +
|
| 138 | + {{% include-from-yaml data="mysql_source_details" |
| 139 | + name="mysql-truncation-restriction" %}} |
| 140 | +
|
| 141 | + ### Modifying an existing source |
| 142 | +
|
| 143 | + {{< include-md |
| 144 | + file="shared-content/alter-source-snapshot-blocking-behavior.md" >}} |
0 commit comments