MySQL CLI Ignores –port Parameter: Troubleshooting Connection Issues with Multiple Instances


3 views

<h2>Understanding the Core Issue</h2>
<p>When working with multiple MySQL instances on a single machine, developers often encounter situations where the <code>mysql</code> command-line client seems to ignore the specified <code>--port</code> parameter. This typically manifests when trying to connect to secondary instances while the client persistently defaults to the standard port 3306.</p>

<h2>Common Causes of Port Ignorance</h2>
<p>The <code>mysql</code> client might bypass your specified port for several reasons:</p>
<ul>
  <li>The <code>--host=localhost</code> parameter triggers Unix socket connections on Linux/Unix systems</li>
  <li>Configuration files (<code>my.cnf</code>) overriding command-line parameters</li>
  <li>Improper parameter ordering in the command syntax</li>
  <li>Typographical errors in the port specification</li>
</ul>

<h2>Solutions for Force TCP Connection</h2>
<p>To explicitly force TCP connection instead of Unix socket:</p>
<pre><code>mysql --protocol=TCP --host=127.0.0.1 --port=9999 -u root -p
</code></pre>

<p>Key differences from original command:</p>
<ul>
  <li><code>--protocol=TCP</code> explicitly requests TCP connection</li>
  <li><code>127.0.0.1</code> instead of <code>localhost</code> prevents socket fallback</li>
</ul>

<h2>Verifying Active Connections</h2>
<p>To confirm which port your client is actually using:</p>
<pre><code>mysqladmin --host=127.0.0.1 --port=9999 processlist
</code></pre>

<h2>Configuration File Precedence</h2>
<p>Check for conflicting settings in configuration files:</p>
<pre><code>mysql --print-defaults
</code></pre>
<p>This reveals all parameters loaded from configuration files that might override your command-line arguments.</p>

<h2>Debugging Connection Attempts</h2>
<p>For detailed connection diagnostics:</p>
<pre><code>mysql --verbose --host=127.0.0.1 --port=9999
</code></pre>
<p>The <code>--verbose</code> flag provides detailed connection attempt information.</p>

<h2>Alternative Connection Methods</h2>
<p>If port specification still fails, consider:</p>
<pre><code># Using the TCP syntax shortcut
mysql -h 127.0.0.1 -P 9999 -u root -p

# Specifying the socket explicitly for socket connections
mysql --socket=/path/to/mysql.sock -u root -p
</code></pre>

When working with multiple MySQL instances on a single machine, developers often encounter this strange scenario:

mysql --host=localhost --port=9999 mysql -u root -p --execute="show tables;"

Despite specifying a custom port (9999 in this case), the connection consistently defaults to the standard 3306 port. This behavior persists even when:

  • Different port numbers are specified
  • The target MySQL instance is confirmed to be running on the specified port
  • Network connectivity is verified

The issue stems from how MySQL interprets localhost connections on Unix-like systems. When you specify:

--host=localhost

MySQL automatically uses a Unix domain socket connection instead of TCP/IP, completely bypassing your specified port. This is an optimization for local connections but causes confusion when dealing with multiple instances.

Solution 1: Force TCP/IP connection

Replace localhost with 127.0.0.1 to ensure TCP/IP connection:

mysql --host=127.0.0.1 --port=9999 -u root -p

Solution 2: Specify the socket explicitly

If you must use Unix sockets, specify the correct socket path:

mysql --socket=/path/to/mysql2.sock -u root -p

Solution 3: Verify with netstat

First confirm your MySQL instance is actually listening on the expected port:

netstat -tulnp | grep mysql

For a development environment with two MySQL instances (3306 and 3307), here's how to properly connect:

# First instance (default)
mysql --host=127.0.0.1 --port=3306 -u root -p

# Second instance
mysql --host=127.0.0.1 --port=3307 -u root -p

For permanent solutions, consider these approaches:

1. Create client configuration files:

[client]
host=127.0.0.1
port=3307
user=dev_user

2. Use connection aliases in ~/.my.cnf:

[client1]
host=127.0.0.1
port=3306

[client2]
host=127.0.0.1
port=3307

Then connect using:

mysql --defaults-group-suffix=2