@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: database-skills
+description: Unified database skill hub with engine-specific packs for PostgreSQL, MySQL, Vitess, Neki, MongoDB (Mongoose), SQLite, Supabase, and Redis.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+metadata:
+  version: "2.0.0"
+  domain: data
+  triggers: database, sql, postgres, mysql, vitess, neki, mongodb, mongoose, sqlite, supabase, redis, schema, migration, index, query, performance, pagination, replication, pooling, sharding, cache
+---
+
+# Database Skills Hub
+
+Use this as the primary database hub. Keep `database-design`, `database-optimizer`, and `drift-flutter` available for specialized/legacy-compatible flows. Load the target engine's `SKILL.md` from `skills/<engine>/`, then load relevant `references/*` files.
+
+## Engine selection
+
+| Situation | Engine |
+| --- | --- |
+| Relational OLTP, self-hosted or cloud | Postgres |
+| Relational OLTP, MySQL-compatible managed service | MySQL + Vitess (PlanetScale) |
+| Multi-tenant SaaS needing horizontal Postgres scale | Neki |
+| Document model, flexible schema | MongoDB |
+| Mobile / desktop / edge local storage | SQLite |
+| BaaS with built-in auth, storage & realtime | Supabase |
+| Caching, queues, leaderboards, pub/sub | Redis |
+
+## Structure
+
+```
+skills/
+  postgres/
+    SKILL.md
+    references/
+      schema-indexing.md       ← index types, composite, partial, INCLUDE
+      performance-ops.md       ← EXPLAIN, pg_stat_statements, VACUUM, autovacuum
+      migrations.md            ← zero-downtime DDL, expand/contract, tools
+      connection-pooling.md    ← PgBouncer, pool sizing, serverless patterns
+
+  mysql/
+    SKILL.md
+    references/
+      query-indexing.md        ← EXPLAIN, composite indexes, covering, seek pagination
+      locking-ddl.md           ← INSTANT/INPLACE/COPY, MDL, gh-ost, deadlocks
+      replication.md           ← binlog formats, GTID, lag monitoring, read routing
+
+  vitess/
+    SKILL.md
+    references/
+      sharding-routing.md      ← VSchema, vindexes, sequences, scatter queries
+      operational-safety.md    ← Online DDL strategies, migration lifecycle, VReplication
+
+  neki/
+    SKILL.md
+    references/
+      architecture.md          ← sharded Postgres architecture, pre-sharding checklist
+      operations.md            ← migration planning, validation, provisional pre-GA guidance
+
+  mongodb/
+    SKILL.md
+    references/
+      modeling.md              ← embed vs reference, compound indexes, explain(), pagination
+      mongoose-nestjs.md       ← repository pattern, lean reads, transactions, NestJS setup
+      aggregation.md           ← pipeline stages, $group, $lookup, $facet, performance
+
+  sqlite/
+    SKILL.md
+    references/
+      local-first.md           ← WAL mode, migration patterns, sync/conflict strategies
+      performance.md           ← EXPLAIN QUERY PLAN, indexes, batch writes, checkpoint tuning
+
+  supabase/
+    SKILL.md
+    references/
+      rls-auth.md              ← RLS policies, auth.uid(), index predicates, service_role
+      performance-operations.md ← query optimization, connection modes, pooler selection
+
+  redis/
+    SKILL.md
+    references/
+      data-modeling.md         ← data structure selection, key naming, TTL strategy
+      cache-patterns.md        ← pipelining, SCAN, rate limiting, leaderboards, invalidation
+      operations.md            ← memory management, eviction policies, latency diagnostics
+```
+
+## Required flow
+
+1. Read `LATEST_VERSIONS.md` before proposing version-specific behavior.
+2. Use engine selection table above to pick the target engine.
+3. Load the target engine `SKILL.md` and relevant `references/*` files — read the ones that match the task (indexing, migrations, replication, etc.).
+4. Provide an optimization or implementation plan that includes:
+   - specific change with rationale,
+   - indexing or schema decisions,
+   - migration safety (online vs offline),
+   - rollback path.
+5. For production-impacting changes, include blast-radius assessment and rollout stages.
+
+## Cross-engine performance checklist
+
+- **Indexing**: add indexes only for real predicates and sort patterns. Drop unused indexes — they penalize writes.
+- **Pagination**: prefer keyset/seek for deep or high-throughput pagination. Reserve offset for shallow interactive pages only.
+- **Measurement**: compare before/after plans with engine-native explain tooling (`EXPLAIN ANALYZE`, `VEXPLAIN`, `explain()`). Validate with realistic cardinality.
+- **Safety**: no destructive data/schema operations without explicit user confirmation. Always include rollback/recovery steps.

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/skills/mongodb/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: mongodb
+description: MongoDB and Mongoose modeling, indexing, pagination, query tuning, and transaction guidance.
+---
+
+# MongoDB and Mongoose
+
+## Optimization workflow
+
+1. Model around dominant read/write paths (embed vs reference).
+2. Add compound indexes for real filter + sort patterns.
+3. Validate with `explain("executionStats")`.
+4. Prefer range/keyset pagination over deep `skip`.
+5. Re-check index selectivity and write overhead as data grows.
+
+## Indexing techniques
+
+- Compound indexes over isolated single-field indexes when query shape demands it.
+- Keep index count controlled on write-heavy collections.
+- Use partial/sparse strategies only when semantics are correct.
+
+## Pagination techniques
+
+- Avoid large-offset `skip` on large collections.
+- Use boundary-based pagination with indexed monotonic key (`_id` or timestamp+id).
+- Keep deterministic sort and cursor boundary state.
+
+## Mongoose/NestJS guardrails
+
+- Keep schema indexes explicit in model definitions/migrations.
+- Use projections to avoid over-fetching large documents.
+- Use transactions only when cross-document invariants require them.
+
+## References
+
+- `references/modeling.md`
+- `references/mongoose-nestjs.md`

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/skills/mongodb/references/aggregation.md

@@ -0,0 +1,153 @@
+# MongoDB — Aggregation Pipeline
+
+## Pipeline basics
+
+The aggregation pipeline is a sequence of stages, each transforming the document stream. Stages execute in order.
+
+```js
+db.orders.aggregate([
+  { $match: { status: 'complete', userId: 'u42' } },  // filter early
+  { $group: { _id: '$category', total: { $sum: '$amount' }, count: { $sum: 1 } } },
+  { $sort: { total: -1 } },
+  { $limit: 10 },
+  { $project: { category: '$_id', total: 1, count: 1, _id: 0 } }
+])
+```
+
+**Critical rule**: Put `$match` as early as possible to reduce documents flowing through subsequent stages. MongoDB can use indexes for `$match` at the start of a pipeline.
+
+## Common stages
+
+| Stage | Purpose |
+| --- | --- |
+| `$match` | Filter documents (use early, supports indexes) |
+| `$group` | Group by key, apply accumulators (`$sum`, `$avg`, `$min`, `$max`, `$push`, `$addToSet`) |
+| `$project` | Reshape documents (include/exclude/rename/compute fields) |
+| `$sort` | Sort (can use index when at start, before `$group`) |
+| `$limit` / `$skip` | Pagination (prefer range-based — see below) |
+| `$lookup` | Left outer join to another collection |
+| `$unwind` | Flatten an array field into individual documents |
+| `$addFields` | Add computed fields without removing existing |
+| `$facet` | Run multiple sub-pipelines in parallel (for multi-category aggregation) |
+| `$bucket` | Group into ranges (histogram) |
+| `$count` | Count documents |
+| `$out` / `$merge` | Write results to a collection |
+
+## $group accumulators
+
+```js
+{ $group: {
+  _id: '$category',
+  total:    { $sum: '$amount' },           // sum
+  average:  { $avg: '$amount' },           // average
+  max:      { $max: '$amount' },           // max
+  min:      { $min: '$amount' },           // min
+  count:    { $sum: 1 },                   // count rows
+  products: { $push: '$productId' },       // array of all values (duplicates kept)
+  unique:   { $addToSet: '$productId' },   // array of unique values
+  first:    { $first: '$createdAt' },      // first value in group
+}}
+```
+
+## $lookup — joins
+
+```js
+// Left join orders with users
+db.orders.aggregate([
+  { $match: { status: 'complete' } },
+  { $lookup: {
+    from: 'users',
+    localField: 'userId',
+    foreignField: '_id',
+    as: 'user'
+  }},
+  { $unwind: { path: '$user', preserveNullAndEmptyArrays: true } },
+  { $project: { total: 1, 'user.name': 1, 'user.email': 1 } }
+])
+```
+
+`$lookup` is expensive on large collections — **prefer embedding** if data is always accessed together. Always filter with `$match` before `$lookup` to minimize joined documents.
+
+Pipeline-style `$lookup` (MongoDB 3.6+) for filtered joins:
+```js
+{ $lookup: {
+  from: 'orderItems',
+  let: { orderId: '$_id' },
+  pipeline: [
+    { $match: { $expr: { $eq: ['$orderId', '$$orderId'] } } },
+    { $project: { sku: 1, qty: 1, _id: 0 } }
+  ],
+  as: 'items'
+}}
+```
+
+## $unwind
+
+Flattens array fields — generates one output document per array element:
+
+```js
+// Input: { _id: 1, tags: ['a', 'b', 'c'] }
+{ $unwind: '$tags' }
+// Output: { _id: 1, tags: 'a' }, { _id: 1, tags: 'b' }, { _id: 1, tags: 'c' }
+```
+
+Watch out: `$unwind` on an array of 1000 elements turns 1 doc into 1000. Use `preserveNullAndEmptyArrays: true` to keep docs with missing/empty arrays.
+
+## Pagination in aggregation
+
+Avoid `$skip` for deep pagination — it scans all skipped docs.
+
+```js
+// BAD: $skip is O(N)
+db.orders.aggregate([
+  { $sort: { createdAt: -1 } },
+  { $skip: 10000 },
+  { $limit: 20 }
+])
+
+// GOOD: range-based pagination
+db.orders.aggregate([
+  { $match: { createdAt: { $lt: lastSeenDate }, _id: { $lt: lastSeenId } } },
+  { $sort: { createdAt: -1, _id: -1 } },
+  { $limit: 20 }
+])
+```
+
+## $facet — parallel aggregations
+
+Run multiple sub-pipelines against the same input in one pass:
+
+```js
+db.products.aggregate([
+  { $match: { active: true } },
+  { $facet: {
+    byCategory: [
+      { $group: { _id: '$category', count: { $sum: 1 } } }
+    ],
+    priceRange: [
+      { $bucket: { groupBy: '$price', boundaries: [0, 50, 100, 200, 500], default: '500+' } }
+    ],
+    total: [
+      { $count: 'count' }
+    ]
+  }}
+])
+```
+
+## Performance tips
+
+- **Index for `$match` and `$sort`**: the pipeline can use an index only for `$match` and `$sort` stages that appear before any `$group`/`$project`/`$unwind`.
+- **Use `allowDiskUse: true`** for large aggregations that exceed the 100MB in-memory sort limit.
+- **`$project` early** to reduce document size flowing through the pipeline.
+- **Avoid `$lookup` on hot paths** — cache results or redesign schema to embed.
+- **Use `$merge` to pre-compute** expensive aggregations into a results collection, then query that.
+
+```js
+// Run explain on aggregation
+db.orders.explain('executionStats').aggregate([...])
+```
+
+## Sources
+- Aggregation pipeline: https://www.mongodb.com/docs/manual/aggregation/
+- Pipeline stages reference: https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/
+- Aggregation performance: https://www.mongodb.com/docs/manual/core/aggregation-pipeline-optimization/

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/skills/mongodb/references/modeling.md

@@ -0,0 +1,96 @@
+# MongoDB — Modeling, Indexing, and Pagination
+
+## Data modeling philosophy
+
+MongoDB is schema-flexible at the storage layer, but **your schema is defined by your queries, not by your data shape**. Model documents for the queries you actually run.
+
+### Embed vs reference
+
+| Embed | Reference (DBRef / manual) |
+| --- | --- |
+| Data is always accessed together | Data is accessed independently |
+| 1-to-1 or bounded 1-to-few | 1-to-many with unbounded growth |
+| Child data has no standalone identity | Child data is queried on its own |
+| Written/updated together | Updated at different rates |
+
+```js
+// Embed: order with line items (always fetched together, bounded count)
+{ _id: ..., userId: ..., lineItems: [ { sku, qty, price }, ... ] }
+
+// Reference: user with orders (orders accessed independently, unbounded)
+{ _id: ..., name: "Alice" }   // users collection
+{ _id: ..., userId: <ref>, total: 99 }  // orders collection
+```
+
+Avoid embedding unbounded arrays — document size limit is 16MB and large docs slow query/update performance.
+
+## Index types and when to use them
+
+| Type | Use for |
+| --- | --- |
+| **Single field** | Equality, range, sort on one field |
+| **Compound** | Combined equality + range + sort — column order matters |
+| **Multikey** | Fields that are arrays (auto-detected by MongoDB) |
+| **Text** | Full-text search on string fields |
+| **Wildcard** | Arbitrary field access patterns |
+| **2dsphere** | Geospatial queries |
+| **TTL** | Auto-delete documents after expiry |
+
+## Compound index design
+
+Same leftmost-prefix rule as SQL — **equality fields first, then range, then sort**:
+
+```js
+// Query: find open orders for a user, sorted by date
+db.orders.find({ userId: X, status: "open" }).sort({ createdAt: -1 })
+
+// Correct index: equality fields lead, sort field last
+db.orders.createIndex({ userId: 1, status: 1, createdAt: -1 })
+
+// Wrong: sort field before filter — doesn't eliminate docs efficiently
+db.orders.createIndex({ createdAt: -1, userId: 1, status: 1 })
+```
+
+## Reading query plans with explain()
+
+```js
+db.orders.find({ userId: 1 }).explain("executionStats")
+```
+
+Key things to check:
+- `winningPlan.stage`: `COLLSCAN` = full scan (bad on large collections), `IXSCAN` = index scan (good).
+- `executionStats.totalDocsExamined` vs `nReturned`: should be close. Large ratio = poor index coverage.
+- `executionStats.executionTimeMillis`: baseline to compare before/after index changes.
+
+## Avoid deep skip() pagination
+
+`skip(N)` makes MongoDB scan and discard N documents. On large collections this is O(N).
+
+```js
+// BAD: skip-based pagination
+db.orders.find().sort({ _id: 1 }).skip(10000).limit(20)
+
+// GOOD: range-based pagination using last seen _id (or cursor field)
+db.orders.find({ _id: { $gt: lastSeenId } }).sort({ _id: 1 }).limit(20)
+
+// For composite sort keys
+db.orders.find({
+  $or: [
+    { createdAt: { $lt: lastDate } },
+    { createdAt: lastDate, _id: { $lt: lastId } }
+  ]
+}).sort({ createdAt: -1, _id: -1 }).limit(20)
+```
+
+## Common modeling mistakes
+
+- **Storing growing arrays in a document**: the document grows without bound → move to a child collection.
+- **Using `$lookup` as a substitute for embedding**: `$lookup` is expensive; redesign the schema if you always join.
+- **Not projecting fields**: always project only needed fields to reduce document transfer size.
+- **Missing index on high-cardinality filter fields**: every `find()` cold path should have an index.
+
+## Sources
+- Explain plans: https://www.mongodb.com/docs/manual/reference/method/db.collection.explain/
+- `skip()` caveats: https://www.mongodb.com/docs/manual/reference/method/cursor.skip/
+- Query plans: https://www.mongodb.com/docs/manual/core/query-plans/
+- Data modeling guide: https://www.mongodb.com/docs/manual/data-modeling/

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/skills/mongodb/references/mongoose-nestjs.md

@@ -0,0 +1,134 @@
+# MongoDB — Mongoose and NestJS Patterns
+
+## Repository pattern with Mongoose + NestJS
+
+Keep data access behind a repository class — don't scatter `Model.find()` calls across services.
+
+```ts
+// order.repository.ts
+@Injectable()
+export class OrderRepository {
+  constructor(@InjectModel(Order.name) private model: Model<Order>) {}
+
+  async findByUser(userId: string, limit = 20, afterId?: string): Promise<Order[]> {
+    const query: FilterQuery<Order> = { userId };
+    if (afterId) query._id = { $gt: new Types.ObjectId(afterId) };
+    return this.model
+      .find(query)
+      .sort({ _id: 1 })
+      .limit(limit)
+      .lean()   // return plain JS objects — skip Mongoose hydration overhead
+      .exec();
+  }
+
+  async create(dto: CreateOrderDto): Promise<Order> {
+    return this.model.create(dto);
+  }
+}
+```
+
+## Schema index definition
+
+Define indexes on the schema, not as ad-hoc calls. This makes them part of your codebase and reviewable.
+
+```ts
+@Schema({ timestamps: true })
+export class Order {
+  @Prop({ required: true, index: true })
+  userId: string;
+
+  @Prop({ required: true })
+  status: string;
+
+  @Prop({ type: [{ sku: String, qty: Number, price: Number }] })
+  lineItems: LineItem[];
+}
+
+// Compound index — define at schema level
+OrderSchema.index({ userId: 1, status: 1, createdAt: -1 });
+
+// TTL index — auto-delete after 90 days
+OrderSchema.index({ createdAt: 1 }, { expireAfterSeconds: 60 * 60 * 24 * 90 });
+```
+
+Always track index definitions in migration scripts when adding to existing collections.
+
+## Lean reads and projection
+
+- `lean()` returns plain JS objects instead of Mongoose Document instances — no hydration overhead, no change tracking. Use for read paths.
+- Always project only what you need to reduce transfer size.
+
+```ts
+// Lean + projection for list endpoints
+this.model
+  .find({ userId })
+  .select('status createdAt total')   // project only needed fields
+  .lean()
+  .exec();
+
+// Full document with Mongoose methods only when saving/updating
+const doc = await this.model.findById(id).exec();
+doc.status = 'complete';
+await doc.save();
+```
+
+## Transactions (MongoDB 4.0+ replica set or sharded cluster)
+
+```ts
+const session = await this.connection.startSession();
+session.startTransaction();
+try {
+  await this.orderModel.create([orderData], { session });
+  await this.inventoryModel.updateOne(
+    { sku: orderData.sku },
+    { $inc: { qty: -1 } },
+    { session }
+  );
+  await session.commitTransaction();
+} catch (e) {
+  await session.abortTransaction();
+  throw e;
+} finally {
+  session.endSession();
+}
+```
+
+Transactions are only needed for multi-document atomicity. Single-document operations are always atomic in MongoDB.
+
+## Aggregation pipeline in NestJS
+
+```ts
+const result = await this.model.aggregate([
+  { $match: { userId, status: 'complete' } },
+  { $group: { _id: '$category', total: { $sum: '$amount' } } },
+  { $sort: { total: -1 } },
+  { $limit: 10 },
+]);
+```
+
+Use `.aggregate()` for reporting/analytics. For regular queries, prefer `.find()` so Mongoose can apply schema type casting.
+
+## Connection and pool setup (NestJS module)
+
+```ts
+MongooseModule.forRoot(uri, {
+  maxPoolSize: 10,          // default 5 — tune to app concurrency
+  serverSelectionTimeoutMS: 5000,
+  socketTimeoutMS: 45000,
+  connectTimeoutMS: 10000,
+})
+```
+
+## Common mistakes
+
+- Calling `Model.find()` directly in service/controller — bypasses repository, untestable.
+- Forgetting `.lean()` on list endpoints — returns Mongoose Documents with full overhead.
+- Defining compound indexes ad-hoc in `onModuleInit` — use schema-level definition instead.
+- Not projecting fields on list queries — transfers full documents when only 3 fields are needed.
+- Using `new Model(data).save()` in a loop — batch with `Model.insertMany()` instead.
+
+## Sources
+- Mongoose documentation: https://mongoosejs.com/docs/
+- MongoDB index strategies: https://www.mongodb.com/docs/manual/indexes/
+- MongoDB data modeling: https://www.mongodb.com/docs/manual/data-modeling/
+- MongoDB transactions: https://www.mongodb.com/docs/manual/core/transactions/

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/skills/mysql/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: mysql
+description: MySQL/InnoDB schema design, indexing, pagination, query tuning, and operational safety.
+---
+
+# MySQL
+
+## Version posture
+
+- Prefer **8.4 LTS** for long-lived production stability.
+- Use **9.x Innovation** only when you need newest features and can absorb faster change cadence.
+
+## Optimization workflow
+
+1. Baseline with `EXPLAIN` and `EXPLAIN ANALYZE`.
+2. Tune indexes around dominant filter and sort paths.
+3. Validate pagination path (`ORDER BY` + index coverage).
+4. Evaluate DDL lock/replication impact before migration.
+
+## Indexing techniques
+
+- Composite indexes that match predicate and ordering direction.
+- Covering indexes for hot read endpoints.
+- Keep clustered primary key narrow to reduce secondary index overhead.
+- Avoid shotgun indexing; measure write amplification impact.
+
+## Pagination techniques
+
+- Prefer seek/keyset pagination with deterministic ordering.
+- Include unique tie-breaker for stable page boundaries.
+- Avoid large offset pagination for deep traversal.
+
+## Operational guardrails
+
+- Treat online DDL mode and lock behavior as explicit rollout risks.
+- Test DDL on production-like data volume and replica topology.
+
+## References
+
+- `references/query-indexing.md`
+- `references/locking-ddl.md`

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/database-skills/skills/mysql/references/locking-ddl.md

@@ -0,0 +1,104 @@
+# MySQL — Locking and DDL Safety
+
+## Online DDL algorithms
+
+MySQL InnoDB can perform many DDL operations without blocking reads/writes. Always check the algorithm before running in production.
+
+| Algorithm | Write impact | When used |
+| --- | --- | --- |
+| `INSTANT` | None | Adding nullable columns at end (MySQL 8.0+), some metadata-only |
+| `INPLACE` | No copy; may block briefly at start/end | Most index adds, some column modifications |
+| `COPY` | Full table rewrite; blocks writes for duration | Changing primary key, column type changes, some charset changes |
+
+Check before applying:
+```sql
+ALTER TABLE orders ADD COLUMN notes TEXT, ALGORITHM=INPLACE, LOCK=NONE;
+-- If MySQL rejects it, it needs COPY → use pt-online-schema-change or gh-ost
+```
+
+Force dry-run check without applying:
+```sql
+-- Will error if it can't do INPLACE, without touching the table
+ALTER TABLE orders ADD INDEX idx_test (status), ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+## Metadata lock (MDL) exposure
+
+DDL acquires a Metadata Lock on the table. Even an `INSTANT` or `INPLACE` operation blocks if a long-running transaction or idle connection holds a conflicting MDL.
+
+```sql
+-- Check for MDL waiters and holders before running DDL
+SELECT r.trx_id waiting_trx_id, r.trx_mysql_thread_id waiting_thread,
+       b.trx_id blocking_trx_id, b.trx_mysql_thread_id blocking_thread,
+       b.trx_query blocking_query
+FROM information_schema.innodb_lock_waits w
+JOIN information_schema.innodb_trx b ON b.trx_id = w.blocking_trx_id
+JOIN information_schema.innodb_trx r ON r.trx_id = w.requesting_trx_id;
+
+-- Also check for long-running active transactions
+SELECT * FROM information_schema.innodb_trx WHERE trx_started < NOW() - INTERVAL 30 SECOND;
+```
+
+Kill blockers with caution before DDL:
+```sql
+KILL <thread_id>;   -- kills connection, rolls back its transaction
+```
+
+## Replication lag impact
+
+- `COPY` algorithm: full table rewrite flows through binary log as row events — replica must replay every row.
+- `INPLACE` lock-free DDL: usually light on replicas.
+- Monitor `Seconds_Behind_Master` / `Seconds_Behind_Source` during DDL.
+
+```sql
+-- On replica
+SHOW REPLICA STATUS\G
+-- Watch: Seconds_Behind_Source
+```
+
+## Online schema change tools
+
+For tables too large or busy for native online DDL:
+- **gh-ost** (GitHub): uses binlog streaming, minimal impact, best for production.
+- **pt-online-schema-change** (Percona): trigger-based, established tooling.
+
+Both create a shadow table, migrates data in background, then atomically cuts over with a brief lock.
+
+## InnoDB row-level locking
+
+- InnoDB locks rows, not tables (except DDL).
+- `SELECT ... FOR UPDATE` takes exclusive row locks — keep duration short.
+- `REPEATABLE READ` (default) uses **gap locks** to prevent phantom reads; causes more lock contention than `READ COMMITTED`.
+- Switch to `READ COMMITTED` for high-contention OLTP workloads:
+  ```sql
+  SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED;
+  ```
+
+## Deadlock handling
+
+```sql
+-- Show last deadlock detail
+SHOW ENGINE INNODB STATUS\G  -- search for LATEST DETECTED DEADLOCK
+
+-- Enable deadlock logging
+SET GLOBAL innodb_print_all_deadlocks = ON;
+```
+
+Prevention:
+- Always access rows in a consistent order across transactions.
+- Keep transactions short — do I/O and computation outside the transaction boundary.
+- Retry with exponential backoff on error 1213 (`ER_LOCK_DEADLOCK`).
+
+## MySQL release tracks
+
+| Track | Description |
+| --- | --- |
+| **LTS** (e.g. 8.4, 9.7+) | Long-term support; production recommended |
+| **Innovation** (8.1, 8.2, etc.) | Frequent releases with new features, shorter support window |
+
+Check which features are available for your version before proposing DDL changes.
+
+## Sources
+- Online DDL operations: https://dev.mysql.com/doc/refman/8.4/en/innodb-online-ddl-operations.html
+- InnoDB locking: https://dev.mysql.com/doc/refman/8.4/en/innodb-locking.html
+- MySQL release tracks: https://dev.mysql.com/doc/refman/8.4/en/mysql-releases.html