rsc-universal 0.1.1

package/skills/mysql/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: mysql
+description: "Use when designing, querying, indexing, or operating a MySQL or MariaDB database and engine-specific behaviour matters: schema and type choices, index design, reading EXPLAIN, online schema change, replication, locking, deadlocks, and server config. Triggers: 'slow MySQL query', 'why isn't my index used', 'EXPLAIN says Using filesort', 'add a column to a huge table without downtime', 'set up GTID replication', 'replica lag', 'InnoDB deadlock', 'utf8mb4 vs utf8', 'caching_sha2_password cannot be loaded', 'pt-online-schema-change', 'gh-ost', 'emoji stored as ????', 'optimizar consulta MySQL', 'por qué no usa el índice', 'optimitzar consulta MySQL', 'MariaDB 11.8 vector'. NOT portable SELECT/JOIN/window-function craft (that is sql); NOT PostgreSQL engine behaviour like VACUUM or JSONB (that is postgresdb); NOT the PlanetScale/Vitess branch-and-deploy workflow (that is planetscale)."
+tags: [mysql, mariadb, innodb, explain, replication, indexing, online-ddl, database]
+recommends: [sql, postgresdb, planetscale, db-migrations, backups]
+origin: risco
+---
+
+# MySQL / MariaDB engine
+
+You are working below portable SQL, at the layer where the answer depends on *which engine* is
+running. This skill owns MySQL 8.4 LTS and MariaDB 11.8 LTS: the **InnoDB** clustered-index storage
+model, MySQL-flavoured DDL and types, index design and the leftmost-prefix rule, reading `EXPLAIN`
+and fixing the plan, online DDL, replication, locking/deadlocks, and day-2 server config.
+
+The dividing line is simple: **if the answer is identical on PostgreSQL, it belongs in `sql`, not
+here.** `sql` owns the dialect-independent SELECT grammar. `mysql` owns how *this* engine stores,
+plans, locks, and replicates. `postgresdb` is the peer engine for the other database — same body
+shape, different facts, never the same answer.
+
+## When to use
+
+- Designing or reviewing a MySQL/MariaDB schema: engine choice, integer/`DECIMAL`/`VARCHAR` sizing,
+  `utf8mb4` charset/collation, `JSON` + generated/`STORED` columns, PK design for InnoDB.
+- A query is slow or scans too many rows; reading `EXPLAIN` / `EXPLAIN ANALYZE` / `FORMAT=JSON`.
+- Choosing or adding an index: composite column order, covering indexes, prefix indexes on `TEXT`,
+  invisible indexes for safe rollout, why an index is *not* used.
+- Schema change on a large/hot table without downtime: `ALGORITHM=INSTANT/INPLACE/COPY`, pt-osc, gh-ost.
+- Replication: binlog row format, GTID (incl. tagged GTIDs), replica lag, semi-sync, group replication.
+- Locking/concurrency: deadlocks, gap/next-key locks, `REPEATABLE READ`, `SELECT ... FOR UPDATE`.
+- Operating the server: buffer pool, `caching_sha2_password` + TLS, slow-query log, `performance_schema`.
+- Migrating 5.7/8.0 → 8.4 LTS, or reasoning about MySQL ↔ MariaDB divergence.
+
+## When NOT to use
+
+| The ask | Goes to |
+|---|---|
+| Portable query craft — joins, window functions, CTEs, NULL 3VL | `sql` |
+| PostgreSQL engine behaviour — MVCC, VACUUM, RLS, JSONB, PgBouncer | `postgresdb` |
+| PlanetScale / Vitess branch + deploy-request workflow, no-FK design | `planetscale` |
+| Vendor-neutral migration *theory* — expand-contract, batched backfill | `db-migrations` |
+| ORM / query-builder API ergonomics | `drizzle-orm`, `prisma-orm` |
+| Backup *strategy* / retention / restore drills as a discipline | `backups` |
+| OLAP / columnar analytics | `clickhouse-analytics`, `duckdb` |
+
+The boundaries with `planetscale` and `db-migrations` are sharp: this skill owns the raw-MySQL
+mechanics (`EXPLAIN`, index choice, `ALGORITHM=`, gh-ost). PlanetScale wraps those in its platform
+workflow; `db-migrations` wraps them in vendor-neutral strategy. You own the knobs they ride on.
+
+## Pick your version first
+
+Get this wrong and every later decision (auth, vector, isolation defaults) is wrong too.
+
+| Target | Use it when | Watch out |
+|---|---|---|
+| **MySQL 8.4 LTS** | Default for conservative production. GA 2024-04-30, supported through April 2032. | `mysql_native_password` is **disabled by default** here. |
+| **MySQL 9.x Innovation** | Only if you need `VECTOR` or the newest features and accept short support. | Short-lived track; `mysql_native_password` is **removed**. Not for stable prod. |
+| **MariaDB 11.8 LTS** | The fork; 2025 yearly LTS, first MariaDB LTS with native vector search. | Auth, vector syntax, and `RETURNING` differ from MySQL — **not drop-in compatible**; `innodb_snapshot_isolation` defaults **ON**. |
+
+`VECTOR` is a MySQL 9.0 (Innovation) feature, *not* in 8.4 LTS. MariaDB 11.8 also has `VECTOR` but
+with different functions (`VEC_DISTANCE_COSINE()` vs MySQL's `STRING_TO_VECTOR()`) — see
+`references/mysql-vs-mariadb.md`. Do not assume one's vector SQL runs on the other.
+
+## Non-negotiables
+
+1. **`utf8mb4`, always — at the column level.** Legacy `utf8` (alias `utf8mb3`) is 3-byte and
+   silently truncates emoji and supplementary characters. Default collation is `utf8mb4_0900_ai_ci`.
+   Setting it on the connection only is not enough; set it on the column.
+2. **Small monotonic PRIMARY KEY.** An InnoDB table *is* its PK B-tree, and every secondary index
+   stores the PK as its row pointer. A random `UUID`/`CHAR(36)` PK bloats every secondary index and
+   wrecks insert locality. Use `BIGINT AUTO_INCREMENT` or an ordered UUIDv7 stored as `BINARY(16)`.
+3. **`binlog_format=ROW` + GTID.** ROW is the only reliable replication format; GTID gives each
+   transaction a globally unique id with auto-skip so it applies at most once per replica.
+4. **`caching_sha2_password` + TLS.** It is the default auth plugin and SHA-256 based; clients need
+   TLS for first-time auth. `mysql_native_password` is disabled by default in 8.4 and gone in 9.0 —
+   do not design around it.
+5. **Index column order follows the leftmost prefix.** `INDEX (a,b,c)` serves `a`, `a,b`, `a,b,c` —
+   never `b` alone. Put equality columns first, then the range/`ORDER BY` column.
+6. **Never `ALTER` a hot table without choosing an algorithm.** Default `COPY` locks and rebuilds.
+   Pick `INSTANT`/`INPLACE`, or use gh-ost / pt-osc, *before* you run it at peak.
+7. **`REPEATABLE READ` + next-key (gap) locks → short, consistently-ordered transactions.** This is
+   the InnoDB default and the usual deadlock source. Acquire rows in the same order everywhere.
+8. **Measure with `EXPLAIN ANALYZE`, do not guess.** The optimizer's `rows` is an estimate;
+   `EXPLAIN ANALYZE` runs the query and reports actual rows and timing.
+
+## Index decision
+
+| You have | Use |
+|---|---|
+| One column in `WHERE`, high selectivity | Single-column index |
+| Multiple `WHERE` columns + an `ORDER BY` | Composite index: equality cols first, then range/sort col (leftmost prefix) |
+| Query reads only indexed columns | Covering index (add the selected cols) — avoids the PK back-lookup |
+| Filtering a long `TEXT`/`VARCHAR` prefix | Prefix index `col(20)` — can't be covering, watch selectivity |
+| Rolling out an index on a hot table safely | `INVISIBLE` index, then flip `VISIBLE` once verified |
+
+```sql
+-- Bad: separate single-column indexes; the optimizer uses at most one, then filesorts.
+CREATE INDEX idx_uid ON orders (user_id);
+CREATE INDEX idx_created ON orders (created_at);
+-- Query: WHERE user_id = ? AND created_at >= ? ORDER BY created_at DESC
+
+-- Good: one composite index — equality (user_id) first, then the range/sort column.
+-- This serves the WHERE and the ORDER BY with no separate sort step.
+CREATE INDEX idx_user_created ON orders (user_id, created_at);
+```
+
+## Read EXPLAIN
+
+`EXPLAIN` shows the plan; `EXPLAIN ANALYZE` runs it and reports actual rows/time;
+`EXPLAIN FORMAT=JSON` shows cost and used-key-parts. Read the access `type` first — it is the ladder
+from worst to best:
+
+`ALL` (full scan) → `index` (full index scan) → `range` → `ref` → `eq_ref` → `const`.
+
+Anything `ALL` on a large table is a red flag. Then check `rows` (estimated rows examined),
+`filtered` (% surviving the `WHERE`), and the `Extra` flags: `Using filesort` (extra sort pass),
+`Using temporary` (materialised temp table), `Using index` (covering — good, no back-lookup).
+
+The most common cause of a missed index is a **non-sargable predicate** — a function or implicit
+charset/type cast wrapping the indexed column:
+
+```sql
+-- Bad: DATE() wraps the indexed column → the index on created_at can't be used → type=ALL.
+SELECT * FROM orders WHERE DATE(created_at) = '2026-06-01';
+
+-- Good: range over the raw column → index range scan (type=range).
+SELECT * FROM orders
+WHERE created_at >= '2026-06-01' AND created_at < '2026-06-02';
+```
+
+A subtler version: joining a `utf8mb4` column to a `latin1` column, or a `VARCHAR` to an `INT`,
+forces a per-row cast and disables the index. Make both sides the same type and collation. Full
+field-by-field reading, the `type` ladder, and every "why no index" cause are in
+`references/indexing-and-explain.md`.
+
+## Online DDL chooser
+
+| Operation / situation | Use |
+|---|---|
+| Add column at end, rename column, set default, drop index | `ALGORITHM=INSTANT` — metadata-only, near-free (8.0+) |
+| Add secondary index, change column nullability inplace | `ALGORITHM=INPLACE, LOCK=NONE` — rebuilds without blocking most writes |
+| What INSTANT/INPLACE can't do, on a small/cold table | `ALGORITHM=COPY` — locks + rebuilds; fine off-hours |
+| Same change on a large/hot table, zero downtime | `gh-ost` or `pt-online-schema-change` — shadow table + swap |
+
+```sql
+-- INSTANT: adding a column at the end is metadata-only in 8.0+. Always be explicit so a
+-- silent fall-through to COPY (which locks) can't happen.
+ALTER TABLE orders ADD COLUMN note VARCHAR(255) NULL, ALGORITHM=INSTANT, LOCK=NONE;
+```
+
+```bash
+# gh-ost: build a shadow table, copy + tail the binlog, then atomic cutover. Always --dry-run
+# first; throttle on replica lag so you don't melt production.
+gh-ost \
+  --host=primary.db --database=shop --table=orders \
+  --alter="ADD INDEX idx_user_created (user_id, created_at)" \
+  --max-lag-millis=1500 --throttle-control-replicas="replica1.db" \
+  --execute   # drop --execute to dry-run
+```
+
+If gh-ost refuses to read the binlog, run `pt-online-schema-change`, which uses triggers instead.
+Both, plus the rollback path and how this composes with `db-migrations` expand-contract theory, are
+in `references/online-ddl-and-migrations.md`.
+
+## Copy-paste patterns
+
+```sql
+-- Covering index: the query reads only (user_id, status, total), so put them all in the index.
+-- EXPLAIN then shows "Using index" — no trip back to the PK leaf for each row.
+SELECT status, total FROM orders WHERE user_id = ?;
+CREATE INDEX idx_cover ON orders (user_id, status, total);
+```
+
+```sql
+-- GTID replication on the replica: GTID auto-positioning, no log file/pos bookkeeping.
+CHANGE REPLICATION SOURCE TO
+  SOURCE_HOST='primary.db', SOURCE_USER='repl', SOURCE_PASSWORD='***',
+  SOURCE_SSL=1, SOURCE_AUTO_POSITION=1;
+START REPLICA;
+```
+
+```sql
+-- Replica lag: read the field, don't eyeball. Seconds_Behind_Source is coarse; for accuracy use
+-- performance_schema replication tables. NULL means replication is broken, not "0 lag".
+SHOW REPLICA STATUS\G   -- Replica_IO_Running / Replica_SQL_Running / Seconds_Behind_Source
+SELECT * FROM performance_schema.replication_applier_status_by_worker;
+```
+
+```sql
+-- Deadlock post-mortem: InnoDB rolls back the cheaper transaction and logs the cycle here.
+SHOW ENGINE INNODB STATUS\G   -- read the LATEST DETECTED DEADLOCK section
+```
+
+```bash
+# Consistent logical dump without locking every table: single transaction over InnoDB.
+mysqldump --single-transaction --set-gtid-purged=AUTO --routines --triggers shop > shop.sql
+```
+
+Replication topologies (async / semi-sync / group replication / InnoDB Cluster + MySQL Router),
+failover, and read-replica routing are in `references/replication-and-ha.md`.
+
+## MySQL vs MariaDB divergence
+
+They share a heritage and diverge in ways that break copy-pasted SQL. Do not assume parity.
+
+| Area | MySQL 8.4 / 9.x | MariaDB 11.8 |
+|---|---|---|
+| Default auth | `caching_sha2_password` | `mysql_native_password` / `ed25519` |
+| `VECTOR` | MySQL 9.0+ only; `STRING_TO_VECTOR()` | Native in 11.8; `VEC_DISTANCE_COSINE()` — different syntax |
+| `RETURNING` | `INSERT ... RETURNING` only (8.0+) | `INSERT`/`UPDATE`/`DELETE ... RETURNING` |
+| Sequences | No `CREATE SEQUENCE` | `CREATE SEQUENCE` supported |
+| System-versioned (temporal) tables | Not supported | `WITH SYSTEM VERSIONING` supported |
+| Snapshot isolation | RR snapshot, no write-conflict detection | `innodb_snapshot_isolation` defaults **ON** |
+| JSON | Native binary `JSON` type | Historically a `LONGTEXT` alias; check version |
+
+Depth and both-direction migration gotchas: `references/mysql-vs-mariadb.md`.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality | Do instead |
+|---|---|---|
+| "`utf8` is Unicode, it's fine." | `utf8` = 3-byte `utf8mb3`; emoji silently become `????`. | `utf8mb4` at the column level. |
+| "A random UUID PK is clean and unique." | Random PK bloats every secondary index and kills insert locality in the clustered index. | `BIGINT AUTO_INCREMENT` or ordered UUIDv7 as `BINARY(16)`. |
+| "`STATEMENT` binlog is smaller, use it." | Non-deterministic statements replicate wrong; silent data drift on replicas. | `binlog_format=ROW`. |
+| "Just keep using `mysql_native_password`." | Disabled by default in 8.4, removed in 9.0 — your upgrade breaks. | `caching_sha2_password` + TLS. |
+| "Wrapping the column in `DATE()`/`LOWER()` is readable." | Function on an indexed column → full scan. | Rewrite to a sargable range; or add a generated column + index. |
+| "`SELECT *` is convenient." | Pulls wide InnoDB rows off-disk and defeats covering indexes. | Select only needed columns. |
+| "I'll hold the transaction open while I do other work." | RR + gap locks held long → deadlocks and lock waits everywhere. | Keep transactions short; commit fast; order rows consistently. |
+| "`ALTER` it now, traffic is fine." | `COPY` algorithm locks a multi-GB table; outage at peak. | Pick `INSTANT`/`INPLACE`, or gh-ost off-peak. |
+| "`EXPLAIN` says 12 rows, so it's fast." | `rows` is an *estimate* from stats. | Confirm with `EXPLAIN ANALYZE` (actual rows/time). |
+| "MyISAM is faster for our table." | No transactions, no FKs, table-level locks, crash-unsafe. | InnoDB for anything transactional. |
+
+## Verify
+
+Run `scripts/verify.sh` from your project root. It is read-only and **never connects to a
+database** — it heuristically lints discovered `*.sql` and `*.cnf`/`my.cnf` files for the foot-guns
+above (legacy `utf8`, MyISAM, random-UUID PK, `binlog_format=STATEMENT`, `mysql_native_password`,
+function-wrapped indexed columns) and checks balanced delimiters. It exits non-zero only on
+unbalanced delimiters or a committed `binlog_format=STATEMENT`; every schema heuristic is advisory.
+It optionally runs `sqlfluff --dialect mysql` if installed.
+
+## See Also
+
+- `../sql/SKILL.md` — portable, engine-agnostic SELECT/JOIN/window-function craft.
+- `../postgresdb/SKILL.md` — the peer engine (PostgreSQL): MVCC, VACUUM, RLS, JSONB.
+- `../planetscale/SKILL.md` — the PlanetScale/Vitess platform workflow on top of MySQL.
+- `db-migrations` — vendor-neutral migration strategy (expand-contract) that the `ALGORITHM=`/gh-ost
+  mechanics here ride on.
+- `backups` — backup strategy, retention, and restore drills as a discipline.

package/skills/mysql/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — mysql
+
+These cases are routing and capability specs, not an automated test suite. There is no in-repo
+trigger harness. To run them, have a human or an LLM judge read `cases.yaml` and check three things:
+that each `should_trigger` prompt would plausibly load this skill, that each `should_not_trigger`
+prompt routes to the named sibling instead (`sql`, `postgresdb`, `planetscale`, `db-migrations`,
+`drizzle-orm` — all real skills), and that an answer to the `capability` scenario hits every bullet
+in its `must_include` rubric. The rubric is the bar: a passing answer reads EXPLAIN, fixes the
+non-sargable predicate, designs the composite/covering index with correct column order, reasons
+about the InnoDB clustered index, and verifies the new plan — without drifting into ORM or platform
+workflow that belongs to a sibling. `scripts/verify.sh` is separate: it lints emitted `*.sql` /
+`*.cnf` artifacts for the foot-guns in SKILL.md and never connects to a database.

package/skills/mysql/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: mysql
+
+should_trigger:
+  - prompt: "This MySQL query is doing a full table scan, EXPLAIN shows type=ALL — how do I index it?"
+    why: Core of the skill — reading the EXPLAIN access type and choosing an InnoDB index.
+  - prompt: "Add a NOT NULL column to a 40GB hot InnoDB table without downtime."
+    why: Online DDL — ALGORITHM choice plus gh-ost/pt-osc on a hot table. MySQL-specific mechanics.
+  - prompt: "Set up GTID-based source-replica replication and check the replica lag."
+    why: Replication setup (CHANGE REPLICATION SOURCE TO, SOURCE_AUTO_POSITION) and lag diagnosis.
+  - prompt: "Getting 'Authentication plugin caching_sha2_password cannot be loaded' connecting to MySQL 8.4."
+    why: Non-obvious. The 8.4 default-auth + TLS trap; mysql_native_password is gone. Pure engine/ops.
+  - prompt: "Our composite index on (a,b,c) isn't used when I filter only on b — why?"
+    why: Non-obvious. The leftmost-prefix rule — the canonical InnoDB index-design confusion.
+  - prompt: "Emoji get stored as ???? in our MySQL VARCHAR column."
+    why: Non-obvious. The legacy 3-byte utf8 (utf8mb3) vs utf8mb4 silent-truncation bug.
+  - prompt: "optimizar consulta MySQL que tarda mucho, el índice no se usa"
+    why: Spanish trigger — slow MySQL query, index not used; squarely engine-level tuning.
+  - prompt: "InnoDB deadlock under REPEATABLE READ — how do I read SHOW ENGINE INNODB STATUS?"
+    why: Locking/concurrency — gap/next-key locks and the deadlock post-mortem, MySQL-specific.
+
+should_not_trigger:
+  - prompt: "Write a window-function query to rank rows per group."
+    route_to: sql
+    why: Portable, engine-agnostic SELECT grammar — identical on Postgres, so it belongs in sql.
+  - prompt: "How does Postgres VACUUM and autovacuum work?"
+    route_to: postgresdb
+    why: PostgreSQL engine behaviour (MVCC garbage collection) — the peer engine, not MySQL.
+  - prompt: "Create a PlanetScale branch and open a deploy request for this schema change."
+    route_to: planetscale
+    why: The PlanetScale/Vitess platform branch-and-deploy workflow, not raw MySQL mechanics.
+  - prompt: "Design an expand-contract migration sequence to rename a column safely."
+    route_to: db-migrations
+    why: Vendor-neutral migration strategy/ordering — mysql owns the ALGORITHM/gh-ost mechanics, not the theory.
+  - prompt: "Define my schema with Drizzle's table builder and run the generated migration."
+    route_to: drizzle-orm
+    why: ORM/query-builder API ergonomics, not engine-level SQL or InnoDB behaviour.
+
+capability:
+  - scenario: >
+      A MySQL 8.4 query on a large InnoDB orders table is slow: it filters
+      WHERE user_id = ? AND DATE(created_at) = ? ORDER BY created_at DESC and currently
+      does type=ALL. Diagnose and fix it end to end, engine-specifically.
+    must_include:
+      - Runs EXPLAIN / EXPLAIN ANALYZE and reads the access type (ALL→index→range→ref…) plus rows/filtered
+      - Identifies the non-sargable predicate (DATE() wrapping the indexed created_at) and rewrites it to a sargable range
+      - Proposes a composite index with equality column (user_id) first then the range/sort column (created_at), matching WHERE and ORDER BY
+      - Considers a covering index and notes the InnoDB clustered-index PK back-lookup implication
+      - Verifies the new plan with EXPLAIN ANALYZE (type improved, rows dropped, no Using filesort) rather than asserting
+      - Stays engine-specific — does not drift into ORM builder API or PlanetScale deploy-request workflow

package/skills/mysql/references/indexing-and-explain.md

@@ -0,0 +1,161 @@
+# Indexing and EXPLAIN (InnoDB)
+
+Everything here is MySQL 8.4 / MariaDB 11.8 InnoDB behaviour. If the same advice would hold on
+PostgreSQL, it belongs in `sql`, not here.
+
+## The clustered-index model — why PK choice is everything
+
+An InnoDB table *is* its primary-key B-tree. The full row lives in the leaf of the PK index; there
+is no separate heap. Two consequences drive almost every indexing decision:
+
+1. **Every secondary index stores the PK value as its row pointer**, not a physical address. So a
+   wide PK is paid for once per secondary index, per row. A `CHAR(36)` random UUID PK on a table
+   with five secondary indexes carries 36 bytes × 5 copies of the key for every row, on top of the
+   clustered copy. A `BIGINT` PK is 8 bytes.
+2. **Insert locality follows PK order.** A monotonic PK (`BIGINT AUTO_INCREMENT`, ordered UUIDv7)
+   appends to the rightmost leaf — tight, sequential, cache-friendly. A random UUID v4 scatters
+   inserts across the whole B-tree, causing page splits and buffer-pool churn.
+
+```sql
+-- Bad: random UUID as a human-readable CHAR(36) PK.
+CREATE TABLE orders (
+  id CHAR(36) PRIMARY KEY,          -- 36 bytes, random → page splits + fat secondary indexes
+  user_id BIGINT NOT NULL
+) ENGINE=InnoDB;
+
+-- Good: small monotonic surrogate PK; store a public UUID as BINARY(16) if you need one.
+CREATE TABLE orders (
+  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+  public_id BINARY(16) NOT NULL,    -- UUIDv7 packed; ordered, 16 bytes
+  user_id BIGINT NOT NULL,
+  UNIQUE KEY uq_public (public_id)
+) ENGINE=InnoDB;
+```
+
+If you must use a UUID PK, use a time-ordered one (UUIDv7) stored as `BINARY(16)`, never a random
+v4 as `CHAR(36)`.
+
+## The leftmost-prefix rule, worked through
+
+A composite index `INDEX (a, b, c)` is a single sorted B-tree keyed on the tuple `(a, b, c)`. It can
+satisfy a predicate only by reading a *contiguous left prefix* of that tuple:
+
+| Query predicate | Uses the index? | Why |
+|---|---|---|
+| `WHERE a = 1` | Yes (prefix `a`) | leftmost column present |
+| `WHERE a = 1 AND b = 2` | Yes (prefix `a,b`) | contiguous prefix |
+| `WHERE a = 1 AND b = 2 AND c = 3` | Yes (full key) | full prefix |
+| `WHERE a = 1 ORDER BY b` | Yes — sort comes free | `b` is the next key column after the `a` equality |
+| `WHERE b = 2` | No | skips the leftmost column `a` |
+| `WHERE a = 1 AND c = 3` | Partial — only `a` | `b` is missing, so `c` can't be a seek key (used as a filter) |
+| `WHERE a > 1 AND b = 2` | Range on `a` only | a range on an earlier column stops the next column from being a seek key |
+
+The design rule that falls out: **equality columns first, then the single range or `ORDER BY`
+column.** A range predicate "uses up" the index — no column after it can be a seek key, only a
+filter.
+
+```sql
+-- Query: WHERE user_id = ? AND status = ? AND created_at >= ? ORDER BY created_at DESC
+-- Good: two equalities first, then the range/sort column last.
+CREATE INDEX idx_u_s_c ON orders (user_id, status, created_at);
+```
+
+## Covering, prefix, invisible, and functional indexes
+
+**Covering index** — if every column a query touches (SELECT list + WHERE + ORDER BY) is in one
+index, InnoDB answers from the index alone and never walks back to the clustered PK leaf. `EXPLAIN`
+shows `Using index`.
+
+```sql
+SELECT status, total FROM orders WHERE user_id = ?;
+-- Good: index covers the filter AND the selected columns → no PK back-lookup.
+CREATE INDEX idx_cover ON orders (user_id, status, total);
+```
+
+**Prefix index** — index the first N characters of a long `VARCHAR`/`TEXT`. Required for `TEXT`
+(which can't be indexed whole) and useful to shrink a fat key. It can never be a covering index, and
+N must be long enough for selectivity.
+
+```sql
+CREATE INDEX idx_email_prefix ON users (email(20));   -- first 20 chars
+-- Pick N from selectivity: SELECT COUNT(DISTINCT LEFT(email,20))/COUNT(*) FROM users;
+```
+
+**Invisible index** (`INVISIBLE`) — the optimizer ignores it but maintains it. Use it to stage a new
+index on a hot table, or to test "would dropping this index hurt?" without actually dropping it.
+
+```sql
+ALTER TABLE orders ALTER INDEX idx_cover INVISIBLE;   -- test impact; ALTER ... VISIBLE to restore
+```
+
+**Functional / multi-valued index** (8.0.13+) — index an expression so a non-sargable predicate
+becomes sargable without a generated column.
+
+```sql
+CREATE INDEX idx_lower_email ON users ((LOWER(email)));   -- query must use LOWER(email) too
+CREATE INDEX idx_tags ON docs ((CAST(meta->'$.tags' AS UNSIGNED ARRAY)));  -- multi-valued, for JSON arrays
+```
+
+## Reading EXPLAIN field by field
+
+Three forms:
+- `EXPLAIN <q>` — the chosen plan, no execution.
+- `EXPLAIN ANALYZE <q>` — actually runs the query, reports *actual* rows and timing per node.
+- `EXPLAIN FORMAT=JSON <q>` — full cost model, `used_key_parts`, `filtered`, attached conditions.
+
+The **access `type`** is the first thing to read — worst to best:
+
+| `type` | Meaning | Verdict |
+|---|---|---|
+| `ALL` | Full table scan | Bad on a large table |
+| `index` | Full index scan (whole index read) | Usually still too much |
+| `range` | Index range scan (`>`, `BETWEEN`, `IN`) | Good |
+| `ref` | Non-unique index lookup by equality | Good |
+| `eq_ref` | Unique/PK lookup, one row per join row | Great (joins) |
+| `const` / `system` | At most one row, resolved as a constant | Best |
+
+Then read:
+- **`rows`** — *estimated* rows examined at this node. An estimate from stats, not truth — confirm
+  with `EXPLAIN ANALYZE`.
+- **`filtered`** — estimated % of `rows` surviving the `WHERE`. Low `filtered` × high `rows` = the
+  index gets you to the neighbourhood but the predicate isn't selective in the index.
+- **`key`** / **`key_len`** — the chosen index and how many bytes of it were used. A short `key_len`
+  on a composite index means only a prefix was usable.
+- **`Extra`** flags: `Using index` (covering — good), `Using filesort` (a separate sort pass — the
+  index didn't satisfy `ORDER BY`), `Using temporary` (a materialised temp table, common with
+  `GROUP BY`/`DISTINCT` that can't use an index), `Using where` (post-filter after the index).
+
+## Every common "why no index" cause, with the fix
+
+```sql
+-- 1. Function on the indexed column → index unusable.
+-- Bad:
+SELECT * FROM orders WHERE DATE(created_at) = '2026-06-01';
+-- Good (sargable range):
+SELECT * FROM orders WHERE created_at >= '2026-06-01' AND created_at < '2026-06-02';
+
+-- 2. Implicit type cast: VARCHAR column compared to a number → per-row cast, no index.
+-- Bad (phone is VARCHAR):
+SELECT * FROM users WHERE phone = 6041234567;
+-- Good:
+SELECT * FROM users WHERE phone = '6041234567';
+
+-- 3. Charset/collation mismatch on a JOIN key → per-row conversion, no index on the joined side.
+-- Bad: a.code is utf8mb4, b.code is latin1.
+-- Good: make both columns the same charset+collation (ALTER one side), then the join uses the index.
+
+-- 4. Leading wildcard LIKE → no prefix to seek.
+-- Bad:
+SELECT * FROM products WHERE name LIKE '%phone%';
+-- Good (prefix only):
+SELECT * FROM products WHERE name LIKE 'phone%';   -- or a FULLTEXT index for substring search
+
+-- 5. OR across different columns → often defeats a single index.
+-- Bad:
+SELECT * FROM t WHERE a = 1 OR b = 2;
+-- Good: UNION two index-friendly halves, or an index_merge the optimizer can use.
+SELECT * FROM t WHERE a = 1 UNION SELECT * FROM t WHERE b = 2;
+```
+
+After every fix, re-run `EXPLAIN ANALYZE` and confirm the `type` improved and `rows` dropped — the
+plan is the proof, not the rewrite.

package/skills/mysql/references/mysql-vs-mariadb.md

@@ -0,0 +1,78 @@
+# MySQL vs MariaDB divergence
+
+MariaDB began as a MySQL fork and the two have diverged enough that copy-pasted SQL, auth setup, and
+operational assumptions break across them. Always know *which* engine the project runs before you
+answer. This is the depth behind the small table in `SKILL.md`.
+
+## Versions and support
+
+| | MySQL | MariaDB |
+|---|---|---|
+| Current LTS | **8.4 LTS** (GA 2024-04-30, supported through April 2032) | **11.8 LTS** (2025 yearly LTS) |
+| Innovation / short-cycle | **9.x** (9.0 GA 2024-07-01, …, 9.4.0 2025-07-22) | rolling releases between LTS years |
+| Owner | Oracle | MariaDB Foundation / MariaDB plc |
+
+MariaDB version numbers do **not** track MySQL's — MariaDB 11.8 is not "MySQL 11". Feature parity is
+partial and one-directional in places (MariaDB has features MySQL lacks and vice versa).
+
+## Authentication
+
+| | MySQL 8.4 / 9.x | MariaDB 11.8 |
+|---|---|---|
+| Default plugin | `caching_sha2_password` (SHA-256, server-side cache; TLS for first auth) | `mysql_native_password` and `ed25519` |
+| `mysql_native_password` | Disabled by default in 8.4, **removed in 9.0** | Still a first-class plugin |
+
+This is the most common cross-engine connection failure: a client/driver configured for MariaDB's
+native auth hits a MySQL 8.4 server and gets *"Authentication plugin caching_sha2_password cannot be
+loaded"* — fix is a `caching_sha2_password`-aware client over TLS, not re-enabling the old plugin.
+
+## Vector search — NOT drop-in compatible
+
+Both engines added native vector search, but with **incompatible syntax**:
+
+| | MySQL 9.0+ (Innovation only) | MariaDB 11.8 (LTS) |
+|---|---|---|
+| Type | `VECTOR(n)` — 4-byte floats, default max 2048, max 16383 entries | `VECTOR(n)` |
+| Parse / format | `STRING_TO_VECTOR()` / `TO_VECTOR()`, `VECTOR_TO_STRING()` / `FROM_VECTOR()` | `VEC_FromText()` / `VEC_ToText()` |
+| Distance | distance functions per the 9.x line | `VEC_DISTANCE_EUCLIDEAN()`, `VEC_DISTANCE_COSINE()`, `VEC_DISTANCE()` |
+| Acceleration | — | SIMD (AVX2/AVX512/ARM/Power10) |
+| Key constraint | A `VECTOR` column **cannot be any kind of key** (no PK/FK/UK/partition) | indexable for approximate search |
+| LTS availability | **Not in 8.4 LTS** — Innovation 9.x only | In the 11.8 LTS line |
+
+If a project needs vector search on a conservative LTS today, MariaDB 11.8 has it in LTS; MySQL only
+has it on the short-lived 9.x Innovation track. The SQL is not portable between them — pick one and
+write to its functions.
+
+## Snapshot isolation
+
+MariaDB 11.8 ships `innodb_snapshot_isolation` defaulting **ON**, which makes a `REPEATABLE READ`
+transaction *detect write conflicts* (raising an error instead of silently applying a stale-snapshot
+write). Stock MySQL `REPEATABLE READ` does **not** do this — it gives a consistent snapshot but no
+write-conflict detection. Code that relies on MariaDB raising a conflict error will silently succeed
+(and possibly lose an update) on MySQL, and vice versa code that doesn't expect the error will fail
+on MariaDB.
+
+## Other SQL surface divergences
+
+| Feature | MySQL | MariaDB |
+|---|---|---|
+| `RETURNING` | `INSERT ... RETURNING` only (8.0+) | `INSERT` / `UPDATE` / `DELETE ... RETURNING` |
+| Sequences | No `CREATE SEQUENCE` (use `AUTO_INCREMENT`) | `CREATE SEQUENCE` supported |
+| System-versioned (temporal) tables | Not supported | `WITH SYSTEM VERSIONING` + `FOR SYSTEM_TIME` queries |
+| `JSON` type | Native binary `JSON` | Historically a `LONGTEXT` alias with JSON functions; check the version — behaviour and storage differ |
+| Optimizer / hints | Oracle-style optimizer, `/*+ HINT */` hint syntax, hypergraph optimizer in newer Innovation | Different optimizer, different hint set and defaults; plans differ for the same query |
+| Storage engines | InnoDB-centric | InnoDB plus Aria, ColumnStore, Spider, etc. |
+
+## Migration gotchas, both directions
+
+- **MariaDB → MySQL**: drop reliance on sequences, system-versioned tables, multi-statement
+  `RETURNING`, and the snapshot-isolation conflict behaviour. Re-check JSON columns. Re-key any
+  vector columns and rewrite vector SQL.
+- **MySQL → MariaDB**: auth changes (native/ed25519 vs caching_sha2_password); rewrite MySQL 9
+  vector SQL to `VEC_*`; expect `innodb_snapshot_isolation=ON` to start raising conflict errors your
+  app didn't see before; verify optimizer-hint syntax and re-test query plans.
+- **Don't trust `mysqldump` round-trips blindly** across engines — types, charsets, and engine
+  clauses can differ. Dump, then read the DDL before loading into the other engine.
+
+Bottom line: treat MySQL and MariaDB as two different databases that happen to share a wire protocol
+and a lot of grammar. Confirm the engine, then write to its specifics.