deprecate connection settings in myclirc [main]

 * deprecate main.default_character_set, with a notice to move the
   setting to the [connection] section
 * deprecate main.ssl_mode, with a notice to move the setting to
   connection.default_ssl_mode

These deprecation notices will affect a modest number of users who
installed mycli for the first time during the periods in which the
given connection-level settings were in [main] in the default myclirc
file.

For default_ssl_mode, that is fresh installs between 2026-01-02 and
2026-02-09.  For default_character_set, that is fresh installs between
2026-01-22 and 2026-02-02.

Users who ran "mycli --checkup" since then were already advised to
migrate the settings to the [connection] section.

While the notices are in red, and printed on every execution of mycli,
respecting of the deprecated settings in [main] still works, iff the
given setting under [main] has a non-blank value.

The --checkup instructions for migrating the settings are not removed,
though they are somewhat duplicative, to keep the checkup instructions
more coherent.

Motivation: general simplification; bundling all breaking changes into
the 2.0 release.  The logic for determining whether the user or package
configuration controls is too subtle when there are multiple possible
locations for the setting.

Preparation for release 2.0

Author: rolandwalker

changelog.md

@@ -10,6 +10,8 @@ Breaking Changes
 * Remove support for deprecated SSH jump functionality.
 * Remove support for `my.cnf` vendor MySQL option files.
 * Remove support for `.myclirc` files in the current working directory.
+* Deprecate `default_character_set` in `[main]` section of `~/.myclirc`.
+* Deprecate `ssl_mode` in `[main]` section of `~/.myclirc`.
 
 
 Documentation

mycli/app_state.py

@@ -11,11 +11,25 @@
     from mycli.client import MyCli
 
 
-def normalize_ssl_mode(config: ConfigObj) -> tuple[str | None, str | None]:
-    ssl_mode = config['main'].get('ssl_mode', None) or config['connection'].get('default_ssl_mode', None)
+def normalize_ssl_mode(
+    config: ConfigObj,
+    config_without_package_defaults: ConfigObj,
+) -> tuple[str | None, str | None]:
+    error_notice: str | None = None
+    ssl_mode: str | None = None
+    if 'main' in config_without_package_defaults and 'ssl_mode' in config_without_package_defaults['main']:
+        # deprecation notice added with mycli 2.0.0 in 2026-07
+        # todo: entirely remove support for ssl_mode in [main]
+        error_notice = (
+            'Mycli 2.0 deprecation notice: please migrate ssl_mode under [main] to default_ssl_mode under [connection] in ~/.myclirc .'
+        )
+        ssl_mode = config_without_package_defaults['main']['ssl_mode']
+    if not ssl_mode and 'default_ssl_mode' in config['connection']:
+        ssl_mode = config['connection']['default_ssl_mode']
     if ssl_mode not in ('auto', 'on', 'off', None):
-        return None, f'Invalid config option provided for ssl_mode ({ssl_mode}); ignoring.'
-    return ssl_mode, None
+        error_notice = f'Invalid config option provided for ssl_mode ({ssl_mode}); ignoring.'
+        return None, error_notice
+    return ssl_mode, error_notice
 
 
 def configure_prompt_state(

mycli/client.py

@@ -132,7 +132,7 @@ def __init__(
         self.binary_display = c['main'].get('binary_display')
         self.llm_prompt_field_truncate, self.llm_prompt_section_truncate = llm_prompt_truncation(c)
 
-        self.ssl_mode, ssl_mode_error = normalize_ssl_mode(c)
+        self.ssl_mode, ssl_mode_error = normalize_ssl_mode(c, self.config_without_package_defaults)
         if ssl_mode_error:
             self.echo(ssl_mode_error, err=True, fg="red")
 

mycli/client_connection.py

@@ -76,14 +76,18 @@ def connect(
 
         passwd = passwd if isinstance(passwd, (str, int)) else mylogin_cnf["password"]
 
-        # default_character_set doesn't check in self.config_without_package_defaults, because the
-        # option already existed before the my.cnf deprecation.  For the same reason,
-        # default_character_set can be in [connection] or [main].
         if not character_set:
-            if 'default_character_set' in self.config['connection']:
+            if 'main' in self.config_without_package_defaults and 'default_character_set' in self.config_without_package_defaults['main']:
+                # deprecation notice added with mycli 2.0.0 in 2026-07
+                # todo: entirely remove support for default_character_set in [main]
+                click.secho(
+                    'Mycli 2.0 deprecation notice: please migrate default_character_set from [main] to [connection] in ~/.myclirc .',
+                    err=True,
+                    fg='red',
+                )
+                character_set = self.config_without_package_defaults['main']['default_character_set']
+            if not character_set and 'default_character_set' in self.config['connection']:
                 character_set = self.config['connection']['default_character_set']
-            elif 'default_character_set' in self.config['main']:
-                character_set = self.config['main']['default_character_set']
         if not character_set:
             character_set = DEFAULT_CHARSET
 

test/pytests/test_app_state.py

@@ -18,21 +18,44 @@ def __init__(self, login_path: str | None = None) -> None:
 
 @pytest.mark.parametrize('ssl_mode', ['auto', 'on', 'off'])
 def test_normalize_ssl_mode_accepts_known_values(ssl_mode: str) -> None:
-    config = ConfigObj({'main': {'ssl_mode': ssl_mode}, 'connection': {'default_ssl_mode': 'off'}})
+    config = ConfigObj({'main': {'ssl_mode': ssl_mode}, 'connection': {'default_ssl_mode': ssl_mode}})
+    config_wo = ConfigObj({'main': {}, 'connection': {}})
 
-    assert normalize_ssl_mode(config) == (ssl_mode, None)
+    assert normalize_ssl_mode(config, config_wo) == (ssl_mode, None)
 
 
 def test_normalize_ssl_mode_falls_back_to_connection_default() -> None:
     config = ConfigObj({'main': {'ssl_mode': ''}, 'connection': {'default_ssl_mode': 'on'}})
+    config_wo = ConfigObj({'main': {}, 'connection': {}})
 
-    assert normalize_ssl_mode(config) == ('on', None)
+    assert normalize_ssl_mode(config, config_wo) == ('on', None)
+
+
+def test_normalize_ssl_mode_prefers_deprecated_main_value() -> None:
+    config = ConfigObj({'main': {}, 'connection': {'default_ssl_mode': 'on'}})
+    config_wo = ConfigObj({'main': {'ssl_mode': 'auto'}, 'connection': {}})
+
+    ssl_mode, warning = normalize_ssl_mode(config, config_wo)
+
+    assert ssl_mode == 'auto'
+    assert (
+        warning
+        == 'Mycli 2.0 deprecation notice: please migrate ssl_mode under [main] to default_ssl_mode under [connection] in ~/.myclirc .'
+    )
+
+
+def test_normalize_ssl_mode_returns_none_when_not_configured() -> None:
+    config = ConfigObj({'main': {}, 'connection': {}})
+    config_wo = ConfigObj({'main': {}, 'connection': {}})
+
+    assert normalize_ssl_mode(config, config_wo) == (None, None)
 
 
 def test_normalize_ssl_mode_reports_invalid_values() -> None:
-    config = ConfigObj({'main': {'ssl_mode': 'required'}, 'connection': {'default_ssl_mode': 'off'}})
+    config = ConfigObj({'main': {'ssl_mode': 'required'}, 'connection': {'default_ssl_mode': 'required'}})
+    config_wo = ConfigObj()
 
-    ssl_mode, warning = normalize_ssl_mode(config)
+    ssl_mode, warning = normalize_ssl_mode(config, config_wo)
 
     assert ssl_mode is None
     assert warning == 'Invalid config option provided for ssl_mode (required); ignoring.'

test/pytests/test_checkup.py

@@ -133,7 +133,6 @@ def test_configuration_checkup_reports_missing_unsupported_and_deprecated(capsys
             'main': {
                 'present': '',
                 'unsupported_item': '',
-                'default_character_set': '',
             },
             'unsupported_section': {
                 'anything': '',
@@ -162,9 +161,6 @@ def test_configuration_checkup_reports_missing_unsupported_and_deprecated(capsys
     assert '### Unsupported in user ~/.myclirc:' in output
     assert 'The entire section:\n\n    [unsupported_section]\n' in output
     assert 'The item:\n\n    [main]\n    unsupported_item =' in output
-    assert '### Deprecated in user ~/.myclirc:' in output
-    assert '    [main]\n    default_character_set' in output
-    assert '    [connection]\n    default_character_set' in output
     assert f'{checkup.REPO_URL}/blob/main/mycli/myclirc' in output
 
 
@@ -200,10 +196,33 @@ def test_configuration_checkup_skips_transitioned_and_free_entry_items(capsys) -
     assert 'The entire section:\n\n    [extra_section]\n' in output
     assert 'Unsupported in user ~/.myclirc:' in output
     assert 'The entire section:\n\n    [unsupported_section]\n' in output
-    assert '[connection]\n    default_character_set =' not in output
     assert '[favorite_queries]' not in output
 
 
+def test_configuration_checkup_reports_deprecated_transition(capsys) -> None:
+    mycli = SimpleNamespace(
+        config={
+            'main': {},
+        },
+        config_without_package_defaults={
+            'main': {
+                'ssl_mode': '',
+            },
+        },
+        config_without_user_options={
+            'main': {},
+        },
+    )
+
+    checkup._configuration_checkup(mycli)
+    output = capsys.readouterr().out
+
+    assert '### Deprecated in user ~/.myclirc:' in output
+    assert 'It is recommended to transition:\n\n    [main]\n    ssl_mode\n\nto\n\n    [connection]\n    default_ssl_mode' in output
+    assert '### Unsupported in user ~/.myclirc:' not in output
+    assert f'{checkup.REPO_URL}/blob/main/mycli/myclirc' in output
+
+
 def test_configuration_checkup_up_to_date(capsys) -> None:
     mycli = SimpleNamespace(
         config={

test/pytests/test_client.py

@@ -31,8 +31,8 @@ def test_init_reports_invalid_ssl_mode(monkeypatch: pytest.MonkeyPatch, tmp_path
     myclirc = write_myclirc(
         tmp_path,
         """
-        [main]
-        ssl_mode = invalid
+        [connection]
+        default_ssl_mode = invalid
         """,
     )
 

test/pytests/test_client_connection.py

@@ -148,12 +148,29 @@ def test_connect_uses_character_set_from_connection_config() -> None:
     assert FakeSQLExecute.calls[-1]['character_set'] == 'utf16'
 
 
-def test_connect_uses_character_set_from_main_config() -> None:
-    client = DummyClient(config={'main': {'default_character_set': 'utf32'}, 'connection': {}})
+def test_connect_uses_deprecated_character_set_from_main_config(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    client = DummyClient(
+        config={'main': {}, 'connection': {}},
+        config_without_package_defaults={'main': {'default_character_set': 'utf32'}},
+    )
+    secho_calls: list[tuple[str, dict[str, Any]]] = []
+    monkeypatch.setattr(
+        client_connection.click,
+        'secho',
+        lambda message, **kwargs: secho_calls.append((message, kwargs)),
+    )
 
     client.connect(host='db', port=3307)
 
     assert FakeSQLExecute.calls[-1]['character_set'] == 'utf32'
+    assert secho_calls == [
+        (
+            'Mycli 2.0 deprecation notice: please migrate default_character_set from [main] to [connection] in ~/.myclirc .',
+            {'err': True, 'fg': 'red'},
+        )
+    ]
 
 
 def test_connect_uses_default_character_set_when_none_configured() -> None: