Automattic / Automattic/markdown-database-integration

Add full-primary MySQL mutation capture through a delegating database backend

Open
#173 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
PHP
Stars
5
Forks
1
Avg merge
2h 38m
Merged PRs (30d)
155

Description

## Problem

The MySQL content backend can make selected posts file-primary through WordPress lifecycle events, but full MDI primary semantics also cover options, users, comments, schemas, and arbitrary plugin tables. Those writes can bypass WordPress content hooks and require successful database-level mutation capture.

This is a later child of #57. It follows the MySQL content backend and does not block it.

## Desired Capability

Add a delegating MySQL backend that captures successful mutations at the WordPress database boundary while preserving normal MySQL execution:

```text
WordPress wpdb
-> MDI delegating backend
-> normal MySQL execution
-> normalized successful mutation events
-> canonical persistence core
```

The backend owns MySQL result normalization, transactions, schema introspection, affected-resource discovery, and mutation capture. The canonical core remains SQL- and database-neutral.

## Required Design Evidence

Before implementation, verify the supported deployment boundary for stock WordPress, custom `db.php`, and managed hosts. The backend must define:

- which direct `$wpdb` writes are captured;
- transaction and rollback timing;
- read-after-write behavior;
- schema DDL handling;
- auto-increment identity reconstruction;
- mixed captured/uncaptured deployment behavior;
- operational recovery when canonical persistence fails after MySQL succeeds.

## Acceptance Criteria

1. Direct plugin `$wpdb` DML and DDL mutations produce normalized canonical persistence events after successful execution.
2. Failed and rolled-back SQL produces no canonical state change.
3. Options, users, comments, taxonomy state, and representative plugin schemas/tables reconstruct from canonical files into an empty supported MySQL database.
4. Existing callers observe compatible `wpdb` return values, errors, insert IDs, row counts, timing, and query logging.
5. Mixed-version deployment behavior is documented and tested.
6. Doctor distinguishes full-primary MySQL from content-primary MySQL using capabilities, not mode-name assumptions.
7. Hosts that cannot install the required database boundary receive an explicit unsupported result and retain content-primary operation.
8. SQLite compatibility remains unchanged.

## AI Assistance

OpenAI GPT-5.6 Sol via OpenCode was used to inspect MDI's existing full-state persistence guarantees and draft this issue. Chris Huber directed the architecture and remains responsible for the proposed capability boundary.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by verifying the supported deployment boundary for stock WordPress, custom db.php, and managed hosts. Define how successful and rolled-back DML and DDL, transactions, identities, and mixed captured/uncaptured deployments map to canonical persistence events. Done means the acceptance criteria are documented and tested, including compatible wpdb behavior, recovery, capability-based Doctor detection, unsupported-host handling, and unchanged SQLite compatibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
mysql, php, wordpress
Domain
backend, database
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.