pt-online-schema-change error: Cannot connect to MySQL - how to specify the DSN

TL;DR

pt-online-schema-change takes the target as a DSN of comma-separated key [your value] parts (D for database, t for table, h for host, u for user), not a URL. Build the DSN as D=[db],t=[table],h=[host],u=[user], pass the password via --ask-pass or a defaults file rather than the command line, and always dry-run without --execute first.

The query

pt-online-schema-change error: Cannot connect to MySQL - how to specify the DSN

Use this when

• pt-online-schema-change fails with "Cannot connect to MySQL"
• Unsure how to specify the DSN for pt-osc
• The tool parses the target as a URL and fails
• An agent needs a working pt-osc command template

Not for

• Connection refused with a correct DSN (check the network, port, and grants)
• Access-denied errors (the user lacks the needed privileges)
• Failures mid-run after connecting (a different troubleshooting path)

Steps

1. Learn the DSN part syntax

pt-osc does not take a URL. The DSN is comma-separated key [your value] parts:

pt-online-schema-change D=[database],t=[table],h=YOUR_HOST,u=[user] --dry-run --alter "ADD COLUMN [col] INT"

D is the database, t the table, h the host, u the user. Expected output: with --dry-run the tool parses the DSN, connects, and prints the plan without changing anything. A DSN error shows up here, safely.

2. Pass the password without putting it on the command line

pt-online-schema-change D=[database],t=[table],h=YOUR_HOST,u=[user] --ask-pass --dry-run --alter "ADD COLUMN [col] INT"

Or store credentials in a mysql defaults file and point at it:

pt-online-schema-change --defaults-file=[path to cnf] D=[database],t=[table],h=YOUR_HOST --dry-run --alter "ADD COLUMN [col] INT"

Expected output: authentication succeeds and the dry run prints its plan. Command-line passwords leak into process lists and shell history; the prompt or the file avoids that.

3. Dry-run first, then execute

Read the dry-run output: the exact ALTER, the chunk size, the trigger plan. When it looks right, re-run the identical command with --execute instead of --dry-run.

pt-online-schema-change D=[database],t=[table],h=YOUR_HOST,u=[user] --ask-pass --execute --alter "ADD COLUMN [col] INT"

Expected output: the tool copies, syncs, and swaps, printing progress until it exits cleanly.

4. Verify the change and clean up

Check the table structure on the database and confirm the application behaves. pt-osc drops the old table by default at the end; if you kept it with --no-drop-old-table, drop it after verification.

Expected output: the new column exists, the old table is gone, and no triggers remain.

Tool compatibility

percona-toolkit 3.x pt-online-schema-change against mysql 5.7 and 8.0, and percona server. DSN syntax is unchanged across 3.x.

Variant phrasings

pt-online-schema-change Cannot connect to MySQL

Steps 1 and 2: rebuild the target as a proper DSN and fix credential passing. Most "cannot connect" reports are DSN syntax, not network.

pt-osc DSN format example

Step 1: D=[db],t=[table],h=[host],u=[user] as comma-separated parts, not a URL.

pt-online-schema-change ask-pass vs defaults-file

Step 2: --ask-pass for interactive runs, --defaults-file for agents and CI. Never -p on the command line.

Why it happens

pt-osc predates URL-style DSNs in the mysql ecosystem and uses its own key [your value] part syntax, which it parses strictly. A URL-shaped target fails parsing before any connection is attempted, so the error reads as "cannot connect" when the real problem is "cannot parse". The --dry-run flag exists precisely to surface this safely.

Edge cases

• Special characters in the database or table name need proper quoting in the shell: single-quote the whole DSN when names contain dashes or dots.
• --ask-pass does not work headless: agents must use --defaults-file with mode 600 permissions.
• A successful dry-run does not guarantee the execute will succeed: locks, disk space, and replica lag only show up on the real run. Monitor it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_WTN7Qw907lV--WWAh1zFyA