remix-run/remix · error · Error

MySQL database config requires a database name

Error message

MySQL database config requires a database name

What it means

resolveMysqlDatabaseName extracts the database name from either a connection URL or a config object and throws when neither yields one. The MySQL driver needs an explicit database because migration locking and metadata queries depend on it; the name can come from config.database or the path component of config.uri (or a string URL).

Source

Thrown at packages/data-table-mysql/src/lib/driver.ts:533

function createMysqlConnection(config: string | MysqlPoolOptions): Promise<MysqlConnection> {
  return typeof config === 'string'
    ? mysql.createConnection(config)
    : mysql.createConnection(config)
}

function isMysqlPool(client: MysqlQueryable): client is MysqlPool {
  return 'getConnection' in client && typeof client.getConnection === 'function'
}

function resolveMysqlDatabaseName(config: string | MysqlPoolOptions): string {
  let database =
    typeof config === 'string'
      ? resolveDatabaseNameFromUrl(config)
      : (config.database ?? resolveDatabaseNameFromUrl(config.uri ?? ''))

  if (!database) {
    throw new Error('MySQL database config requires a database name')
  }

  return database
}

function resolveDatabaseNameFromUrl(value: string): string | undefined {
  try {
    let url = new URL(value)
    let database = decodeURIComponent(url.pathname.replace(/^\//, ''))
    return database || undefined
  } catch {
    return undefined
  }
}

function toMysqlServerConfig(config: string | MysqlPoolOptions): string | MysqlPoolOptions {
  if (typeof config === 'string') {
    try {

View on GitHub (pinned to 9696913134)

Solutions

1. Add the database name: { uri: 'mysql://user:pass@host:3306/mydb' } or { database: 'mydb', ... }
2. If using a URL string, verify it includes the path segment after the host
3. Check environment variables (e.g. MYSQL_URL/DATABASE_URL) actually contain the db name at runtime

Example fix

// before
const driver = createMysqlDriver({ uri: 'mysql://user:pass@localhost:3306' })
// after
const driver = createMysqlDriver({ uri: 'mysql://user:pass@localhost:3306/app_db' })

import { parse } from 'node:url'
function databaseNameFromUri(uri: string): string | undefined {
  const path = parse(uri).pathname
  return path ? path.replace(/^\//, '') || undefined : undefined
}
if (!config.database && !databaseNameFromUri(config.uri ?? '')) {
  throw new Error('add database to MySQL config or uri')
}

const configHasDatabase = (c: MysqlPoolOptions | string) =>
  typeof c === 'string' ? /^[^/]+\/.+/.test(c.split('://')[1] ?? '') : Boolean(c.database ?? c.uri?.match(/:\d+\/.+/))

When it happens

Trigger: Passing a config with neither database nor uri; a uri without a path such as 'mysql://user:pass@host:3306'; a uri whose path is empty or malformed so resolveDatabaseNameFromUrl returns undefined.

Common situations: Environment-driven configs where MYSQL_URL omits the database; splitting a URL into components and dropping the path; typos like 'database' vs 'db' keys; test configs reusing a bare host DSN.

Related errors

• MySQL database + method + () requires config-based construc
• Unknown transaction token: + token.id
• MySQL migration lock is already held by this database
• MySQL database cannot + method + while transactions are op
• MySQL migration lock could not be acquired

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/c5cf6818dabb7cd4. Report an issue: GitHub.