Deprecate $MYSQL_UNIX_PORT environment variable

changelog.md

@@ -4,6 +4,7 @@ Upcoming (TBD)
 Features
 ---------
 * Add a `--batch` option as an alternative to STDIN.
+* Deprecate `$MYSQL_UNIX_PORT` environment variable in favor of `$MYSQL_UNIX_SOCKET`.
 
 
 Bug Fixes

mycli/main.py

@@ -1911,7 +1911,7 @@ def get_last_query(self) -> str | None:
 @click.option("-h", "--host", envvar="MYSQL_HOST", help="Host address of the database.")
 @click.option("-P", "--port", envvar="MYSQL_TCP_PORT", type=int, help="Port number to use for connection. Honors $MYSQL_TCP_PORT.")
 @click.option("-u", "--user", help="User name to connect to the database.")
-@click.option("-S", "--socket", envvar="MYSQL_UNIX_PORT", help="The socket file to use for connection.")
+@click.option("-S", "--socket", envvar="MYSQL_UNIX_SOCKET", help="The socket file to use for connection.")
 @click.option(
     "-p",
     "--pass",
@@ -2188,6 +2188,7 @@ def get_password_from_file(password_file: str | None) -> str | None:
             else:
                 click.secho(alias)
         sys.exit(0)
+
     if list_ssh_config:
         ssh_config = read_ssh_config(ssh_config_path)
         try:
@@ -2202,6 +2203,18 @@ def get_password_from_file(password_file: str | None) -> str | None:
             else:
                 click.secho(host_entry)
         sys.exit(0)
+
+    if 'MYSQL_UNIX_PORT' in os.environ:
+        # deprecated 2026-03
+        click.secho(
+            "The MYSQL_UNIX_PORT environment variable is deprecated in favor of MYSQL_UNIX_SOCKET.  "
+            "MYSQL_UNIX_PORT will be removed in a future release.",
+            err=True,
+            fg="red",
+        )
+        if not socket:
+            socket = os.environ['MYSQL_UNIX_PORT']
+
     # Choose which ever one has a valid value.
     database = dbname or database