---
title: "MySQL Mocking | Speedscale Docs"
description: "Mock MySQL database connections and queries for local development using proxymock to streamline your API testing and enhance your testing environment."
canonical: "https://docs.speedscale.com/proxymock/databases/record/mysql/"
---

[Documentation index](https://docs.speedscale.com/proxymock/llms.txt) | [Markdown](https://docs.speedscale.com/proxymock/databases/record/mysql/index.md) | [Canonical page](https://docs.speedscale.com/proxymock/databases/record/mysql/)

# MySQL Mocking

This guide covers how to use proxymock to mock MySQL database connections and queries for local development and testing.

<a id="introduction"></a>

## Introduction to MySQL

MySQL is one of the world's most popular open-source relational database management systems (RDBMS). It uses Structured Query Language (SQL) for accessing and managing data stored in relational tables. **proxymock** is able to record and mock MySQL databases. This allows you to mock a MySQL database, including real data, without running a MySQL database or populating it with data. To do this, we record your app talking to a MySQL database and simulate the database in subsequent tests. To learn more about proxymock recording and architecture, work through the [agent tutorial](https://docs.speedscale.com/proxymock/agent-tutorial/).

<a id="demo-app"></a>

## Demo App

The following instructions will work with most MySQL clients. However, for demonstration purposes we'll use a simple Java application that connects to a MySQL database. If you are using your own app skip ahead to [recording](https://docs.speedscale.com/proxymock/databases/record/mysql/#configure-mysql-client) for the environment variables you'll need.

This demo app is available in the [speedscale/demo](https://github.com/speedscale/demo) repository and requires Java to be installed. If you'd like to use the demo app, clone the repository and navigate to the `java-auth` directory, which contains a basic Java authentication service that interacts with MySQL:

```bash
git clone https://github.com/speedscale/demo && cd demo/java-auth/server
```

Build the java _server_ normally using maven and start MySQL on your local machine (instructions in the README). Don't worry if you don't have java installed and can't use this app. Just apply the environment variables to your own MySQL client app.

<a id="recording-intro"></a>

## Recording MySQL Traffic

The `proxymock record` command creates RRPair files from real MySQL interactions. Each request will contain a MySQL command (like a SELECT SQL statement) and the response will usually contain row information and values returned by the database.

<a id="start-recording"></a>

### Start the Recorder

Start a dedicated terminal window to run the proxymock recorder:

```bash
proxymock record --map 13306=localhost:3306 --app-port 8080
```

This tells the recorder to listen on port 13306 for MySQL traffic and forward it to the real MySQL server at 3306. The database request will be forwarded from 13306 to the real MySQL at 3306. Your can learn more about the how _proxymock_ records on the [architecture page](https://docs.speedscale.com/proxymock/how-it-works/architecture/).

<a id="configure-mysql-client"></a>

### MySQL Connection Configuration

If you are using the demo app, make sure you have MySQL running and you have created the database. The instructions are in the demo [readme](https://github.com/speedscale/demo/tree/master/java-auth).

For proxymock to capture MySQL traffic, point your application at the mapped host and port. Start a new terminal window that will run the demo app server:

```bash
export MYSQL_PORT=13306
export MYSQL_HOST=localhost
export MYSQL_DATABASE=auth_db
java -jar target/auth-1.1.7.jar
```

Normally _MYSQL\_PORT_ and _MYSQL\_HOST_ will point at an external system or at your local machine port 3306. Since _proxymock_ is intercepting traffic on port `localhost:13306` we set MYSQL to those connection parameters. This is the key ingredient for redirecting traffic to the proxymock recorder with `--map`.

<a id="what-gets-recorded"></a>

### What Gets Recorded

You can browse the recording in your browser with proxymock web:

```bash
proxymock web
```

proxymock web shows each statement with its bound values, how it ended and the rest of its connection, and its Live SQL lens follows statements as your app runs them. See [Inspect a statement](https://docs.speedscale.com/proxymock/databases/inspect-a-statement/) and [Watch live SQL](https://docs.speedscale.com/proxymock/databases/watch-live-sql/). To list every statement your app ran, see [SQL inventory](https://docs.speedscale.com/proxymock/databases/sql-inventory/), and to turn them into a runnable `.sql` file, see [Export a SQL script](https://docs.speedscale.com/proxymock/databases/export-sql-script/).

proxymock captures MySQL traffic as RRPair files containing:

*   **Request Data**: SQL queries, prepared statements, connection handshakes
*   **Response Data**: Result sets, error responses, metadata
*   **Timing Information**: Query execution times and connection latency

The actual wire protocol is binary but proxymock displays request and response data as JSON. The underlying files can be modified if you want your mock to return different values. You can learn more about the structure of the underlying recording by looking at the `proxymock` directory containing the recording files and the [docs](https://docs.speedscale.com/proxymock/how-it-works/rrpair-format/).

<a id="troubleshooting-recording"></a>

### Troubleshooting Recording

*   Ensure your MySQL driver supports SOCKS5 proxy or use `--map`
*   If you are using SOCKS, check that `ALL_PROXY` or your driver's SOCKS configuration is set correctly
*   Verify MySQL server is accessible from proxymock

<a id="start-mocks"></a>

## Starting the Mock Server

Make sure to stop your local MySQL server to prevent port conflicts. You can run your app against the normal MySQL port 3306 now and proxymock will simulate the database.

Start the _proxymock_ mock server:

```bash
proxymock mock
```

You can now run your MySQL client normally and it will connect to proxymock on port 3306 like a normal database.

<a id="modifying-responses"></a>

## Modifying Responses

A SQL mock matches on the statement, not on its bound values. See [Mock a database](https://docs.speedscale.com/proxymock/databases/mock-a-database/) for what that means and when a transform should make a value part of the match.

To change a response by hand, edit its RRPair markdown file. To change values on every run, save the transforms in a [blueprint](https://docs.speedscale.com/proxymock/guides/blueprints/) instead. Active blueprints in the workspace apply during `proxymock mock` and `proxymock replay` without rewriting the recording. They use the same [transform engine](https://docs.speedscale.com/concepts/transforms/) as Speedscale Cloud, so you do not need to upload the snapshot.

[Create and Verify Blueprints](https://docs.speedscale.com/proxymock/guides/blueprints/) shows how to save transforms from `proxymock web`, preview their changes, and confirm they ran. Use a responder response chain to change the mock response returned to your app, or a responder request chain to change the request used for mock matching.

If your team already keeps a Traffic Transform Template in Speedscale Cloud, pull it into the workspace:

```sh
proxymock cloud pull transform <id>
```

The template is written to `proxymock/blueprints/<id>.json`, and the next `proxymock mock` applies it.

<a id="load-testing"></a>

## Load and Regression Testing

The statements you recorded can also be replayed against a real MySQL database, to load test it or to catch regressions after a schema change or a MySQL upgrade. See [Load and Regression Test a Database](https://docs.speedscale.com/proxymock/databases/load-and-regression-testing/).

<a id="kubernetes"></a>

## Kubernetes and eBPF

In Kubernetes environments, Speedscale's eBPF collector (`nettap`) captures MySQL traffic automatically at the kernel level — no `--map` configuration, SOCKS proxying, or application changes required. The collector uses kprobes and uprobes to observe TCP and TLS traffic directly, including the MySQL wire protocol.

This means the `--map` workflow described above applies to **local development** only. When your application is deployed in Kubernetes with the Speedscale operator, MySQL traffic is captured transparently alongside all other protocols.

For details on eBPF-based traffic collection, see the [eBPF Traffic Collection](https://docs.speedscale.com/reference/ebpf-traffic-collection/) documentation.
