MySQL Runtime Guide

This guide documents the MySQL runtime track and keeps it separated from SQLite, PostgreSQL, and SQL Server behavior.

Status

MySQL runtime support is implemented.

The package exports:

• MySqlReflector
• MySQL query builders
• MySQL inspector helpers
• schema sync preview types
• MySQL view, trigger, and stored routine APIs
• automatic destructive dependency orchestration
• schema change history and audit hooks

Current Scope

The MySQL runtime currently covers:

• schema reflection and synchronization
• schema planning with planReflect(...)
• schema inspection and entity generation
• MySQL-specific query builder behavior
• returning(...) on insert, update, and delete builders through MySQL-safe re-selection
• views, triggers, functions, and procedures
• dependency-aware destructive orchestration for rebuilds
• bootstrap from connectionString
• schema change history persistence
• audit events through onSchemaChange

Approved Column Renames

Use approvedColumnRenames when a MySQL schema change is a literal rename and the runtime should preserve the existing values during the rebuild.

const db = new MySqlReflector(connectionString, {
	defaultSchema: "app",
	approvedColumnRenames: [
		{ table: "app.accounts", from: "name", to: "display_name" },
	],
	approvedDestructiveTableChanges: ["app.accounts"],
	changeTicketId: "CHG-4102",
});
Copy

The rebuild copy step will project the source column into the new target column name instead of treating the change as data loss.

Current Limits

The MySQL runtime currently does not provide full parity with PostgreSQL in every advanced governance feature.

• returning(...) is emulated with follow-up selection because MySQL does not expose PostgreSQL-style native RETURNING
• materialized views are not supported
• orchestration coverage is narrower than PostgreSQL because MySQL does not include PostgreSQL-specific objects like materialized views

Inspector Fidelity Notes

The current MySQL inspector preserves standard column-based indexes and functional indexes in generated entity metadata when the server exposes expression metadata through information_schema.statistics.expression.

That allows generated output such as index([], { expressions: [...] }) for functional indexes on supported MySQL versions.

Some MySQL-specific index details still require manual review during legacy onboarding.

• older servers that do not expose information_schema.statistics.expression fall back to column-only index metadata
• prefix-length details are not emitted into generated index(...) definitions
• visibility flags and other engine-specific index options are not currently modeled

For legacy MySQL onboarding, treat generated functional indexes as supported on modern MySQL builds, but keep manual review for version-specific metadata gaps.

Full Engine Reference

For the complete engine-level feature matrix and MySQL limitation notes, use:

• DATABASE_ENGINE.md

Use this guide for MySQL-specific runtime orientation and the generated API reference for exported symbols.

Treat DATABASE_ENGINE.md as the stricter compatibility contract when you need the exact distinction between Full, Partial, and Emulated capabilities.