✨ add MySQL SSL certificate options (--mysql-ssl-ca, --mysql-ssl-cert, --mysql-ssl-key) (#128)

* Add MySQL SSL certificate options (--mysql-ssl-ca, --mysql-ssl-cert, --mysql-ssl-key)

Add support for specifying SSL certificate, key, and CA certificate file
paths when connecting to MySQL databases that require secure transport.
This addresses connections where --require_secure_transport=ON is set on
the MySQL server.

Changes:
- Add --mysql-ssl-ca, --mysql-ssl-cert, --mysql-ssl-key CLI options
- Thread SSL params through types, transporter, and mysql.connector.connect
- Update README.md and docs/README.rst
- Add unit tests for SSL param passthrough, partial combinations, defaults
- Add mysql_ssl_certs fixture to extract certs from Docker MySQL containers
- Add functional SSL tests against real MySQL (skipped on versions without certs)

* Address review feedback: add SSL validation and improve cert extraction

* Fail fast on unexpected cert extraction errors instead of skipping

* Enable ssl_verify_cert when CA is provided, document SSL constraints

Author: ryantology

README.md

@@ -69,7 +69,15 @@ Options:
   --mysql-charset TEXT            MySQL database and table character set
                                   [default: utf8mb4]
   --mysql-collation TEXT          MySQL database and table collation
+  --mysql-ssl-ca PATH             Path to SSL CA certificate file.
+  --mysql-ssl-cert PATH           Path to SSL certificate file.
+                                  Must be provided together with
+                                  --mysql-ssl-key.
+  --mysql-ssl-key PATH            Path to SSL key file.
+                                  Must be provided together with
+                                  --mysql-ssl-cert.
   -S, --skip-ssl                  Disable MySQL connection encryption.
+                                  Cannot be used with --mysql-ssl-* options.
   -c, --chunk INTEGER             Chunk reading/writing SQL records
   -l, --log-file PATH             Log file
   --json-as-text                  Transfer JSON columns as TEXT.

docs/README.rst

@@ -47,8 +47,11 @@ Connection Options
 - ``-h, --mysql-host TEXT``: MySQL host. Defaults to localhost.
 - ``-P, --mysql-port INTEGER``: MySQL port. Defaults to 3306.
 - ``--mysql-charset TEXT``: MySQL database and table character set. The default is utf8mb4.
-- ``--mysql-collation TEXT``: MySQL database and table collation
-- ``-S, --skip-ssl``: Disable MySQL connection encryption.
+- ``--mysql-collation TEXT``: MySQL database and table collation.
+- ``--mysql-ssl-ca PATH``: Path to SSL CA certificate file.
+- ``--mysql-ssl-cert PATH``: Path to SSL certificate file. Must be provided together with ``--mysql-ssl-key``.
+- ``--mysql-ssl-key PATH``: Path to SSL key file. Must be provided together with ``--mysql-ssl-cert``.
+- ``-S, --skip-ssl``: Disable MySQL connection encryption. Cannot be used together with ``--mysql-ssl-*`` options.
 
 Other Options
 """""""""""""

src/mysql_to_sqlite3/cli.py

@@ -137,6 +137,24 @@
     default=None,
     help="MySQL database and table collation",
 )
+@click.option(
+    "--mysql-ssl-ca",
+    type=click.Path(exists=True, dir_okay=False, file_okay=True, readable=True),
+    default=None,
+    help="Path to SSL CA certificate file.",
+)
+@click.option(
+    "--mysql-ssl-cert",
+    type=click.Path(exists=True, dir_okay=False, file_okay=True, readable=True),
+    default=None,
+    help="Path to SSL certificate file.",
+)
+@click.option(
+    "--mysql-ssl-key",
+    type=click.Path(exists=True, dir_okay=False, file_okay=True, readable=True),
+    default=None,
+    help="Path to SSL key file.",
+)
 @click.option("-S", "--skip-ssl", is_flag=True, help="Disable MySQL connection encryption.")
 @click.option(
     "-c",
@@ -184,6 +202,9 @@ def cli(
     mysql_port: int,
     mysql_charset: str,
     mysql_collation: str,
+    mysql_ssl_ca: t.Optional[str],
+    mysql_ssl_cert: t.Optional[str],
+    mysql_ssl_key: t.Optional[str],
     skip_ssl: bool,
     chunk: int,
     log_file: t.Union[str, "os.PathLike[t.Any]"],
@@ -215,6 +236,16 @@ def cli(
         if mysql_tables is not None and exclude_mysql_tables is not None:
             raise click.UsageError("Illegal usage: --mysql-tables and --exclude-mysql-tables are mutually exclusive!")
 
+        if skip_ssl and any((mysql_ssl_ca, mysql_ssl_cert, mysql_ssl_key)):
+            raise click.UsageError(
+                "Illegal usage: --skip-ssl and --mysql-ssl-ca/--mysql-ssl-cert/--mysql-ssl-key are mutually exclusive!"
+            )
+
+        if bool(mysql_ssl_cert) != bool(mysql_ssl_key):
+            raise click.UsageError(
+                "Illegal usage: --mysql-ssl-cert and --mysql-ssl-key must be provided together."
+            )
+
         converter = MySQLtoSQLite(
             sqlite_file=sqlite_file,
             mysql_user=mysql_user,
@@ -234,6 +265,9 @@ def cli(
             mysql_port=mysql_port,
             mysql_charset=mysql_charset,
             mysql_collation=mysql_collation,
+            mysql_ssl_ca=mysql_ssl_ca,
+            mysql_ssl_cert=mysql_ssl_cert,
+            mysql_ssl_key=mysql_ssl_key,
             mysql_ssl_disabled=skip_ssl,
             chunk=chunk,
             json_as_text=json_as_text,

src/mysql_to_sqlite3/transporter.py

@@ -110,8 +110,17 @@ def __init__(self, **kwargs: Unpack[MySQLtoSQLiteParams]) -> None:
         if self._without_tables and self._without_data:
             raise ValueError("Unable to continue without transferring data or creating tables!")
 
+        self._mysql_ssl_ca = kwargs.get("mysql_ssl_ca") or None
+        self._mysql_ssl_cert = kwargs.get("mysql_ssl_cert") or None
+        self._mysql_ssl_key = kwargs.get("mysql_ssl_key") or None
         self._mysql_ssl_disabled = bool(kwargs.get("mysql_ssl_disabled", False))
 
+        if self._mysql_ssl_disabled and any((self._mysql_ssl_ca, self._mysql_ssl_cert, self._mysql_ssl_key)):
+            raise ValueError("Cannot use SSL certificate options when SSL is disabled")
+
+        if bool(self._mysql_ssl_cert) != bool(self._mysql_ssl_key):
+            raise ValueError("mysql_ssl_cert and mysql_ssl_key must be provided together")
+
         self._current_chunk_number = 0
 
         self._chunk_size = kwargs.get("chunk") or None
@@ -161,6 +170,10 @@ def __init__(self, **kwargs: Unpack[MySQLtoSQLiteParams]) -> None:
                 password=self._mysql_password,
                 host=self._mysql_host,
                 port=self._mysql_port,
+                ssl_ca=self._mysql_ssl_ca,
+                ssl_cert=self._mysql_ssl_cert,
+                ssl_key=self._mysql_ssl_key,
+                ssl_verify_cert=self._mysql_ssl_ca is not None,
                 ssl_disabled=self._mysql_ssl_disabled,
                 charset=self._mysql_charset,
                 collation=self._mysql_collation,

src/mysql_to_sqlite3/types.py

@@ -32,6 +32,9 @@ class MySQLtoSQLiteParams(TypedDict):
     mysql_port: int
     mysql_charset: t.Optional[str]
     mysql_collation: t.Optional[str]
+    mysql_ssl_ca: t.Optional[str]
+    mysql_ssl_cert: t.Optional[str]
+    mysql_ssl_key: t.Optional[str]
     mysql_ssl_disabled: t.Optional[bool]
     mysql_tables: t.Optional[t.Sequence[str]]
     mysql_user: str
@@ -67,6 +70,9 @@ class MySQLtoSQLiteAttributes:
     _mysql_port: int
     _mysql_charset: str
     _mysql_collation: str
+    _mysql_ssl_ca: t.Optional[str]
+    _mysql_ssl_cert: t.Optional[str]
+    _mysql_ssl_key: t.Optional[str]
     _mysql_ssl_disabled: bool
     _mysql_tables: t.Sequence[str]
     _mysql_user: str

tests/conftest.py

@@ -1,6 +1,8 @@
+import io
 import json
 import os
 import socket
+import tarfile
 import typing as t
 from codecs import open
 from contextlib import contextmanager
@@ -271,6 +273,84 @@ def mysql_instance(mysql_credentials: MySQLCredentials, pytestconfig: Config) ->
         container.kill()
 
 
+class MySQLSSLCerts(t.NamedTuple):
+    """Paths to MySQL SSL certificate files extracted from the Docker container."""
+
+    ca: str
+    client_cert: str
+    client_key: str
+
+
+@pytest.fixture(scope="session")
+def mysql_ssl_certs(
+    mysql_instance: MySQLConnection,
+    pytestconfig: Config,
+    tmp_path_factory: pytest.TempPathFactory,
+) -> t.Optional[MySQLSSLCerts]:
+    db_credentials_file = abspath(join(dirname(__file__), "db_credentials.json"))
+    if isfile(db_credentials_file):
+        return None
+
+    if not pytestconfig.getoption("use_docker"):
+        return None
+
+    client: DockerClient = docker.from_env()
+    try:
+        container: t.Optional[Container] = None
+        for c in client.containers.list():
+            if c.name == "pytest_mysql_to_sqlite3":
+                container = c
+                break
+
+        if container is None:
+            pytest.fail("MySQL test container is running, but SSL cert extraction could not find it")
+
+        ssl_dir = tmp_path_factory.mktemp("mysql_ssl_certs")
+
+        cert_files = {
+            "ca.pem": "ca.pem",
+            "client-cert.pem": "client-cert.pem",
+            "client-key.pem": "client-key.pem",
+        }
+
+        extracted: t.Dict[str, str] = {}
+        for filename, dest_name in cert_files.items():
+            try:
+                data_stream, _stat = container.get_archive(f"/var/lib/mysql/{filename}")
+            except NotFound:
+                # Cert files not present - MySQL version likely doesn't auto-generate them
+                return None
+
+            buf = io.BytesIO()
+            for chunk in data_stream:
+                buf.write(chunk)
+            buf.seek(0)
+            with tarfile.open(fileobj=buf) as tar:
+                member = next(
+                    (m for m in tar.getmembers() if Path(m.name).name == filename),
+                    None,
+                )
+                if member is None:
+                    pytest.fail(f"Docker returned an archive for {filename}, but the file was not present")
+
+                fobj = tar.extractfile(member)
+                if fobj is None:
+                    pytest.fail(f"Could not read {filename} from the Docker archive")
+
+                with fobj:
+                    dest_path = ssl_dir / dest_name
+                    dest_path.write_bytes(fobj.read())
+                    extracted[filename] = str(dest_path)
+
+        return MySQLSSLCerts(
+            ca=extracted["ca.pem"],
+            client_cert=extracted["client-cert.pem"],
+            client_key=extracted["client-key.pem"],
+        )
+    finally:
+        client.close()
+
+
 @pytest.fixture(scope="session")
 def mysql_database(
     tmpdir_factory: TempdirFactory,