From f78411787bdd73e412f16e7a63344ad88c99081a Mon Sep 17 00:00:00 2001 From: looreenz Date: Thu, 28 May 2026 11:55:29 +0200 Subject: [PATCH] feat: modularize system-versioned-tables, mcp and sdd artifacts --- mariadb-mcp/SKILL.md | 146 ++----------- mariadb-mcp/docs/connecting.md | 35 ++++ mariadb-mcp/docs/gotchas.md | 8 + mariadb-mcp/docs/installation.md | 23 ++ mariadb-mcp/docs/overview.md | 24 +++ mariadb-mcp/docs/security.md | 11 + mariadb-mcp/docs/sources.md | 8 + mariadb-mcp/docs/vector-search.md | 19 ++ mariadb-system-versioned-tables/SKILL.md | 198 ++---------------- .../docs/alter-table.md | 13 ++ .../docs/column-control.md | 20 ++ .../docs/creation.md | 23 ++ .../docs/gotchas.md | 8 + .../docs/history-management.md | 35 ++++ .../docs/overview.md | 20 ++ .../docs/querying.md | 28 +++ .../docs/sources.md | 8 + .../docs/transaction-tracking.md | 17 ++ .../apply-progress.md | 9 + sdd/modular-skills-architecture/design.md | 47 +++++ sdd/modular-skills-architecture/proposal.md | 51 +++++ sdd/modular-skills-architecture/tasks.md | 42 ++++ .../apply-progress.md | 14 ++ sdd/standardize-sdd-framework/design.md | 63 ++++++ sdd/standardize-sdd-framework/proposal.md | 51 +++++ sdd/standardize-sdd-framework/tasks.md | 45 ++++ 26 files changed, 650 insertions(+), 316 deletions(-) create mode 100644 mariadb-mcp/docs/connecting.md create mode 100644 mariadb-mcp/docs/gotchas.md create mode 100644 mariadb-mcp/docs/installation.md create mode 100644 mariadb-mcp/docs/overview.md create mode 100644 mariadb-mcp/docs/security.md create mode 100644 mariadb-mcp/docs/sources.md create mode 100644 mariadb-mcp/docs/vector-search.md create mode 100644 mariadb-system-versioned-tables/docs/alter-table.md create mode 100644 mariadb-system-versioned-tables/docs/column-control.md create mode 100644 mariadb-system-versioned-tables/docs/creation.md create mode 100644 mariadb-system-versioned-tables/docs/gotchas.md create mode 100644 mariadb-system-versioned-tables/docs/history-management.md create mode 100644 mariadb-system-versioned-tables/docs/overview.md create mode 100644 mariadb-system-versioned-tables/docs/querying.md create mode 100644 mariadb-system-versioned-tables/docs/sources.md create mode 100644 mariadb-system-versioned-tables/docs/transaction-tracking.md create mode 100644 sdd/modular-skills-architecture/apply-progress.md create mode 100644 sdd/modular-skills-architecture/design.md create mode 100644 sdd/modular-skills-architecture/proposal.md create mode 100644 sdd/modular-skills-architecture/tasks.md create mode 100644 sdd/standardize-sdd-framework/apply-progress.md create mode 100644 sdd/standardize-sdd-framework/design.md create mode 100644 sdd/standardize-sdd-framework/proposal.md create mode 100644 sdd/standardize-sdd-framework/tasks.md diff --git a/mariadb-mcp/SKILL.md b/mariadb-mcp/SKILL.md index 333e4c3..c25c35e 100644 --- a/mariadb-mcp/SKILL.md +++ b/mariadb-mcp/SKILL.md @@ -4,143 +4,21 @@ description: "How to connect AI agents to MariaDB using the Model Context Protoc --- # MariaDB MCP Server +## 💡 Quick Context +- **Baseline Version:** See [MariaDB Versioning Context](../_shared/versioning.md). +- **Requirements:** Python 3.11+, `uv` package manager, MariaDB server. *Last updated: 2026-05-25* The Model Context Protocol (MCP) lets AI agents connect to external tools and data sources. The MariaDB MCP Server gives agents direct, controlled access to a MariaDB database — reading schemas, running queries, and optionally performing vector/semantic search — without requiring the developer to write integration code. -The server is open source (MIT), maintained by the MariaDB Foundation at [github.com/MariaDB/mcp](https://github.com/MariaDB/mcp). +## Documentation -> **Requires:** Python 3.11+, `uv` package manager, MariaDB server. - -## What Agents Can Do - -With the MariaDB MCP Server connected, an agent can: - -- List databases and tables -- Read table schemas including foreign key relationships -- Run read-only SQL queries (`SELECT`, `SHOW`, `DESCRIBE`) -- Create databases -- Perform semantic/vector search on stored documents (when embedding provider is configured) - -Write operations (`INSERT`, `UPDATE`, `DELETE`) are disabled by default. - -## Installation - -```bash -git clone https://github.com/MariaDB/mcp -cd mcp -cp .env.example .env -# Edit .env with your database credentials -``` - -**Minimum `.env` configuration:** -``` -DB_HOST=127.0.0.1 -DB_PORT=3306 -DB_USER=myuser -DB_PASSWORD=mypassword -DB_NAME=mydatabase -MCP_READ_ONLY=true -``` - -**Run the server:** -```bash -uv run server.py -``` - -## Connecting Claude Code, Cursor, or Windsurf - -Use the official server from a local clone (see Installation). Point your MCP config at `uv run server.py` and the `.env` file with database credentials. - -**Claude Code** (project-scoped `.mcp.json` at the repo root): - -```json -{ - "mcpServers": { - "mariadb": { - "command": "uv", - "args": [ - "--directory", - "/absolute/path/to/mcp", - "run", - "server.py" - ], - "envFile": "/absolute/path/to/mcp/.env" - } - } -} -``` - -Or add via CLI (replace paths): - -```bash -claude mcp add mariadb -- uv --directory /absolute/path/to/mcp run server.py -``` - -**Cursor / VS Code** — same `mcpServers` block in MCP settings; use absolute paths. - -**SSE or HTTP** — run `uv run server.py --transport sse` (or `http`) and connect to the URL; see [MariaDB/mcp README — Integration](https://github.com/MariaDB/mcp#integration---claude-desktopcursorwindsurfvscode). - -> **Not official:** PyPI package `mcp-server-mariadb` (`uvx mcp-server-mariadb`) is a third-party project, not maintained by the MariaDB Foundation. Prefer `github.com/MariaDB/mcp` unless you have a specific reason to use the PyPI package. - -## Available Tools - -| Tool | What it does | -|---|---| -| `list_databases` | Lists all databases the user can access | -| `list_tables` | Lists tables in a database | -| `get_table_schema` | Returns column definitions and types | -| `get_table_schema_with_relations` | Includes foreign key relationships | -| `execute_sql` | Runs a read-only SQL query | -| `create_database` | Creates a new database | - -## Vector & Semantic Search (Optional) - -When an embedding provider is configured, additional tools are available for building RAG pipelines directly through the MCP interface: - -| Tool | What it does | -|---|---| -| `create_vector_store` | Creates a vector store table | -| `insert_docs_vector_store` | Embeds and stores documents | -| `search_vector_store` | Semantic similarity search | -| `list_vector_stores` | Lists available vector stores | -| `delete_vector_store` | Removes a vector store | - -**Configure an embedding provider in `.env`:** -``` -EMBEDDING_PROVIDER=openai # or gemini or huggingface -OPENAI_API_KEY=sk-... -``` - -For building pure vector search applications, using MariaDB's native `VECTOR` type and `VEC_DISTANCE_*` functions directly is more efficient. The MCP vector tools are useful for quick prototyping and when AI agents need to manage the vector store themselves. See the `mariadb-vector` skill for native vector SQL. - -## Security: Read-Only Access - -The `MCP_READ_ONLY=true` setting enforces read-only at the application level by filtering queries. For production or shared environments, also restrict at the database level: - -```sql -CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'password'; -GRANT SELECT, SHOW DATABASES ON *.* TO 'mcp_agent'@'localhost'; --- Do NOT grant INSERT, UPDATE, DELETE, DROP -``` - -Application-level read-only alone is not sufficient — database-level privileges are the reliable guarantee. - -## Key Gotchas - -- **`uv` is required**: the MCP server uses `uv` for dependency management, not `pip` directly. Install: `pip install uv` or `brew install uv`. -- **Read-only is not fully enforced in software**: rely on database-level privileges, not just `MCP_READ_ONLY=true`. -- **Vector tools are disabled** until `EMBEDDING_PROVIDER` is set in `.env`. -- **Connection pooling** defaults to 10 connections — tune `MCP_MAX_POOL_SIZE` for concurrent agent use. -- **SSL/TLS**: configure `DB_SSL_CA`, `DB_SSL_CERT`, `DB_SSL_KEY` in `.env` for remote or production databases. -- **Enterprise version**: MariaDB also offers a MariaDB Enterprise MCP Server with additional access control and multi-agent features. See [mariadb.com/products/mcp-server](https://mariadb.com/products/mcp-server/). - -## Sources - -- [MariaDB MCP Server — GitHub](https://github.com/MariaDB/mcp) -- [MariaDB MCP Server product page — mariadb.com](https://mariadb.com/products/mcp-server/) -- [Connect Claude Code to tools via MCP — Claude Code Docs](https://code.claude.com/docs/en/mcp) -- [MCP Hackathon winner announcement — mariadb.org](https://mariadb.org/model-context-protocol-mcp-hackathon-integration-track-winner/) - -*For topics not covered here, see the official MariaDB documentation at [mariadb.com/docs](https://mariadb.com/docs).* +- [Deep Dive Index] + - [Overview](docs/overview.md) + - [Installation](docs/installation.md) + - [Connecting](docs/connecting.md) + - [Vector & Semantic Search](docs/vector-search.md) + - [Security](docs/security.md) + - [Key Gotchas](docs/gotchas.md) +- [Sources](docs/sources.md) diff --git a/mariadb-mcp/docs/connecting.md b/mariadb-mcp/docs/connecting.md new file mode 100644 index 0000000..27bdd4e --- /dev/null +++ b/mariadb-mcp/docs/connecting.md @@ -0,0 +1,35 @@ +# Connecting Claude Code, Cursor, or Windsurf + +Use the official server from a local clone (see Installation). Point your MCP config at `uv run server.py` and the `.env` file with database credentials. + +## Claude Code (project-scoped `.mcp.json` at the repo root): + +```json +{ + "mcpServers": { + "mariadb": { + "command": "uv", + "args": [ + "--directory", + "/absolute/path/to/mcp", + "run", + "server.py" + ], + "envFile": "/absolute/path/to/mcp/.env" + } + } +} +``` + +Or add via CLI (replace paths): +```bash +claude mcp add mariadb -- uv --directory /absolute/path/to/mcp run server.py +``` + +## Cursor / VS Code +Same `mcpServers` block in MCP settings; use absolute paths. + +## SSE or HTTP +Run `uv run server.py --transport sse` (or `http`) and connect to the URL; see [MariaDB/mcp README — Integration](https://github.com/MariaDB/mcp#integration---claude-desktopcursorwindsurfvscode). + +> **Not official:** PyPI package `mcp-server-mariadb` (`uvx mcp-server-mariadb`) is a third-party project, not maintained by the MariaDB Foundation. Prefer `github.com/MariaDB/mcp` unless you have a specific reason to use the PyPI package. diff --git a/mariadb-mcp/docs/gotchas.md b/mariadb-mcp/docs/gotchas.md new file mode 100644 index 0000000..b0608a2 --- /dev/null +++ b/mariadb-mcp/docs/gotchas.md @@ -0,0 +1,8 @@ +# Key Gotchas + +- **`uv` is required**: the MCP server uses `uv` for dependency management, not `pip` directly. Install: `pip install uv` or `brew install uv`. +- **Read-only is not fully enforced in software**: rely on database-level privileges, not just `MCP_READ_ONLY=true`. +- **Vector tools are disabled** until `EMBEDDING_PROVIDER` is set in `.env`. +- **Connection pooling** defaults to 10 connections — tune `MCP_MAX_POOL_SIZE` for concurrent agent use. +- **SSL/TLS**: configure `DB_SSL_CA`, `DB_SSL_CERT`, `DB_SSL_KEY` in `.env` for remote or production databases. +- **Enterprise version**: MariaDB also offers a MariaDB Enterprise MCP Server with additional access control and multi-agent features. See [mariadb.com/products/mcp-server](https://mariadb.com/products/mcp-server/). diff --git a/mariadb-mcp/docs/installation.md b/mariadb-mcp/docs/installation.md new file mode 100644 index 0000000..f018330 --- /dev/null +++ b/mariadb-mcp/docs/installation.md @@ -0,0 +1,23 @@ +# Installation + +```bash +git clone https://github.com/MariaDB/mcp +cd mcp +cp .env.example .env +# Edit .env with your database credentials +``` + +**Minimum `.env` configuration:** +``` +DB_HOST=127.0.0.1 +DB_PORT=3306 +DB_USER=myuser +DB_PASSWORD=mypassword +DB_NAME=mydatabase +MCP_READ_ONLY=true +``` + +**Run the server:** +```bash +uv run server.py +``` diff --git a/mariadb-mcp/docs/overview.md b/mariadb-mcp/docs/overview.md new file mode 100644 index 0000000..896d599 --- /dev/null +++ b/mariadb-mcp/docs/overview.md @@ -0,0 +1,24 @@ +# MariaDB MCP Server: Overview + +## What Agents Can Do + +With the MariaDB MCP Server connected, an agent can: + +- List databases and tables +- Read table schemas including foreign key relationships +- Run read-only SQL queries (`SELECT`, `SHOW`, `DESCRIBE`) +- Create databases +- Perform semantic/vector search on stored documents (when embedding provider is configured) + +Write operations (`INSERT`, `UPDATE`, `DELETE`) are disabled by default. + +## Available Tools + +| Tool | What it does | +|---|---| +| `list_databases` | Lists all databases the user can access | +| `list_tables` | Lists tables in a database | +| `get_table_schema` | Returns column definitions and types | +| `get_table_schema_with_relations` | Includes foreign key relationships | +| `execute_sql` | Runs a read-only SQL query | +| `create_database` | Creates a new database | diff --git a/mariadb-mcp/docs/security.md b/mariadb-mcp/docs/security.md new file mode 100644 index 0000000..91ff369 --- /dev/null +++ b/mariadb-mcp/docs/security.md @@ -0,0 +1,11 @@ +# Security: Read-Only Access + +The `MCP_READ_ONLY=true` setting enforces read-only at the application level by filtering queries. For production or shared environments, also restrict at the database level: + +```sql +CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'password'; +GRANT SELECT, SHOW DATABASES ON *.* TO 'mcp_agent'@'localhost'; +-- Do NOT grant INSERT, UPDATE, DELETE, DROP +``` + +Application-level read-only alone is not sufficient — database-level privileges are the reliable guarantee. diff --git a/mariadb-mcp/docs/sources.md b/mariadb-mcp/docs/sources.md new file mode 100644 index 0000000..8f25636 --- /dev/null +++ b/mariadb-mcp/docs/sources.md @@ -0,0 +1,8 @@ +# Sources + +- [MariaDB MCP Server — GitHub](https://github.com/MariaDB/mcp) +- [MariaDB MCP Server product page — mariadb.com](https://mariadb.com/products/mcp-server/) +- [Connect Claude Code to tools via MCP — Claude Code Docs](https://code.claude.com/docs/en/mcp) +- [MCP Hackathon winner announcement — mariadb.org](https://mariadb.org/model-context-protocol-mcp-hackathon-integration-track-winner/) + +*For topics not covered here, see the official MariaDB documentation at [mariadb.com/docs](https://mariadb.com/docs).* diff --git a/mariadb-mcp/docs/vector-search.md b/mariadb-mcp/docs/vector-search.md new file mode 100644 index 0000000..947b7c4 --- /dev/null +++ b/mariadb-mcp/docs/vector-search.md @@ -0,0 +1,19 @@ +# Vector & Semantic Search (Optional) + +When an embedding provider is configured, additional tools are available for building RAG pipelines directly through the MCP interface: + +| Tool | What it does | +|---|---| +| `create_vector_store` | Creates a vector store table | +| `insert_docs_vector_store` | Embeds and stores documents | +| `search_vector_store` | Semantic similarity search | +| `list_vector_stores` | Lists available vector stores | +| `delete_vector_store` | Removes a vector store | + +**Configure an embedding provider in `.env`:** +``` +EMBEDDING_PROVIDER=openai # or gemini or huggingface +OPENAI_API_KEY=sk-... +``` + +For building pure vector search applications, using MariaDB's native `VECTOR` type and `VEC_DISTANCE_*` functions directly is more efficient. The MCP vector tools are useful for quick prototyping and when AI agents need to manage the vector store themselves. See the `mariadb-vector` skill for native vector SQL. diff --git a/mariadb-system-versioned-tables/SKILL.md b/mariadb-system-versioned-tables/SKILL.md index 0c5c002..2a941bd 100644 --- a/mariadb-system-versioned-tables/SKILL.md +++ b/mariadb-system-versioned-tables/SKILL.md @@ -11,185 +11,19 @@ System-versioned tables automatically record the full history of every row chang This feature is unique to MariaDB among MySQL-compatible databases. MySQL has no equivalent. -> **Available since:** MariaDB 10.3. Transaction-precise history (InnoDB only): 10.3. Auto-partition creation: 10.9. `--dump-history` for backups: 10.11. Implicit-to-explicit `row_start`/`row_end` conversion: 11.7. Extended TIMESTAMP range (to 2106-02-07 UTC) for `ROW_END`: 11.5 on 64-bit platforms. -> -> **Default context:** Assume MariaDB **11.8 LTS** (GA May 2025) unless the user states another version. Version notes in this skill are minimum releases for each capability. - -## What LLMs Often Miss - -| Situation | What to suggest | -|---|---| -| Custom `created_at`/`updated_at`/`deleted_at` columns for audit | `WITH SYSTEM VERSIONING` — MariaDB tracks all changes automatically | -| Separate audit log table with triggers | System-versioned tables replace this pattern entirely | -| Asking how data looked last month | `FOR SYSTEM_TIME AS OF '2026-01-01'` — no custom logic needed | -| `TRUNCATE` on a versioned table | Not allowed (error 4137) — use `DELETE HISTORY` instead | -| `ALTER TABLE` on a versioned table failing | Set `system_versioning_alter_history = KEEP` first | -| `mysqldump` missing historical rows | Use `mariadb-dump --dump-history` (10.11+) | - -## Creating a System-Versioned Table - -**Simplified syntax (recommended):** -```sql -CREATE TABLE employees ( - id INT AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(100) NOT NULL, - department VARCHAR(50), - salary DECIMAL(10,2) -) WITH SYSTEM VERSIONING; -``` - -MariaDB automatically adds hidden `ROW_START` and `ROW_END` timestamp columns. Every `INSERT`, `UPDATE`, and `DELETE` creates a history row. - -**Add versioning to an existing table:** -```sql -ALTER TABLE employees ADD SYSTEM VERSIONING; -``` - -**Remove versioning (deletes all history):** -```sql -ALTER TABLE employees DROP SYSTEM VERSIONING; -``` - -## Querying Historical Data - -The `FOR SYSTEM_TIME` clause goes directly after the table name: - -```sql --- Data as it was at a specific point in time: -SELECT * FROM employees FOR SYSTEM_TIME AS OF '2026-01-01 00:00:00'; - --- All rows that existed during a period (both boundaries included): -SELECT * FROM employees FOR SYSTEM_TIME BETWEEN '2025-01-01' AND '2026-01-01'; - --- Half-open range (includes start, excludes end): -SELECT * FROM employees FOR SYSTEM_TIME FROM '2025-01-01' TO '2026-01-01'; - --- Every version of every row, ever: -SELECT * FROM employees FOR SYSTEM_TIME ALL; - --- See the full history of one employee: -SELECT *, ROW_START, ROW_END FROM employees FOR SYSTEM_TIME ALL WHERE id = 42; -``` - -**Apply an implicit AS OF to all queries in a session:** -```sql -SET system_versioning_asof = '2026-01-01 00:00:00'; --- Now all queries against versioned tables see that point in time -SELECT * FROM employees; -- returns 2026-01-01 snapshot -SET system_versioning_asof = DEFAULT; -- reset -``` - -## Transaction-Precise History (InnoDB Only) - -For exact transaction-boundary tracking instead of timestamps: - -```sql -CREATE TABLE ledger ( - id INT, - amount DECIMAL(10,2), - trx_start BIGINT UNSIGNED GENERATED ALWAYS AS ROW START, - trx_end BIGINT UNSIGNED GENERATED ALWAYS AS ROW END, - PERIOD FOR SYSTEM_TIME(trx_start, trx_end) -) WITH SYSTEM VERSIONING; - -SELECT * FROM ledger FOR SYSTEM_TIME AS OF TRANSACTION 12345; -``` - -Uses `mysql.transaction_registry` internally. Not compatible with `PARTITION BY SYSTEM_TIME`. - -## Column-Level Control - -Exclude specific columns from versioning (useful for frequently-updated columns like counters): - -```sql -CREATE TABLE products ( - id INT PRIMARY KEY, - name VARCHAR(100), - price DECIMAL(10,2), - view_count INT WITHOUT SYSTEM VERSIONING -- not tracked -) WITH SYSTEM VERSIONING; -``` - -Or version only specific columns in a non-versioned table: -```sql -CREATE TABLE config ( - key VARCHAR(50), - value TEXT WITH SYSTEM VERSIONING -- only this column tracked -); -``` - -## Managing History Growth - -Every update adds a row. For high-update tables, history grows fast. Use partitioning to keep current data performant: - -```sql --- Separate current and historical partitions: -CREATE TABLE events ( - id INT, - payload JSON -) WITH SYSTEM VERSIONING - PARTITION BY SYSTEM_TIME ( - PARTITION p_hist HISTORY, - PARTITION p_cur CURRENT - ); - --- Auto-rotate history by time interval (10.9+): -CREATE TABLE prices ( - symbol VARCHAR(10), - price DECIMAL(10,4) -) WITH SYSTEM VERSIONING - PARTITION BY SYSTEM_TIME INTERVAL 1 MONTH AUTO ( - PARTITION p_cur CURRENT - ); -``` - -**Delete old history:** -```sql --- Delete all history before a date: -DELETE HISTORY FROM employees BEFORE SYSTEM_TIME '2024-01-01'; - --- Delete all history (requires DROP SYSTEM VERSIONING + re-add, or partition drop): -ALTER TABLE employees DROP PARTITION p_hist; -``` - -Requires `DELETE HISTORY` privilege. `TRUNCATE` is not allowed on versioned tables. - -## ALTER TABLE on Versioned Tables - -By default, `ALTER TABLE` on a versioned table raises an error to protect history integrity. To allow it: - -```sql -SET system_versioning_alter_history = KEEP; -ALTER TABLE employees ADD COLUMN manager_id INT; -SET system_versioning_alter_history = ERROR; -- restore default -``` - -`KEEP` allows the alter but historical rows for the new column will have `NULL` values — the history is technically incomplete. This is usually acceptable for adding columns. - -**Convert hidden `ROW_START`/`ROW_END` to explicit columns** (11.7+, MDEV-27293) — once a table is versioned with the hidden form (no `PERIOD FOR SYSTEM_TIME` clause), you can promote them to explicit columns later without dropping versioning. Useful if you initially started simple and later want transaction-precise history or explicit naming for tooling. - -## Key Gotchas - -- **`TRUNCATE` is prohibited** on versioned tables (error 4137). Use `DELETE HISTORY` or partition management instead. -- **Replication**: `ROW_END` is implicitly added to the Primary Key. On replicas, this can cause duplicate key errors during log replay. Fix: set `secure_timestamp = YES` on the replica. -- **Backups**: `mysqldump` / `mariadb-dump` skips historical rows by default. Use `--dump-history` (10.11+) to include them. On restore, set `system_versioning_insert_history=ON` (10.11+, MDEV-16546) so the loader is allowed to write directly into `ROW_START`/`ROW_END`; combine with `secure_timestamp` set to allow session timestamp changes. -- **Table growth**: without partitioning, history rows accumulate indefinitely. Plan partitioning from the start for high-update tables. -- **DELETE HISTORY with future timestamps**: using `BEFORE SYSTEM_TIME` with a timestamp beyond `ROW_END` max can accidentally delete active rows (MDEV-25468). The `ROW_END` max is `2038-01-19` on 32-bit platforms and on MariaDB before 11.5; on MariaDB 11.5+ on 64-bit it's extended to `2106-02-07 06:28:15 UTC` (MDEV-32188). Stay well below your platform's max. -- **`SYSTEM` as a column name**: causes parser errors in `ALTER TABLE` statements. Use backticks: `` `SYSTEM` ``. - -## Use Cases - -- **Audit trails** — who changed what and when, without application code -- **GDPR / PCI DSS compliance** — prove what personal data contained at any date -- **Point-in-time recovery** — restore a row or table to a previous state without a full backup restore -- **Slowly-changing dimensions** — track employee department/salary history, product price history -- **Debugging** — see exactly what changed and when in production data - -## Sources - -- [System-Versioned Tables — MariaDB KB](https://mariadb.com/docs/server/reference/sql-structure/temporal-tables/system-versioned-tables) -- [System-Versioned Tables — MariaDB Docs](https://mariadb.com/docs/server/reference/sql-structure/temporal-tables/system-versioned-tables) -- [Use Cases for MariaDB Data Versioning — MariaDB Blog](https://mariadb.com/resources/blog/use-cases-for-mariadb-data-versioning/) -- [Rewinding Time in MariaDB Databases — MariaDB Blog](https://mariadb.com/resources/blog/rewinding-time-in-mariadb-databases-system-versioning-and-application-time/) - -*For topics not covered here, see the official MariaDB documentation at [mariadb.com/docs](https://mariadb.com/docs).* +## 💡 Quick Context +- **Baseline Version:** See [MariaDB Versioning Context](../_shared/versioning.md). +- **Feature Availability:** MariaDB 10.3+. Transaction-precise history (InnoDB only): 10.3. Auto-partition creation: 10.9. `--dump-history` for backups: 10.11. Implicit-to-explicit `row_start`/`row_end` conversion: 11.7. Extended TIMESTAMP range (to 2106-02-07 UTC) for `ROW_END`: 11.5 on 64-bit platforms. + +## Documentation + +- [Deep Dive Index] + - [Overview & Use Cases](docs/overview.md) + - [Creating a Versioned Table](docs/creation.md) + - [Querying Historical Data](docs/querying.md) + - [Transaction-Precise History](docs/transaction-tracking.md) + - [Column-Level Control](docs/column-control.md) + - [Managing History Growth](docs/history-management.md) + - [ALTER TABLE](docs/alter-table.md) + - [Key Gotchas](docs/gotchas.md) +- [Sources](docs/sources.md) diff --git a/mariadb-system-versioned-tables/docs/alter-table.md b/mariadb-system-versioned-tables/docs/alter-table.md new file mode 100644 index 0000000..2fe8f91 --- /dev/null +++ b/mariadb-system-versioned-tables/docs/alter-table.md @@ -0,0 +1,13 @@ +# ALTER TABLE on Versioned Tables + +By default, `ALTER TABLE` on a versioned table raises an error to protect history integrity. To allow it: + +```sql +SET system_versioning_alter_history = KEEP; +ALTER TABLE employees ADD COLUMN manager_id INT; +SET system_versioning_alter_history = ERROR; -- restore default +``` + +`KEEP` allows the alter but historical rows for the new column will have `NULL` values — the history is technically incomplete. This is usually acceptable for adding columns. + +**Convert hidden `ROW_START`/`ROW_END` to explicit columns** (11.7+, MDEV-27293) — once a table is versioned with the hidden form (no `PERIOD FOR SYSTEM_TIME` clause), you can promote them to explicit columns later without dropping versioning. Useful if you initially started simple and later want transaction-precise history or explicit naming for tooling. diff --git a/mariadb-system-versioned-tables/docs/column-control.md b/mariadb-system-versioned-tables/docs/column-control.md new file mode 100644 index 0000000..1f08d77 --- /dev/null +++ b/mariadb-system-versioned-tables/docs/column-control.md @@ -0,0 +1,20 @@ +# Column-Level Control + +Exclude specific columns from versioning (useful for frequently-updated columns like counters): + +```sql +CREATE TABLE products ( + id INT PRIMARY KEY, + name VARCHAR(100), + price DECIMAL(10,2), + view_count INT WITHOUT SYSTEM VERSIONING -- not tracked +) WITH SYSTEM VERSIONING; +``` + +Or version only specific columns in a non-versioned table: +```sql +CREATE TABLE config ( + key VARCHAR(50), + value TEXT WITH SYSTEM VERSIONING -- only this column tracked +); +``` diff --git a/mariadb-system-versioned-tables/docs/creation.md b/mariadb-system-versioned-tables/docs/creation.md new file mode 100644 index 0000000..9b952b0 --- /dev/null +++ b/mariadb-system-versioned-tables/docs/creation.md @@ -0,0 +1,23 @@ +# Creating a System-Versioned Table + +**Simplified syntax (recommended):** +```sql +CREATE TABLE employees ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(100) NOT NULL, + department VARCHAR(50), + salary DECIMAL(10,2) +) WITH SYSTEM VERSIONING; +``` + +MariaDB automatically adds hidden `ROW_START` and `ROW_END` timestamp columns. Every `INSERT`, `UPDATE`, and `DELETE` creates a history row. + +**Add versioning to an existing table:** +```sql +ALTER TABLE employees ADD SYSTEM VERSIONING; +``` + +**Remove versioning (deletes all history):** +```sql +ALTER TABLE employees DROP SYSTEM VERSIONING; +``` diff --git a/mariadb-system-versioned-tables/docs/gotchas.md b/mariadb-system-versioned-tables/docs/gotchas.md new file mode 100644 index 0000000..660ad4f --- /dev/null +++ b/mariadb-system-versioned-tables/docs/gotchas.md @@ -0,0 +1,8 @@ +# Key Gotchas + +- **`TRUNCATE` is prohibited** on versioned tables (error 4137). Use `DELETE HISTORY` or partition management instead. +- **Replication**: `ROW_END` is implicitly added to the Primary Key. On replicas, this can cause duplicate key errors during log replay. Fix: set `secure_timestamp = YES` on the replica. +- **Backups**: `mysqldump` / `mariadb-dump` skips historical rows by default. Use `--dump-history` (10.11+) to include them. On restore, set `system_versioning_insert_history=ON` (10.11+, MDEV-16546) so the loader is allowed to write directly into `ROW_START`/`ROW_END`; combine with `secure_timestamp` set to allow session timestamp changes. +- **Table growth**: without partitioning, history rows accumulate indefinitely. Plan partitioning from the start for high-update tables. +- **DELETE HISTORY with future timestamps**: using `BEFORE SYSTEM_TIME` with a timestamp beyond `ROW_END` max can accidentally delete active rows (MDEV-25468). The `ROW_END` max is `2038-01-19` on 32-bit platforms and on MariaDB before 11.5; on MariaDB 11.5+ on 64-bit it's extended to `2106-02-07 06:28:15 UTC` (MDEV-32188). Stay well below your platform's max. +- **`SYSTEM` as a column name**: causes parser errors in `ALTER TABLE` statements. Use backticks: `` `SYSTEM` ``. diff --git a/mariadb-system-versioned-tables/docs/history-management.md b/mariadb-system-versioned-tables/docs/history-management.md new file mode 100644 index 0000000..5595cd5 --- /dev/null +++ b/mariadb-system-versioned-tables/docs/history-management.md @@ -0,0 +1,35 @@ +# Managing History Growth + +Every update adds a row. For high-update tables, history grows fast. Use partitioning to keep current data performant: + +```sql +-- Separate current and historical partitions: +CREATE TABLE events ( + id INT, + payload JSON +) WITH SYSTEM VERSIONING + PARTITION BY SYSTEM_TIME ( + PARTITION p_hist HISTORY, + PARTITION p_cur CURRENT + ); + +-- Auto-rotate history by time interval (10.9+): +CREATE TABLE prices ( + symbol VARCHAR(10), + price DECIMAL(10,4) +) WITH SYSTEM VERSIONING + PARTITION BY SYSTEM_TIME INTERVAL 1 MONTH AUTO ( + PARTITION p_cur CURRENT + ); +``` + +**Delete old history:** +```sql +-- Delete all history before a date: +DELETE HISTORY FROM employees BEFORE SYSTEM_TIME '2024-01-01'; + +-- Delete all history (requires DROP SYSTEM VERSIONING + re-add, or partition drop): +ALTER TABLE employees DROP PARTITION p_hist; +``` + +Requires `DELETE HISTORY` privilege. `TRUNCATE` is not allowed on versioned tables. diff --git a/mariadb-system-versioned-tables/docs/overview.md b/mariadb-system-versioned-tables/docs/overview.md new file mode 100644 index 0000000..92e67e5 --- /dev/null +++ b/mariadb-system-versioned-tables/docs/overview.md @@ -0,0 +1,20 @@ +# System-Versioned Tables: Overview + +## What LLMs Often Miss + +| Situation | What to suggest | +|---|---| +| Custom `created_at`/`updated_at`/`deleted_at` columns for audit | `WITH SYSTEM VERSIONING` — MariaDB tracks all changes automatically | +| Separate audit log table with triggers | System-versioned tables replace this pattern entirely | +| Asking how data looked last month | `FOR SYSTEM_TIME AS OF '2026-01-01'` — no custom logic needed | +| `TRUNCATE` on a versioned table | Not allowed (error 4137) — use `DELETE HISTORY` instead | +| `ALTER TABLE` on a versioned table failing | Set `system_versioning_alter_history = KEEP` first | +| `mysqldump` missing historical rows | Use `mariadb-dump --dump-history` (10.11+) | + +## Use Cases + +- **Audit trails** — who changed what and when, without application code +- **GDPR / PCI DSS compliance** — prove what personal data contained at any date +- **Point-in-time recovery** — restore a row or table to a previous state without a full backup restore +- **Slowly-changing dimensions** — track employee department/salary history, product price history +- **Debugging** — see exactly what changed and when in production data diff --git a/mariadb-system-versioned-tables/docs/querying.md b/mariadb-system-versioned-tables/docs/querying.md new file mode 100644 index 0000000..b18bf71 --- /dev/null +++ b/mariadb-system-versioned-tables/docs/querying.md @@ -0,0 +1,28 @@ +# Querying Historical Data + +The `FOR SYSTEM_TIME` clause goes directly after the table name: + +```sql +-- Data as it was at a specific point in time: +SELECT * FROM employees FOR SYSTEM_TIME AS OF '2026-01-01 00:00:00'; + +-- All rows that existed during a period (both boundaries included): +SELECT * FROM employees FOR SYSTEM_TIME BETWEEN '2025-01-01' AND '2026-01-01'; + +-- Half-open range (includes start, excludes end): +SELECT * FROM employees FOR SYSTEM_TIME FROM '2025-01-01' TO '2026-01-01'; + +-- Every version of every row, ever: +SELECT * FROM employees FOR SYSTEM_TIME ALL; + +-- See the full history of one employee: +SELECT *, ROW_START, ROW_END FROM employees FOR SYSTEM_TIME ALL WHERE id = 42; +``` + +**Apply an implicit AS OF to all queries in a session:** +```sql +SET system_versioning_asof = '2026-01-01 00:00:00'; +-- Now all queries against versioned tables see that point in time +SELECT * FROM employees; -- returns 2026-01-01 snapshot +SET system_versioning_asof = DEFAULT; -- reset +``` diff --git a/mariadb-system-versioned-tables/docs/sources.md b/mariadb-system-versioned-tables/docs/sources.md new file mode 100644 index 0000000..6d05b8b --- /dev/null +++ b/mariadb-system-versioned-tables/docs/sources.md @@ -0,0 +1,8 @@ +# Sources + +- [System-Versioned Tables — MariaDB KB](https://mariadb.com/docs/server/reference/sql-structure/temporal-tables/system-versioned-tables) +- [System-Versioned Tables — MariaDB Docs](https://mariadb.com/docs/server/reference/sql-structure/temporal-tables/system-versioned-tables) +- [Use Cases for MariaDB Data Versioning — MariaDB Blog](https://mariadb.com/resources/blog/use-cases-for-mariadb-data-versioning/) +- [Rewinding Time in MariaDB Databases — MariaDB Blog](https://mariadb.com/resources/blog/rewinding-time-in-mariadb-databases-system-versioning-and-application-time/) + +*For topics not covered here, see the official MariaDB documentation at [mariadb.com/docs](https://mariadb.com/docs).* diff --git a/mariadb-system-versioned-tables/docs/transaction-tracking.md b/mariadb-system-versioned-tables/docs/transaction-tracking.md new file mode 100644 index 0000000..a07dc7e --- /dev/null +++ b/mariadb-system-versioned-tables/docs/transaction-tracking.md @@ -0,0 +1,17 @@ +# Transaction-Precise History (InnoDB Only) + +For exact transaction-boundary tracking instead of timestamps: + +```sql +CREATE TABLE ledger ( + id INT, + amount DECIMAL(10,2), + trx_start BIGINT UNSIGNED GENERATED ALWAYS AS ROW START, + trx_end BIGINT UNSIGNED GENERATED ALWAYS AS ROW END, + PERIOD FOR SYSTEM_TIME(trx_start, trx_end) +) WITH SYSTEM VERSIONING; + +SELECT * FROM ledger FOR SYSTEM_TIME AS OF TRANSACTION 12345; +``` + +Uses `mysql.transaction_registry` internally. Not compatible with `PARTITION BY SYSTEM_TIME`. diff --git a/sdd/modular-skills-architecture/apply-progress.md b/sdd/modular-skills-architecture/apply-progress.md new file mode 100644 index 0000000..ce4a490 --- /dev/null +++ b/sdd/modular-skills-architecture/apply-progress.md @@ -0,0 +1,9 @@ +# Apply Progress: Hyper-Modularization + +- [x] mariadb-features +- [x] mariadb-vector +- [x] mysql-to-mariadb +- [x] oracle-to-mariadb +- [x] mariadb-replication-and-ha +- [x] mariadb-system-versioned-tables +- [x] mariadb-mcp diff --git a/sdd/modular-skills-architecture/design.md b/sdd/modular-skills-architecture/design.md new file mode 100644 index 0000000..851f951 --- /dev/null +++ b/sdd/modular-skills-architecture/design.md @@ -0,0 +1,47 @@ +# Design: Modularizing MariaDB Skill Documentation + +## Technical Approach + +Refactor root `SKILL.md` files for 8 MariaDB-related skills by adopting a `docs/` subdirectory architecture. This modular approach reduces the size of root `SKILL.md` files to under 100 lines, improving maintainability and readability by separating concerns into granular, linked documentation files. + +## Architecture Decisions + +### Decision: Modular Documentation Structure (`docs/` subdirectory) + +**Choice**: Move detailed sections from `SKILL.md` into `docs/.md` files. +**Alternatives considered**: Maintaining a single large file, splitting into subdirectories without a standard convention. +**Rationale**: Root files were exceeding 200+ lines, making them difficult to navigate. A standardized `docs/` directory per skill provides better discoverability and enforces manageable content limits. + +### Decision: PR-per-Skill Rollout + +**Choice**: One PR per skill. +**Alternatives considered**: One massive PR for all 8 skills, or individual PRs per section. +**Rationale**: Smaller, focused PRs reduce risk, simplify reviews, and allow for easier rollbacks if documentation breaks. + +## File Changes + +| File | Action | Description | +|------|--------|-------------| +| `mariadb-*/docs/*.md` | Create | Modular documentation files for each skill | +| `mariadb-*/SKILL.md` | Modify | Strip detailed content, add links to `docs/` files | + +## Testing Strategy + +| Layer | What to Test | Approach | +|-------|-------------|----------| +| Unit | Root `SKILL.md` line count | Ensure `< 100` lines | +| Integration | Link integrity | Verify all links in `SKILL.md` correctly point to `docs/` files | +| E2E | Agent activation | Validate that `mariadb-features` (and others) are still recognized as valid skill directories | + +## Migration / Rollout + +Iterate through each of the 8 MariaDB-related skill folders sequentially. +1. Create `docs/` directory. +2. Refactor `SKILL.md` content into new `docs/` files. +3. Verify links and line counts. +4. Submit PR. +5. Proceed to next skill. + +## Open Questions + +- [ ] Confirm if all 8 skills need the exact same `docs/` structure, or if they should adapt to their specific needs. diff --git a/sdd/modular-skills-architecture/proposal.md b/sdd/modular-skills-architecture/proposal.md new file mode 100644 index 0000000..3fb641e --- /dev/null +++ b/sdd/modular-skills-architecture/proposal.md @@ -0,0 +1,51 @@ +# Proposal: Modularizing SKILL.md entries + +## Intent +Improve maintainability and readability of 8 MariaDB skills documentation by adopting a `docs/` folder architecture. The current root `SKILL.md` files are becoming bloated, making it difficult to find critical information. + +## Scope + +### In Scope +- Create `docs/` subdirectory for each of the 8 MariaDB skills. +- Refactor existing `SKILL.md` content into granular files within `docs/`. +- Enforce a 100-line limit for the root `SKILL.md`. +- Ensure root `SKILL.md` contains clear links to `docs/` files. +- Execute via a PR-per-skill approach. + +### Out of Scope +- Changing the functionality of the skills themselves. +- Updating documentation for other non-MariaDB skills. + +## Capabilities + +### New Capabilities +- `modular-docs-structure`: Standardizing the documentation layout across all skills. + +### Modified Capabilities +- None + +## Approach +We will iterate through each skill, moving detailed sections into `docs/
.md` files, leaving only the summary and links in `SKILL.md`. + +## Affected Areas + +| Area | Impact | Description | +|------|--------|-------------| +| `skills/mariadb-*/` | Modified | Add `docs/` folder, refactor `SKILL.md` | + +## Risks + +| Risk | Likelihood | Mitigation | +|------|------------|------------| +| Broken links | Medium | Verify all links after refactoring in each PR | + +## Rollback Plan +Revert the PR for the specific skill if documentation becomes inaccessible or broken. + +## Dependencies +- None + +## Success Criteria +- [ ] Every MariaDB skill has a `docs/` folder. +- [ ] Every root `SKILL.md` is under 100 lines. +- [ ] All `SKILL.md` files link correctly to `docs/` files. diff --git a/sdd/modular-skills-architecture/tasks.md b/sdd/modular-skills-architecture/tasks.md new file mode 100644 index 0000000..2ebeae2 --- /dev/null +++ b/sdd/modular-skills-architecture/tasks.md @@ -0,0 +1,42 @@ +# Tasks: Modularize Skill Documentation + +## Review Workload Forecast + +| Field | Value | +|-------|-------| +| Estimated changed lines | 200-350 | +| 400-line budget risk | Low | +| Chained PRs recommended | No | +| Suggested split | single PR | +| Delivery strategy | single-pr | +| Chain strategy | size-exception | + +Decision needed before apply: Yes +Chained PRs recommended: No +Chain strategy: size-exception +400-line budget risk: Low + +### Suggested Work Units + +| Unit | Goal | Likely PR | Notes | +|------|------|-----------|-------| +| 1 | Migrate docs and refactor all skills | PR 1 | Base branch: main | + +## Phase 1: Preparation +- [ ] 1.1 Create `mariadb-features/docs` directory +- [ ] 1.2 Create `mariadb-vector/docs` directory +- [ ] 1.3 Create `docs` directories for remaining 6 skills + +## Phase 2: Content Migration +- [ ] 2.1 Migrate long-form content to `mariadb-features/docs` +- [ ] 2.2 Migrate content to `mariadb-vector/docs` +- [ ] 2.3 Migrate content to remaining 6 `docs` directories + +## Phase 3: Refactoring +- [ ] 3.1 Refactor `mariadb-features/SKILL.md` (root) to reference new docs +- [ ] 3.2 Refactor `mariadb-vector/SKILL.md` (root) to reference new docs +- [ ] 3.3 Refactor `SKILL.md` for remaining 6 skills + +## Phase 4: Cleanup & Verification +- [ ] 4.1 Verify root `SKILL.md` files are under 100 lines +- [ ] 4.2 Verify all moved docs are accessible and linked correctly diff --git a/sdd/standardize-sdd-framework/apply-progress.md b/sdd/standardize-sdd-framework/apply-progress.md new file mode 100644 index 0000000..92ec374 --- /dev/null +++ b/sdd/standardize-sdd-framework/apply-progress.md @@ -0,0 +1,14 @@ +# Apply Progress: Standardize SDD Framework + +## Completed Tasks +- ✅ 1.1 Create `skills/_shared/versioning.md` with standardized schema. +- ✅ 2.1 Refactor `mariadb-features/SKILL.md` to standardized format. +- ✅ 2.2 Refactor `mariadb-vector/SKILL.md` to standardized format. +- ✅ 2.3 Refactor `mysql-to-mariadb/SKILL.md` to standardized format. + +## Remaining Tasks (Phase 2) +- ✅ 2.4 Refactor `oracle-to-mariadb/SKILL.md` to standardized format. +- ✅ 2.5 Refactor `mariadb-query-optimization/SKILL.md` to standardized format. +- ✅ 2.6 Refactor `mariadb-replication-and-ha/SKILL.md` to standardized format. +- ✅ 2.7 Refactor `mariadb-system-versioned-tables/SKILL.md` to standardized format. +- ✅ 2.8 Refactor `mariadb-mcp/SKILL.md` to standardized format. diff --git a/sdd/standardize-sdd-framework/design.md b/sdd/standardize-sdd-framework/design.md new file mode 100644 index 0000000..25c08c9 --- /dev/null +++ b/sdd/standardize-sdd-framework/design.md @@ -0,0 +1,63 @@ +# Design: Standardization of MariaDB SKILL.md Framework + +## Technical Approach + +We will standardize all eight MariaDB-related `SKILL.md` files by refactoring them into a unified Markdown schema. This reduces context noise and enforces consistency. We will implement shared versioning via a new `skills/_shared/versioning.md` file, which all other `SKILL.md` files will reference. We will follow a PR-per-skill strategy, starting with `mariadb-features` as a blueprint. + +## Architecture Decisions + +### Decision: Centralized Versioning Boilerplate + +**Choice**: Create `skills/_shared/versioning.md` and reference it from all other skills. +**Alternatives considered**: Hardcoding versioning in each file, or using a complex templating system. +**Rationale**: Hardcoding is redundant and error-prone during upgrades (e.g., when moving past 11.8 LTS). A shared file ensures single-point-of-truth. + +### Decision: PR-per-skill Workflow + +**Choice**: One pull request per skill refactor. +**Alternatives considered**: A single, massive PR for all skills. +**Rationale**: Smaller, focused PRs are easier to review, verify, and revert if necessary. It adheres to the 400-line budget per PR. + +## Data Flow + + [Shared Versioning] <──┐ + │ + [Skill A/SKILL.md] ────┤ (Refactor to Schema) + [Skill B/SKILL.md] ────┤ + [.../SKILL.md] ────────┘ + +## File Changes + +| File | Action | Description | +|------|--------|-------------| +| `skills/_shared/versioning.md` | Create | Contains the standardized versioning snippet (MariaDB 11.8 LTS). | +| `skills/mariadb-*/SKILL.md` | Modify | Refactor existing skill files to the new standardized schema. | + +## Interfaces / Contracts + +The standardized schema: +```markdown +--- +name: [skill-name] +description: "[Summary]" +--- +# [Title] +## 💡 Quick Context +- **Baseline Version:** [Reference shared/versioning.md] +... +``` + +## Testing Strategy + +| Layer | What to Test | Approach | +|-------|-------------|----------| +| Unit | Structural integrity | Validate schema compliance using a script or manual inspection against spec #139. | +| Integration | Accuracy of content | Compare refactored content against original `SKILL.md` to ensure no loss of critical information. | + +## Migration / Rollout + +The `mariadb-features` skill will serve as the initial blueprint to validate the schema and refactoring process. Once validated, we will proceed with the remaining skills in the order specified in the proposal. + +## Open Questions + +- [ ] None. diff --git a/sdd/standardize-sdd-framework/proposal.md b/sdd/standardize-sdd-framework/proposal.md new file mode 100644 index 0000000..7c7cb8c --- /dev/null +++ b/sdd/standardize-sdd-framework/proposal.md @@ -0,0 +1,51 @@ +# Proposal: Standardization of MariaDB SKILL.md Framework + +## 1. Objective +Standardize the eight existing `SKILL.md` files to improve token efficiency, reduce LLM context noise, and ensure consistency across MariaDB versions (defaulting to 11.8 LTS). + +## 2. Shared Boilerplate (`skills/_shared/versioning.md`) +To eliminate redundancy, all files will reference a shared snippet for versioning: +> **Baseline Version:** MariaDB 11.8 LTS (GA May 2025). +> **Activation:** Automatic based on context. + +## 3. Standardized Schema Structure +Every `SKILL.md` file will be refactored to this format: + +```markdown +--- +name: [skill-name] +description: "[One sentence summary]" +--- +# [Title] + +## 💡 Quick Context +- **Baseline Version:** [Reference shared/versioning.md] +- **Core Stance:** [E.g., "Vector support is native."] + +## 🚫 Common LLM Hallucinations +| Prompt/Context | Correction | +|---|---| +| ... | ... | + +## 🚀 Core Syntax & Best Practices +[Compact examples, bullet points over prose.] + +## ⚠️ Gotchas +- [Actionable "Do / Don't" list] + +## 📚 References +- [Minimal links] +``` + +## 4. Delivery Strategy (Chained PRs) +- **Constraint**: Each refactored skill will be a separate PR. +- **Budget**: If a single skill refactor exceeds 400 lines (unlikely given compression), it will be split. +- **Order**: + 1. `mariadb-features` + 2. `mariadb-vector` + 3. `mysql-to-mariadb` + 4. `oracle-to-mariadb` + 5. `mariadb-query-optimization` + 6. `mariadb-replication-and-ha` + 7. `mariadb-system-versioned-tables` + 8. `mariadb-mcp` diff --git a/sdd/standardize-sdd-framework/tasks.md b/sdd/standardize-sdd-framework/tasks.md new file mode 100644 index 0000000..4f07177 --- /dev/null +++ b/sdd/standardize-sdd-framework/tasks.md @@ -0,0 +1,45 @@ +# Tasks: Standardize MariaDB Skills + +## Review Workload Forecast + +| Field | Value | +|-------|-------| +| Estimated changed lines | 500-800 | +| 400-line budget risk | High | +| Chained PRs recommended | Yes | +| Suggested split | PR 1 → PR 2 → PR 3 | +| Delivery strategy | ask-on-risk | +| Chain strategy | stacked-to-main | + +Decision needed before apply: Yes +Chained PRs recommended: Yes +Chain strategy: stacked-to-main +400-line budget risk: High + +### Suggested Work Units + +| Unit | Goal | Likely PR | Notes | +|------|------|-----------|-------| +| 1 | Create shared versioning & Refactor 3 skills | PR 1 | Base branch: main | +| 2 | Refactor 3 skills | PR 2 | Base branch: PR 1 | +| 3 | Refactor remaining 2 skills | PR 3 | Base branch: PR 2 | + +## Phase 1: Foundation (Infrastructure) + +- [ ] 1.1 Create `skills/_shared/versioning.md` with standardized schema. + +## Phase 2: Core Implementation (Refactoring) + +- [ ] 2.1 Refactor `mariadb-features/SKILL.md` to standardized format. +- [ ] 2.2 Refactor `mariadb-vector/SKILL.md` to standardized format. +- [ ] 2.3 Refactor `mysql-to-mariadb/SKILL.md` to standardized format. +- [ ] 2.4 Refactor `oracle-to-mariadb/SKILL.md` to standardized format. +- [ ] 2.5 Refactor `mariadb-query-optimization/SKILL.md` to standardized format. +- [ ] 2.6 Refactor `mariadb-replication-and-ha/SKILL.md` to standardized format. +- [ ] 2.7 Refactor `mariadb-system-versioned-tables/SKILL.md` to standardized format. +- [ ] 2.8 Refactor `mariadb-mcp/SKILL.md` to standardized format. + +## Phase 3: Verification + +- [ ] 3.1 Verify all skills load correctly using `skill-registry` (if applicable). +- [ ] 3.2 Ensure consistent frontmatter and structure across all refactored files.