What the agent does
Most teams meet this migration through an error. MySQL 8 creates users with the caching_sha2_password plugin, the mysql package for Node.js does not speak it, and the connection fails with ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol requested by server; consider upgrading MySQL client. mysql2 supports it and keeps most of the old API, which makes the swap look like one line. The agent checks how the application actually talks to the driver before deciding how many lines it is. In an API like Maransatto/rest-api-node-js, package.json depends on mysql at ^2.18.1, and exactly one file requires it: mysql.js, which creates a pool from five MYSQL_ environment variables and exports an execute(query, params) function, a hand-written Promise around pool.query. The five controllers call that function seventeen times and never touch the driver.
That wrapper sets the terms. Callers treat what it resolves to as the rows themselves: they read result.length, results[0].password and result.insertId. mysql2/promise resolves a query to a pair, [rows, fields], so a wrapper that simply returns the driver's promise would hand every controller an array of two things, and result.length would be 2 for every query. The agent rewrites the wrapper to await the pool and return only the first element, and leaves all seventeen call sites untouched.
The second trap is the wrapper's name. It is called execute, and mysql2 has a method of that name which does something different from query: it sends a server-side prepared statement. A tidy-minded rewrite would map one onto the other. In this code that breaks createUser in user-controller.js, which inserts several rows at once with INSERT INTO users (email, password) VALUES ? and a nested array of values. Expanding one placeholder into a list of rows is done by the client when it builds the SQL text, and prepared statements do not do it. The agent keeps pool.query behind the existing name and explains why in a comment and in the pull request.
Then it proves the change against the server version that caused the trouble. The repository's test script is npm's placeholder, but database/db_version.sql creates the tables and test/*.http holds sample requests for users, products, categories and orders. The agent installs a MySQL 8 server in its sandbox from the system package manager, creates a user with the default authentication plugin, loads the schema, starts the app with node server.js, and sends the requests, checking list lengths, inserted ids and the login path. It first confirms that the old driver fails to connect to the same server. It also points at connectionLimit: 1000 in the pool settings, far above a MySQL server's default of 151 connections, as something to review while this file is open.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this Node.js project from the mysql package to mysql2. Find every file that requires mysql and describe how the rest of the code reaches the database: directly, or through a wrapper module. List every way results are consumed (rows as an array, result.insertId, result.affectedRows, the fields argument, streaming, multiple statements, transactions, pool.getConnection). Replace the dependency in package.json and the lockfile, using the package manager the lockfile belongs to. Keep the calling convention the application already has: if callers expect rows, make the wrapper return rows, not the [rows, fields] pair that mysql2/promise resolves to. Do not replace query with execute unless every statement that would use it works as a server-side prepared statement; bulk inserts with VALUES ?, IN (?) with an array, and identifiers passed as ?? placeholders must stay on query. Keep connection options, and report any that mysql2 treats differently (for example dateStrings, supportBigNumbers, decimalNumbers, typeCast, flags, ssl). Then verify against a real server: install MySQL 8 in the sandbox, create a user with the default authentication plugin, load the schema from the repository if there is one, and confirm that the old driver fails to connect with ER_NOT_SUPPORTED_AUTH_MODE and the new one connects. Start the app and exercise each route that reads or writes the database, using the repository's tests or sample requests, and compare response bodies before and after where the old driver can still be used (a user created with mysql_native_password). Report any difference in returned types, such as dates, decimals and booleans. Do not change SQL or table definitions. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that, for rest-api-node-js, changes package.json, yarn.lock and mysql.js, and nothing under controllers/. The description explains why the diff is that small: the wrapper absorbs the change in result shape. It quotes the old wrapper and the new one, names the bulk insert that keeps the code on query, and lists the routes that were exercised with the status and the relevant part of each response.
It shows the connection result both ways against MySQL 8: the old driver's ER_NOT_SUPPORTED_AUTH_MODE and the new driver's successful query. If response bodies differed between drivers for any column type, the description shows the two values next to each other.
A reviewer checks that no call site was converted to prepared statements by accident, reads the note on the pool limit, and decides whether to follow up by removing the hand-written wrapper in favour of the promise API throughout.
Run it on every error-tracker issue with ER_NOT_SUPPORTED_AUTH_MODE
This error tends to appear on the day a database is upgraded or a service is pointed at a new MySQL 8 instance, and it reaches the team as an alert. Create an automation with a webhook trigger in the Project that holds the repository and save the prompt above. An error tracker such as Sentry signs its own webhook requests and cannot add the Authorization: Bearer header the trigger needs, so run a small handler on your server that receives the alert, keeps issues whose message contains ER_NOT_SUPPORTED_AUTH_MODE, and forwards the payload to the trigger's URL with the trigger's secret.
The forwarded alert is placed after the saved prompt as event text, at most 64 KB of it. Keep the automation's max runs per hour at 1 so a burst of identical alerts from every instance of the service starts one run in that hour; one more waits for the next hour and any past that are refused.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The claim that matters in this pull request is that the app works against MySQL 8, and that can only be shown with a MySQL 8 server. A developer's laptop often has an older local database, or a user created years ago with the old password plugin, and the swap passes there without exercising the thing it was for. The agent's sandbox is its own machine: it installs the server version in question, creates a fresh user, and runs the app against it, with every command and response kept in the session transcript.
It also keeps the change honest about scope. The tempting version of this job modernises as it goes, converting callbacks, switching everything to prepared statements, renaming the wrapper. Each of those alters behaviour. A run told to preserve the calling convention and prove it route by route produces a diff a reviewer can approve in minutes, and leaves the refactor as a separate decision.
Frequently asked questions
Is mysql2 a drop-in replacement for mysql?
With callbacks, nearly: createConnection, createPool, query and placeholder escaping work the same way, so changing the require is often enough. The promise API is where shapes differ, since mysql2/promise resolves to [rows, fields]. Code that wrapped the old driver in its own promises needs that wrapper adjusted.
What is the difference between query and execute in mysql2?
query escapes values on the client and sends one SQL string, as the mysql package did. execute prepares the statement on the server and sends values separately. Prepared statements do not expand an array into a list, so VALUES ? bulk inserts and IN (?) with an array must use query.
Can I fix ER_NOT_SUPPORTED_AUTH_MODE without changing drivers?
You can alter the database user to use mysql_native_password, which the old driver supports. That is a change on the server, it has to be repeated for every user and environment, and newer MySQL releases are phasing that plugin out. Moving to mysql2 fixes it in the application.
Will column values come back with different types?
For the common types the defaults match: dates as Date objects, decimals as strings, integers as numbers. Differences appear with options such as dateStrings, supportBigNumbers and typeCast, or with less common column types. The agent compares response bodies under both drivers and lists any value that changed.
Does the agent need access to my production database?
No. It works from the repository: the schema file, the code and any sample requests or tests. It runs its own MySQL server inside the sandbox and never connects to yours, so no database credentials are part of the request.
More jobs like this: Upgrade dependencies weekly
- Migrate from node-sass to Dart Sass in a Webpack Project (webpack)
- Migrate a Python Project From oauth2client to google-auth (oauth2client)
- Migrate From packr to Go's embed Package (packr)
- Replace pkg/errors With the Standard Library in a Go Module (pkg/errors)
- Fix "No module named 'pkg_resources'" by Migrating to importlib.resources (setuptools)
- Migrate a Flask App From psycopg2 to Psycopg 3 (psycopg2)