mysql-maintainer

Reactively maintains database structure by updating schema and retrying on MySQL errors.

Connect this package to @itrocks/mysql, then keep using your MySQL data sources normally. Their database structure is maintained automatically, as operations need it, when persistent object structures evolve. There are no migration files to write and no maintenance API to call.

Use with the it.rocks framework

An application based on @itrocks/framework needs the framework, the MySQL data source, and this package:

npm i @itrocks/framework @itrocks/mysql @itrocks/mysql-maintainer

Add the composition and the main MySQL data source to the project's config.yaml:

compose:
  '@itrocks/mysql:Mysql': '@itrocks/mysql-maintainer:Mysql'

dataSource:
  engine: '@itrocks/mysql'
  host: localhost
  user: application
  password: secret
  database: application

The compose entry enriches @itrocks/mysql with the automatic maintenance behaviour. It uses the standard @itrocks/compose mechanism for enriching one module with another module's features.

The dataSource entry above configures the project's main data source. You can instead create other MySQL data sources as described in the @itrocks/mysql documentation. Every data source based on the composed @itrocks/mysql implementation is maintained automatically.

That is the complete setup. Keep changing and using persistent object classes through the usual it.rocks storage operations; the required database changes are applied when an operation first needs them.

Use outside the it.rocks framework

The same integration principle can be used without @itrocks/framework:

1. Install @itrocks/mysql and a mixin-based composition system such as @itrocks/compose. A wrapper implementing the same API as @itrocks/mysql can be used instead.
2. Create the required @itrocks/mysql data sources as described in its documentation. This package does not change how data sources are configured.
3. Install @itrocks/mysql-maintainer in the project.
4. Use the chosen composition system to enrich the Mysql implementation from @itrocks/mysql with the behaviour supplied by @itrocks/mysql-maintainer. Refer to the @itrocks/compose documentation when using that package.
5. Use the MySQL data sources normally. Their operations now trigger automatic maintenance when the current database structure no longer supports the persistent object model.

The application integrator is responsible for performing the composition early enough and according to the chosen composition system's loading rules.

How it works

The package enriches the usual Mysql operations with the context required to identify the persistent classes involved. Projection, search and count queries retain every root and related type supplied by the MySQL query graph. Each connection stores that context with AsyncLocalStorage, so concurrent operations on different classes cannot overwrite one another's maintenance target. It intercepts MySQL errors that indicate a missing or outdated table, column, or foreign key, derives the expected schema from the object model, applies the required structural changes, and retries the original operation.

For example, a read follows this simplified sequence:

1. The application reads an object through a MySQL data source as usual.
2. The enriched data source records the class being read and executes the SQL query.
3. If MySQL reports a supported structure error, the maintainer compares the database with the schema derived from that class and updates the affected table or relationship table.
4. The data source retries the same query and returns the read result to the application.

The exported classes that implement context tracking, error handling, schema updates, and retries are internal mechanics of this integration. They are not a separate API that an application needs to call.

Unique indexes declared with @Unique from @itrocks/unique are checked before the first insert or update of each persistent class on a database connection. This lazy preflight also detects an index added to a class after its table already exists. Writes of the same class on the same connection share one preflight, and a new connection performs the check again.

If existing duplicate rows prevent a unique index from being created, the maintainer does not alter or delete those rows. It rejects the write with a generic UniqueIndexMaintenanceError. Operational logs contain only a fixed event name and a driver error code from a closed operational allowlist; they do not contain SQL, parameters, driver messages, arbitrary code strings, or stored values. Once an operator resolves the duplicates, a later write retries the preflight.

Persistent model requirements

Automatic maintenance derives database structure from business classes and their reflection metadata. Those classes must follow the it.rocks persistent object conventions, including the decorators and metadata used by its ORM packages.

The current implementation is strongly coupled to the it.rocks ORM ecosystem. Its npm dependencies show the reflection, storage, schema conversion, and schema diff modules involved. Outside a full it.rocks application, the integrator must provide a compatible model and metadata environment in addition to the MySQL and composition integrations described above.