@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/windsurf/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/windsurf/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/windsurf/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/windsurf/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/windsurf/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

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/mysql/references/query-indexing.md

@@ -0,0 +1,104 @@
+# MySQL — Query Optimization and Indexing
+
+## EXPLAIN workflow
+
+Always run `EXPLAIN` (or `EXPLAIN ANALYZE`) before and after index changes.
+
+```sql
+EXPLAIN SELECT * FROM orders WHERE user_id = 42 ORDER BY created_at DESC LIMIT 20;
+EXPLAIN ANALYZE SELECT ...;  -- MySQL 8.0+: shows actual row counts and timing
+```
+
+Key columns to read:
+
+| Column | Red flag |
+| --- | --- |
+| `type` | `ALL` = full table scan. Target: `ref`, `eq_ref`, `range`, or `const`. |
+| `Extra` | `Using filesort` = no index satisfying ORDER BY. `Using temporary` = costly in-memory or on-disk sort. |
+| `rows` | Estimated rows examined. Should be close to rows returned. |
+| `key` | Which index MySQL chose. `NULL` = no index used. |
+
+## Composite index design (leftmost prefix rule)
+
+- Column order is critical: **equality predicates first, then range, then sort**.
+- The planner can use any leading prefix of the index — trailing columns after a range stop being used.
+- **Good**: `(status, user_id, created_at)` for `WHERE status = 'open' AND user_id = 42 ORDER BY created_at`.
+- **Bad**: `(created_at, status)` for `WHERE status = 'open'` — planner must scan the whole index.
+
+```sql
+-- Supports: WHERE status = ? ORDER BY created_at
+-- Supports: WHERE status = ? AND user_id = ?
+CREATE INDEX idx_orders_status_user_created ON orders (status, user_id, created_at);
+```
+
+## Covering indexes
+
+Include all selected columns in the index to avoid a heap row lookup (index-only read).
+
+```sql
+-- Query: SELECT status, total FROM orders WHERE user_id = 42
+CREATE INDEX idx_orders_user_covering ON orders (user_id) INCLUDE (status, total);
+-- Or in older MySQL without INCLUDE, use a composite key that covers the columns
+```
+
+Range predicates in the key stop the index from being used for subsequent columns — use `INCLUDE`-style or a separate index for those.
+
+## Seek (cursor) pagination — avoid OFFSET
+
+`OFFSET N` forces MySQL to scan and discard N rows. On large tables this is catastrophically slow.
+
+```sql
+-- BAD: OFFSET pagination
+SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 10000;
+
+-- GOOD: Seek pagination using last seen ID
+SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;
+
+-- For composite sort keys
+SELECT * FROM orders
+WHERE (created_at, id) < (:last_created_at, :last_id)
+ORDER BY created_at DESC, id DESC
+LIMIT 20;
+```
+
+## Function calls on indexed columns break index usage
+
+```sql
+-- BAD: function call prevents index use
+SELECT * FROM users WHERE YEAR(created_at) = 2025;
+
+-- GOOD: range predicate preserves index
+SELECT * FROM users WHERE created_at >= '2025-01-01' AND created_at < '2026-01-01';
+```
+
+## Index maintenance
+
+```sql
+-- Find unused indexes (after collecting stats for a while)
+SELECT object_schema, object_name, index_name, count_read
+FROM performance_schema.table_io_waits_summary_by_index_usage
+WHERE count_read = 0 AND object_schema NOT IN ('mysql', 'sys', 'information_schema')
+ORDER BY object_schema, object_name;
+
+-- Check index sizes
+SELECT table_name, index_name, stat_value * @@innodb_page_size / 1024 / 1024 AS size_mb
+FROM mysql.innodb_index_stats
+WHERE stat_name = 'size' AND database_name = DATABASE()
+ORDER BY size_mb DESC;
+```
+
+- Drop indexes with `count_read = 0` — every index adds write and lock overhead.
+- Use `ALTER TABLE ... ADD INDEX ..., ALGORITHM=INPLACE, LOCK=NONE` for online index changes.
+
+## Key guardrails
+
+- Avoid leading `%` in LIKE (`LIKE '%foo'`) — can't use a B-tree index.
+- Avoid `OR` across different indexed columns — use `UNION ALL` instead.
+- Avoid implicit type coercions in `WHERE` (e.g., `WHERE varchar_col = 123`) — breaks index usage.
+- Batch large INSERTs (500–5000 rows per statement) to reduce per-statement overhead.
+
+## Sources
+- Using EXPLAIN: https://dev.mysql.com/doc/refman/8.4/en/using-explain.html
+- Optimization and indexes: https://dev.mysql.com/doc/refman/8.4/en/optimization-indexes.html
+- LIMIT/OFFSET optimization: https://dev.mysql.com/doc/refman/8.4/en/limit-optimization.html
+- performance_schema index stats: https://dev.mysql.com/doc/refman/8.4/en/table-io-waits-summary-by-index-usage-table.html