MySQL

Use MySQLStore to persist Mastra application data, including messages, workflows, traces, scores, and other storage domains, in a MySQL database.

Installation

Storage providers must be installed as separate packages:

npm

npm install @mastra/mysql@latest

pnpm

pnpm add @mastra/mysql@latest

Yarn

yarn add @mastra/mysql@latest

Bun

bun add @mastra/mysql@latest

Usage

Add MySQLStore to your Mastra configuration with a MySQL connection string:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MySQLStore } from '@mastra/mysql'

export const mastra = new Mastra({
  storage: new MySQLStore({
    id: 'mysql-storage',
    connectionString: process.env.MYSQL_URL!,
  }),
})

For example, MYSQL_URL can use the format mysql://user:password@host:3306/database.

Host-based configuration

You can provide individual connection fields instead of a connection string:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MySQLStore } from '@mastra/mysql'

export const mastra = new Mastra({
  storage: new MySQLStore({
    id: 'mysql-storage',
    host: process.env.MYSQL_HOST!,
    port: Number(process.env.MYSQL_PORT ?? 3306),
    user: process.env.MYSQL_USER!,
    password: process.env.MYSQL_PASSWORD,
    database: process.env.MYSQL_DATABASE!,
  }),
})

Options

Connection string

connectionString:

string

MySQL connection string, including the database name unless database is provided separately.

database?:

string

Database name that overrides the database in the connection string.

max?:

number

= 10

Maximum number of connections in the pool.

ssl?:

boolean | Record<string, unknown>

Enables SSL or provides mysql2-compatible connection SSL options.

Host-based connection

host:

string

MySQL server hostname.

port?:

number

= 3306

MySQL server port.

user:

string

MySQL user name.

password?:

string

Password for the MySQL user.

database:

string

Database used for Mastra storage.

ssl?:

boolean | Record<string, unknown>

Enables SSL or provides mysql2-compatible connection SSL options.

max?:

number

= 10

Maximum number of connections in the pool.

waitForConnections?:

boolean

= true

Waits for a connection when the pool has reached its connection limit.

queueLimit?:

number

= 0

Maximum number of requests the pool can queue. Use 0 for no limit.

Storage and index options

id?:

string

= mysql

Unique identifier for this storage instance.

disableInit?:

boolean

Disables automatic initialization. Call storage.init() manually before using the store.

skipDefaultIndexes?:

boolean

When true, default storage indexes aren't created during initialization.

indexes?:

CreateIndexOptions[]

Custom index definitions to create during initialization.

Initialization

When you register storage with Mastra, init() is called automatically to create the core schema:

const storage = new MySQLStore({
  id: 'mysql-storage',
  connectionString: process.env.MYSQL_URL!,
})

export const mastra = new Mastra({
  storage, // init() is called automatically
})

When using storage directly without Mastra, call init() before accessing domain stores:

const storage = new MySQLStore({
  id: 'mysql-storage',
  connectionString: process.env.MYSQL_URL!,
})

await storage.init()

const memoryStore = await storage.getStore('memory')

Production

Use a durable MySQL database that your Mastra deployment can reach. Store credentials in environment variables, and enable SSL when your database provider requires it.