## 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

```text
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:

```bash
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

```bash
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:

```bash
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.

```bash
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