Automattic / Automattic/markdown-database-integration

Decouple canonical persistence from SQLite and add database backend adapters

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

Description

## Direction

Decouple MDI's canonical file-backed persistence model from its SQLite query/index implementation while preserving SQLite as the complete reference backend.

The prior SQLite-only product decision recorded in this issue has changed. MDI should support additional database backends through explicit capabilities without duplicating canonical storage, reconstruction, reconciliation, or persistence logic.

## Architecture

```text
Markdown / JSON / schema files

canonical persistence + reconciliation core

normalized backend contract and capabilities
↙ ↘
SQLite adapter MySQL adapters
```

The canonical core owns file formats, storage routing, manifests, hashes, persistence policy, normalized logical mutations, reconciliation decisions, and changed-path receipts.

Backend adapters own query/result behavior, transactions, schema and table introspection, hydration, mutation capture, and backend-specific runtime optimizations.

## Product Shape

Authority, backend, and persistence scope are independent dimensions:

- SQLite mirror and full primary remain supported without configuration or behavior changes.
- MySQL content-primary makes configured posts, meta, and terms file-authoritative on normal WordPress installations.
- MySQL full-primary adds database-level mutation capture for options, users, comments, schemas, and arbitrary plugin tables where the required database boundary is available.
- Backend capabilities determine supported guarantees; mode names do not imply unavailable behavior.

## Compatibility Gate

SQLite compatibility is a separate proof obligation. The program preserves:

- existing Markdown, JSON, schema SQL, manifest, and index formats;
- mirror and primary behavior;
- cold/warm reconstruction;
- lazy content and search behavior;
- explicit/shutdown flush semantics;
- CLI, abilities, response schemas, diagnostics, and observability identifiers;
- released and trunk SQLite Integration compatibility.

## Tracked Work

- [x] #172 defines backend capabilities and freezes the executable SQLite compatibility contract.
- [x] #175 extracts backend-neutral canonical persistence and mutation projection after #172.
- [x] #174 moves the current SQLite runtime behind the backend adapter after #172 and #175.
- [x] #176 adds pluggable content layout profiles; it can proceed independently against the canonical storage contract and must integrate with #171.
- [x] #171 adds backend-neutral three-way reconciliation with plan/apply after #175, consuming #176 for path identity.
- [x] #170 adds MySQL content-primary support after #172, #175, #176, and #171; #174 proves SQLite preservation before this backend ships.
- [ ] #173 adds later full-primary MySQL mutation capture after #170.

Existing related work:

- #106 delivered MySQL-compatible explicit import/export.
- #125 delivered explicit primary-runtime flush and path receipts via #126 and #128.
- #99 tracks a durability failure that must become a backend contract regression fixture.
- #61 keeps Git and remote merge policy outside MDI.

## Program Acceptance Criteria

1. Canonical persistence services contain no SQLite/PDO type dependency.
2. Current SQLite stores and callers remain compatible without migration.
3. SQLite passes the complete backend contract as the reference implementation.
4. MySQL content-primary reconstructs and round-trips managed WordPress content on a real MySQL/MariaDB runtime.
5. Unsupported backend capabilities fail closed and are visible through doctor/health output.
6. The same reconciliation and path-layout contracts work across supported backends.

## AI Assistance

OpenAI GPT-5.6 Sol via OpenCode was used to inspect the current MDI implementation, historical issues, and compatibility surface and draft this revised tracker. Chris Huber changed the product direction, directed the architecture, and remains responsible for the proposal.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.