For AI / Vibe-Coding Developers

Using MariaDB effectively from Cursor, Claude Code, Windsurf and other agent workflows

This page is where this site diverges most from official MariaDB docs. The official material is written for DBAs; today's developers increasingly touch the database through an LLM. These patterns haven't been collected anywhere.

1. LLM-friendly schemas

Without comments, LLMs guess column meanings — sometimes wrong. Adding structured COMMENT to every table and column is the cheapest accuracy win you'll ever get.

CREATE TABLE orders (
  id            BIGINT AUTO_INCREMENT PRIMARY KEY
                COMMENT 'Globally-unique order id',
  user_id       BIGINT NOT NULL
                COMMENT 'FK -> users.id, the customer',
  amount_cents  INT NOT NULL
                COMMENT 'Order total in cents (USD)',
  status        ENUM('pending','paid','shipped','cancelled') NOT NULL
                COMMENT 'pending -> paid -> shipped; can be cancelled from any state',
  created_at    DATETIME DEFAULT CURRENT_TIMESTAMP
                COMMENT 'Server local time',
  INDEX idx_user_created (user_id, created_at)
) COMMENT='E-commerce orders';

Pull these into the agent's context via INFORMATION_SCHEMA.COLUMNS.COLUMN_COMMENT. Accuracy jumps.

Naming for agents

✅ Prefer	❌ Avoid	Why
`order_amount_cents`	`oac`, `amt2`	Abbreviations mislead the model
`is_active`	`flag1`	Boolean prefix is universal
`created_at` / `updated_at`	`ctime` / `mtime`	Industry standard
ENUM for status	string codes	Enum values appear in the schema

2. Wire MariaDB into MCP

Model Context Protocol lets AI clients talk to external systems safely. MariaDB plugs into any MySQL MCP server since the wire protocol is compatible.

~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "mariadb-playground": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_USER": "readonly",
        "MYSQL_PASSWORD": "xxx",
        "MYSQL_DATABASE": "playground"
      }
    }
  }
}

~/.cursor/mcp.json — same shape.

Always give MCP a read-only user scoped to a specific database. Agent mistakes are more expensive than human ones.

3. Safe write patterns for agents

Don't let an agent run UPDATE / DELETE directly against production. Pick one:

A. Shadow tables — agent writes to staging_*, a CI job diffs, human merges.

B. Transactional with row-count guard

START TRANSACTION;
UPDATE orders SET status='cancelled' WHERE user_id = 42;
SELECT ROW_COUNT();   -- if wildly above expectation, ROLLBACK

C. App-layer tools, not raw SQL — expose cancel_order(order_id) with typed args; tool uses prepared statements internally. This is the default for production.

4. Vector search — yes, in MariaDB

MariaDB 11.8+ ships a native VECTOR type with HNSW indexing. You don't need pgvector / Pinecone / Qdrant for RAG anymore.

CREATE TABLE doc_chunks (
  id       BIGINT AUTO_INCREMENT PRIMARY KEY,
  content  TEXT,
  embed    VECTOR(1536) NOT NULL,
  VECTOR INDEX (embed)
);

SELECT id, content,
       VEC_DISTANCE_EUCLIDEAN(embed, VEC_FromText('[0.1,0.2,...]')) AS dist
FROM doc_chunks
ORDER BY dist LIMIT 5;

5. Drop-in vibe-coding rules

Paste into your Cursor / Claude Code rules file:

## MariaDB rules
- charset utf8mb4 with utf8mb4_unicode_ci; never utf8
- PK is always BIGINT AUTO_INCREMENT; no business field as PK
- monetary columns use *_cents INT/BIGINT, never floats
- timestamps: created_at, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
- UPDATE/DELETE must have WHERE; bare-table mutations need '-- intentional: full table'
- default engine InnoDB; never MyISAM
- no SELECT *; list columns