Document case-sensitive configuration properties

Author: Joe Lodin

docs/src/main/sphinx/connector/clickhouse.rst

@@ -48,6 +48,8 @@ configured connector to create a catalog named ``sales``.
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 Querying ClickHouse

docs/src/main/sphinx/connector/druid.rst

@@ -44,6 +44,8 @@ name from the properties file.
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. _druid-type-mapping:
 
 Type mapping

docs/src/main/sphinx/connector/jdbc-case-insensitive-matching.fragment

@@ -0,0 +1,56 @@
+Case insensitive matching
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When ``case-insensitive-name-matching`` is set to ``true``, Trino
+is able to query non-lowercase schemas and tables by maintaining a mapping of
+the lowercase name to the actual name in the remote system. However, if two
+schemas and/or tables have names that differ only in case (such as "customers"
+and "Customers") then Trino fails to query them due to ambiguity.
+
+In these cases, use the ``case-insensitive-name-matching.config-file`` catalog
+configuration property to specify a configuration file that maps these remote
+schemas/tables to their respective Trino schemas/tables:
+
+.. code-block:: json
+
+  {
+    "schemas": [
+      {
+        "remote": "CaseSensitiveName",
+        "mapping": "case_insensitive_1"
+      },
+      {
+        "remote": "cASEsENSITIVEnAME",
+        "mapping": "case_insensitive_2"
+      }],
+    "tables": [
+      {
+        "remoteSchema": "CaseSensitiveName",
+        "remoteTable": "tablex",
+        "mapping": "table_1"
+      },
+      {
+        "remoteSchema": "CaseSensitiveName",
+        "remoteTable": "TABLEX",
+        "mapping": "table_2"
+      }]
+  }
+
+Queries against one of the tables or schemes defined in the ``mapping``
+attributes are run against the corresponding remote entity. For example, a query
+against tables in the ``case_insensitive_1`` schema is forwarded to the
+CaseSensitiveName schema and a query against ``case_insensitive_2`` is forwarded
+to the ``cASEsENSITIVEnAME`` schema.
+
+At the table mapping level, a query on ``case_insensitive_1.table_1`` as
+configured above is forwarded to ``CaseSensitiveName.tablex``, and a query on
+``case_insensitive_1.table_2`` is forwarded to ``CaseSensitiveName.TABLEX``.
+
+By default, when a change is made to the mapping configuration file, Trino must
+be restarted to load the changes. Optionally, you can set the
+``case-insensitive-name-mapping.refresh-period`` to have Trino refresh the
+properties without requiring a restart:
+
+.. code-block:: properties
+
+  case-insensitive-name-mapping.refresh-period=30s

docs/src/main/sphinx/connector/jdbc-common-configurations.fragment

@@ -1,7 +1,7 @@
 General configuration properties
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The following table describes general configuration properties for the
+The following table describes general catalog configuration properties for the
 connector:
 
 .. list-table::
@@ -12,29 +12,38 @@ connector:
     - Description
     - Default value
   * - ``case-insensitive-name-matching``
-    - Match schema and table names case insensitively
-    - False
+    - Support case insensitive schema and table names.
+    - ``false``
   * - ``case-insensitive-name-matching.cache-ttl``
     -
-    - 1 minute
+    - ``1m``
+  * - ``case-insensitive-name-matching.config-file``
+    - Path to a name mapping configuration file in JSON format that allows
+      Trino to disambiguate between schemas and tables with similar names in
+      different cases.
+    - ``null``
+  * - ``case-insensitive-name-matching.refresh-period``
+    - Frequency with which Trino checks the name matching configuration file
+      for changes.
+    - ``0`` (refresh disabled)
   * - ``metadata.cache-ttl``
     - Duration for which metadata, including table and column statistics, is
-      cached
-    - 0 (disabled caching)
+      cached.
+    - ``0`` (caching disabled)
   * - ``metadata.cache-missing``
     - Cache the fact that metadata, including table and column statistics, is
       not available
-    - False
+    - ``false``
   * - ``metadata.cache-maximum-size``
     - Maximum number of objects stored in the metadata cache
-    - 10000
+    - ``10000``
   * - ``write.batch-size``
     - Maximum number of statements in a batched execution.
       Do not change this setting from the default. Non-default values may
       negatively impact performance.
-    - 1000
+    - ``1000``
   * - ``join-pushdown.enabled``
     - Enable :ref:`join pushdown <join-pushdown>`. Equivalent :doc:`catalog
       session property </sql/set-session>` is ``join_pushdown_enabled``.  Enabling
       this may negatively impact performance for some queries.
-    - False
+    - ``false``

docs/src/main/sphinx/connector/memsql.rst

@@ -43,6 +43,8 @@ will create a catalog named ``sales`` using the configured connector.
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 Querying SingleStore

docs/src/main/sphinx/connector/mysql.rst

@@ -61,6 +61,8 @@ creates a catalog named ``sales`` using the configured connector.
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 .. _mysql-type-mapping:

docs/src/main/sphinx/connector/oracle.rst

@@ -77,6 +77,8 @@ you name the property file ``sales.properties``, Trino creates a catalog named
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 Querying Oracle

docs/src/main/sphinx/connector/phoenix.rst

@@ -60,6 +60,8 @@ Property Name                                      Required   Description
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 Querying Phoenix tables

docs/src/main/sphinx/connector/postgresql.rst

@@ -61,6 +61,8 @@ catalog named ``sales`` using the configured connector.
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 .. _postgresql-type-mapping:

docs/src/main/sphinx/connector/redshift.rst

@@ -46,6 +46,8 @@ catalog named ``sales`` using the configured connector.
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 Querying Redshift

docs/src/main/sphinx/connector/sqlserver.rst

@@ -59,6 +59,8 @@ catalog named ``sales`` using the configured connector.
 
 .. include:: jdbc-common-configurations.fragment
 
+.. include:: jdbc-case-insensitive-matching.fragment
+
 .. include:: non-transactional-insert.fragment
 
 Querying SQL Server