sql: change IGNORE COLUMNS MySQL option to EXCLUDE COLUMNS

doc/user/content/sql/create-source/mysql.md

@@ -50,7 +50,7 @@ _src_name_  | The name for the source.
 
 Field                                | Value                           | Description
 -------------------------------------|---------------------------------|-------------------------------------
-`IGNORE COLUMNS`                     | A list of fully-qualified names | Ignore specific columns that cannot be decoded or should not be included in the subsources created in Materialize.
+{{< if-unreleased "v0.117" >}}`IGNORE COLUMNS`{{< /if-unreleased >}} {{< if-released "v0.117" >}}`EXCLUDE COLUMNS`{{< /if-released >}} | A list of fully-qualified names | Exclude specific columns that cannot be decoded or should not be included in the subsources created in Materialize.
 `TEXT COLUMNS`                       | A list of fully-qualified names | Decode data as `text` for specific columns that contain MySQL types that are [unsupported in Materialize](#supported-types).
 
 ## Features
@@ -256,9 +256,17 @@ following types:
 <li><code>year</code></li>
 </ul>
 
+{{< if-unreleased "v0.117" >}}
 The specified columns will be treated as `text`, and will thus not offer the
 expected MySQL type features. For any unsupported data types not listed above,
 use the [`IGNORE COLUMNS`](#ignoring-columns) option.
+{{< /if-unreleased >}}
+
+{{< if-released "v0.117" >}}
+The specified columns will be treated as `text`, and will thus not offer the
+expected MySQL type features. For any unsupported data types not listed above,
+use the [`EXCLUDE COLUMNS`](#excluding-columns) option.
+{{< /if-released >}}
 
 ##### Truncation
 
@@ -372,6 +380,7 @@ CREATE SOURCE mz_source
   FOR ALL TABLES;
 ```
 
+{{< if-unreleased "v0.117" >}}
 #### Ignoring columns
 
 MySQL doesn't provide a way to filter out columns from the replication stream.
@@ -385,6 +394,23 @@ CREATE SOURCE mz_source
   )
   FOR ALL TABLES;
 ```
+{{< /if-unreleased >}}
+
+{{< if-released "v0.117" >}}
+#### Excluding columns
+
+MySQL doesn't provide a way to filter out columns from the replication stream.
+To exclude specific upstream columns from being ingested, use the `EXCLUDE
+COLUMNS` option.
+
+```mzsql
+CREATE SOURCE mz_source
+  FROM MYSQL CONNECTION mysql_connection (
+    EXCLUDE COLUMNS (mydb.table_1.column_to_ignore)
+  )
+  FOR ALL TABLES;
+```
+{{< /if-released >}}
 
 ### Handling errors and schema changes
 

doc/user/sql-grammar/sql-grammar.bnf

@@ -232,6 +232,7 @@ create_source_mysql ::=
   'FROM' 'MYSQL' 'CONNECTION' connection_name
   ( ( '(' 'TEXT COLUMNS' ('(' (column_name) ( ( ',' column_name ) )* ')')? )? )
       ( ( ',' 'IGNORE COLUMNS' ('(' (column_name) ( ( ',' column_name ) )* ')')? ')' )? )
+      ( ( ',' 'EXCLUDE COLUMNS' ('(' (column_name) ( ( ',' column_name ) )* ')')? ')' )? )
   ('FOR ALL TABLES'
     | 'FOR TABLES' '(' table_name ('AS' subsrc_name)?  (',' table_name ('AS' subsrc_name)? )* ')'
     | 'FOR SCHEMAS' '(' schema_name (',' schema_name )* ')'

src/adapter/src/coord/sequencer/inner.rs

@@ -3631,7 +3631,7 @@ impl Coordinator {
 
                 let mz_sql::plan::AlterSourceAddSubsourceOptionExtracted {
                     text_columns: mut new_text_columns,
-                    ignore_columns: mut new_ignore_columns,
+                    exclude_columns: mut new_exclude_columns,
                     ..
                 } = options.try_into()?;
 
@@ -3709,7 +3709,7 @@ impl Coordinator {
                     } => {
                         let mz_sql::plan::MySqlConfigOptionExtracted {
                             mut text_columns,
-                            mut ignore_columns,
+                            mut exclude_columns,
                             ..
                         } = curr_options.clone().try_into()?;
 
@@ -3719,28 +3719,28 @@ impl Coordinator {
                             !matches!(
                                 o.name,
                                 MySqlConfigOptionName::TextColumns
-                                    | MySqlConfigOptionName::IgnoreColumns
+                                    | MySqlConfigOptionName::ExcludeColumns
                             )
                         });
 
-                        // Drop all text / ignore columns that are not currently referred to.
+                        // Drop all text / exclude columns that are not currently referred to.
                         let column_referenced =
                             |column_qualified_reference: &UnresolvedItemName| {
                                 mz_ore::soft_assert_eq_or_log!(
                                 column_qualified_reference.0.len(),
                                 3,
-                                "all TEXT COLUMNS & IGNORE COLUMNS values must be column-qualified references"
+                                "all TEXT COLUMNS & EXCLUDE COLUMNS values must be column-qualified references"
                             );
                                 let mut table = column_qualified_reference.clone();
                                 table.0.truncate(2);
                                 curr_references.contains(&table)
                             };
                         text_columns.retain(column_referenced);
-                        ignore_columns.retain(column_referenced);
+                        exclude_columns.retain(column_referenced);
 
-                        // Merge the current text / ignore columns into the new text / ignore columns.
+                        // Merge the current text / exclude columns into the new text / exclude columns.
                         new_text_columns.extend(text_columns);
-                        new_ignore_columns.extend(ignore_columns);
+                        new_exclude_columns.extend(exclude_columns);
 
                         // If we have text columns, add them to the options.
                         if !new_text_columns.is_empty() {
@@ -3755,17 +3755,17 @@ impl Coordinator {
                                 value: Some(WithOptionValue::Sequence(new_text_columns)),
                             });
                         }
-                        // If we have ignore columns, add them to the options.
-                        if !new_ignore_columns.is_empty() {
-                            new_ignore_columns.sort();
-                            let new_ignore_columns = new_ignore_columns
+                        // If we have exclude columns, add them to the options.
+                        if !new_exclude_columns.is_empty() {
+                            new_exclude_columns.sort();
+                            let new_exclude_columns = new_exclude_columns
                                 .into_iter()
                                 .map(WithOptionValue::UnresolvedItemName)
                                 .collect();
 
                             curr_options.push(MySqlConfigOption {
-                                name: MySqlConfigOptionName::IgnoreColumns,
-                                value: Some(WithOptionValue::Sequence(new_ignore_columns)),
+                                name: MySqlConfigOptionName::ExcludeColumns,
+                                value: Some(WithOptionValue::Sequence(new_exclude_columns)),
                             });
                         }
                     }

src/mysql-util/src/schemas.rs

@@ -90,14 +90,14 @@ impl MySqlTableSchema {
     }
 
     /// Convert the raw table schema to our MySqlTableDesc representation
-    /// using any provided text_columns and ignore_columns
+    /// using any provided text_columns and exclude_columns
     pub fn to_desc(
         self,
         text_columns: Option<&BTreeSet<&str>>,
-        ignore_columns: Option<&BTreeSet<&str>>,
+        exclude_columns: Option<&BTreeSet<&str>>,
     ) -> Result<MySqlTableDesc, MySqlError> {
-        // Verify there are no duplicates in text_columns and ignore_columns
-        match (&text_columns, &ignore_columns) {
+        // Verify there are no duplicates in text_columns and exclude_columns
+        match (&text_columns, &exclude_columns) {
             (Some(text_cols), Some(ignore_cols)) => {
                 let intersection: Vec<_> = text_cols.intersection(ignore_cols).collect();
                 if !intersection.is_empty() {
@@ -133,7 +133,7 @@ impl MySqlTableSchema {
             }
 
             // If this column is ignored, use None for the column type to signal that it should be.
-            if let Some(ignore_cols) = &ignore_columns {
+            if let Some(ignore_cols) = &exclude_columns {
                 if ignore_cols.contains(&info.column_name.as_str()) {
                     columns.push(MySqlColumnDesc {
                         name: info.column_name,

src/sql-lexer/src/keywords.txt

@@ -150,6 +150,7 @@ Escape
 Estimate
 Every
 Except
+Exclude
 Execute
 Exists
 Expected

src/sql-parser/src/ast/defs/ddl.rs

@@ -1092,21 +1092,21 @@ pub enum MySqlConfigOptionName {
     /// fully deprecating that feature and forcing users to use explicit
     /// `CREATE TABLE .. FROM SOURCE` statements
     TextColumns,
-    /// Columns you want to ignore
+    /// Columns you want to exclude
     /// NOTE(roshan): This value is kept around to allow round-tripping a
     /// `CREATE SOURCE` statement while we still allow creating implicit
     /// subsources from `CREATE SOURCE`, but will be removed once
     /// fully deprecating that feature and forcing users to use explicit
     /// `CREATE TABLE .. FROM SOURCE` statements
-    IgnoreColumns,
+    ExcludeColumns,
 }
 
 impl AstDisplay for MySqlConfigOptionName {
     fn fmt<W: fmt::Write>(&self, f: &mut AstFormatter<W>) {
         f.write_str(match self {
             MySqlConfigOptionName::Details => "DETAILS",
             MySqlConfigOptionName::TextColumns => "TEXT COLUMNS",
-            MySqlConfigOptionName::IgnoreColumns => "IGNORE COLUMNS",
+            MySqlConfigOptionName::ExcludeColumns => "EXCLUDE COLUMNS",
         })
     }
 }
@@ -1122,7 +1122,7 @@ impl WithOptionName for MySqlConfigOptionName {
         match self {
             MySqlConfigOptionName::Details
             | MySqlConfigOptionName::TextColumns
-            | MySqlConfigOptionName::IgnoreColumns => false,
+            | MySqlConfigOptionName::ExcludeColumns => false,
         }
     }
 }

src/sql-parser/src/ast/defs/statement.rs

@@ -1098,8 +1098,8 @@ pub enum CreateSubsourceOptionName {
     ExternalReference,
     /// Columns whose types you want to unconditionally format as text
     TextColumns,
-    /// Columns you want to ignore when ingesting data
-    IgnoreColumns,
+    /// Columns you want to exclude when ingesting data
+    ExcludeColumns,
     /// `DETAILS` for this subsource, hex-encoded protobuf type
     /// `mz_storage_types::sources::SourceExportStatementDetails`
     Details,
@@ -1111,7 +1111,7 @@ impl AstDisplay for CreateSubsourceOptionName {
             CreateSubsourceOptionName::Progress => "PROGRESS",
             CreateSubsourceOptionName::ExternalReference => "EXTERNAL REFERENCE",
             CreateSubsourceOptionName::TextColumns => "TEXT COLUMNS",
-            CreateSubsourceOptionName::IgnoreColumns => "IGNORE COLUMNS",
+            CreateSubsourceOptionName::ExcludeColumns => "EXCLUDE COLUMNS",
             CreateSubsourceOptionName::Details => "DETAILS",
         })
     }
@@ -1129,7 +1129,7 @@ impl WithOptionName for CreateSubsourceOptionName {
             | CreateSubsourceOptionName::ExternalReference
             | CreateSubsourceOptionName::Details
             | CreateSubsourceOptionName::TextColumns
-            | CreateSubsourceOptionName::IgnoreColumns => false,
+            | CreateSubsourceOptionName::ExcludeColumns => false,
         }
     }
 }
@@ -1510,8 +1510,8 @@ impl_display_for_with_option!(TableOption);
 pub enum TableFromSourceOptionName {
     /// Columns whose types you want to unconditionally format as text
     TextColumns,
-    /// Columns you want to ignore when ingesting data
-    IgnoreColumns,
+    /// Columns you want to exclude when ingesting data
+    ExcludeColumns,
     /// Hex-encoded protobuf of a `ProtoSourceExportStatementDetails`
     /// message, which includes details necessary for planning this
     /// table as a Source Export
@@ -1522,7 +1522,7 @@ impl AstDisplay for TableFromSourceOptionName {
     fn fmt<W: fmt::Write>(&self, f: &mut AstFormatter<W>) {
         f.write_str(match self {
             TableFromSourceOptionName::TextColumns => "TEXT COLUMNS",
-            TableFromSourceOptionName::IgnoreColumns => "IGNORE COLUMNS",
+            TableFromSourceOptionName::ExcludeColumns => "EXCLUDE COLUMNS",
             TableFromSourceOptionName::Details => "DETAILS",
         })
     }
@@ -1539,7 +1539,7 @@ impl WithOptionName for TableFromSourceOptionName {
         match self {
             TableFromSourceOptionName::Details
             | TableFromSourceOptionName::TextColumns
-            | TableFromSourceOptionName::IgnoreColumns => false,
+            | TableFromSourceOptionName::ExcludeColumns => false,
         }
     }
 }
@@ -2534,7 +2534,7 @@ pub enum AlterSourceAddSubsourceOptionName {
     /// Columns whose types you want to unconditionally format as text
     TextColumns,
     /// Columns you want to ignore when ingesting data
-    IgnoreColumns,
+    ExcludeColumns,
     /// Updated `DETAILS` for an ingestion, e.g.
     /// [`crate::ast::PgConfigOptionName::Details`]
     /// or
@@ -2546,7 +2546,7 @@ impl AstDisplay for AlterSourceAddSubsourceOptionName {
     fn fmt<W: fmt::Write>(&self, f: &mut AstFormatter<W>) {
         f.write_str(match self {
             AlterSourceAddSubsourceOptionName::TextColumns => "TEXT COLUMNS",
-            AlterSourceAddSubsourceOptionName::IgnoreColumns => "IGNORE COLUMNS",
+            AlterSourceAddSubsourceOptionName::ExcludeColumns => "EXCLUDE COLUMNS",
             AlterSourceAddSubsourceOptionName::Details => "DETAILS",
         })
     }
@@ -2563,7 +2563,7 @@ impl WithOptionName for AlterSourceAddSubsourceOptionName {
         match self {
             AlterSourceAddSubsourceOptionName::Details
             | AlterSourceAddSubsourceOptionName::TextColumns
-            | AlterSourceAddSubsourceOptionName::IgnoreColumns => false,
+            | AlterSourceAddSubsourceOptionName::ExcludeColumns => false,
         }
     }
 }