# AxarDB Cloud — AI Agent & LLM Quickstart Guide

> AxarDB Cloud (https://axardb.com) is a high-performance in-memory NoSQL database service running on distributed edge containers with zero-latency JavaScript query execution.

Any autonomous AI agent, LLM tool, or vibe coder can provision and query an AxarDB NoSQL database in seconds via simple HTTP REST calls.

---

## 1. Quickstart for AI Agents

### Instant Free Database Provisioning (Zero-Interaction)
An AI agent can register and provision a database with a single API call:

```bash
curl -X POST "https://axardb.com/api/auth/register-fast" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent-user@gmail.com",
    "dbName": "ai-memory",
    "subdomain": "agent-mem-01"
  }'
```

**Requirements & Rules:**
- Free databases require a reputable email domain (`gmail.com`, `hotmail.com`, `outlook.com`, `yahoo.com`, `proton.me`, etc.).
- The email address must not contain dots (`.`) or aliases (`+`) in the username prefix.
- Rate limit: 1 account creation per IP address per hour.
- The unverified trial database is active immediately for 1 hour. Verify via email link to make your 1 free database permanent.
- Unverified users cannot create multiple databases or delete their database to bypass trial limits.

---

## 2. Querying Your Database (Master Write Access)

All backend operations (Insert, Query, Update, Filter, Delete, Stored Views) execute via HTTP POST to `/query` using your master API key:

```bash
curl -X POST "https://agent-mem-01.axardb.com/query" \
  -H "Authorization: Bearer axdb_YOUR_API_KEY" \
  -H "Content-Type: text/plain; charset=utf-8" \
  -d '
    db.memories.insert({ topic: "user_preference", value: "dark_mode", timestamp: new Date() });
    return db.memories.findall(m => m.topic == "user_preference");
  '
```

### Key Query Syntax Rules for LLMs:
- **Language**: Standard JavaScript (ES6+ executed on the server).
- **Return Value**: Always use `return` to send data back to the client.
- **Collection Access**: `db.<collectionName>.<method>()` (auto-creates collection on first insert).
- **CRITICAL**: Do **NOT** use `.toList()`. In AxarDB `.findall()` returns array results directly.
- **Filtering**: `db.users.findall(u => u.active == true)`
- **Aggregation**: `db.users.findall().count()`

---

## 3. Vibe Coding Privilege: Public Views (Zero-Credential Client Architecture)

### ⚠️ The Golden Rule for AI Vibe Coders & Mobile / Web / IoT Apps:
**NEVER** prompt an AI assistant (Cursor, v0, Lovable, Claude, Windsurf, ChatGPT) to paste your master `axdb_live_...` API key into mobile apps (Flutter/React Native/Swift/Kotlin), frontend websites, or embedded firmware (ESP32). Anyone decompiling the app or inspecting network traffic would gain full database write/delete access!

### The Solution: AxarDB Public Views
AxarDB provides a unique built-in capability: **Public Views** (`// @access public`).
1. **Define the View once on the server** using your master API key:
```bash
curl -X POST "https://agent-mem-01.axardb.com/query" \
  -H "Authorization: Bearer axdb_YOUR_API_KEY" \
  -H "Content-Type: text/plain; charset=utf-8" \
  -d '
    db.saveView("getProductsByCategory", `
      // @access public
      var category = @cat;
      return db.products
        .findall(p => p.category == category && p.inStock == true)
        .take(50);
    `);
    return "Public View created!";
  '
```

2. **Query from any Client with ZERO API Keys**:
Any frontend, mobile app, or IoT device calls HTTP GET without any authentication headers:
```bash
curl "https://agent-mem-01.axardb.com/views/getProductsByCategory?cat=electronics"
```

**Security Guarantees:**
- **Zero Credentials Exposed**: Client bundles require NO tokens or passwords.
- **Read-Only Enforced**: Only HTTP GET/HEAD is allowed; write/delete operations are structurally impossible.
- **Parameter Sanitization**: Dynamic `@param` values prevent code injection.
- **Edge Speed**: Responses are served with ultra-low latency from memory.

---

## 4. In-Memory Acceleration & Migration Layer (PostgreSQL, MySQL, MongoDB)

AxarDB acts as a high-performance **In-Memory Front Layer / Edge Accelerator** for existing SQL and NoSQL engines. It decouples high-frequency client reads from heavy disk-bound storage.

### 4.1 Architecture & Performance Matrix
```
[ Mobile Apps / Web Clients / IoT Devices ]
                   │
                   ▼ (Sub-millisecond HTTPS GET / Public Views - 0 Credentials)
┌─────────────────────────────────────────────────────────┐
│     AxarDB Cloud In-Memory Acceleration Front-Layer     │
│   (100% RAM • Pure JS Engine • Edge Snapshots • Views)  │
└──────────────────────────┬──────────────────────────────┘
                           │ (Async Sync / CDC / Cache-Miss Fallback)
                           ▼
┌─────────────────────────────────────────────────────────┐
│     Primary System of Record (Heavy Disk / ACID)        │
│          PostgreSQL  •  MySQL  •  MongoDB               │
└─────────────────────────────────────────────────────────┘
```

| Metric | Primary DB Direct (Postgres/MySQL/Mongo) | With AxarDB In-Memory Front-Layer |
|:---|:---|:---|
| **Read Latency** | 25ms – 120ms (Disk I/O, locks, query plan) | **0.5ms – 2ms** (100% in-RAM execution) |
| **Edge Concurrency** | Bottlenecked by DB connection pool | **10,000+ concurrent requests** via edge containers |
| **Disk IOPS Load** | 100% of read traffic hits primary disk | **90%+ offloaded** from primary storage |
| **Client Security** | Requires backend proxy or DB credentials | **Zero-credential** access via Public Views |

---

### 4.2 Scenario 1: PostgreSQL — E-Commerce Catalog & Search Acceleration
**Problem**: An e-commerce platform has 200,000 products in PostgreSQL. Category browsing and search cause heavy multi-table JOINs (`products`, `categories`, `tags`) that throttle the database during flash sales.
**Solution**: Export denormalized product documents to AxarDB in memory. Frontend reads hit AxarDB in < 1ms, falling back to PostgreSQL only on cache miss.

#### Step A: Data Migration & Hydration (Node.js / TypeScript)
```typescript
import { Client } from "pg";

async function hydrateAxarFromPostgres() {
  const pg = new Client({ connectionString: process.env.DATABASE_URL });
  await pg.connect();

  // 1. Extract denormalized data with SQL JOIN
  const res = await pg.query(`
    SELECT p.id, p.name, p.price, p.stock, c.name as category,
           COALESCE(json_agg(t.tag) FILTER (WHERE t.tag IS NOT NULL), '[]') as tags
    FROM products p
    LEFT JOIN categories c ON p.category_id = c.id
    LEFT JOIN product_tags t ON p.id = t.product_id
    WHERE p.is_active = true
    GROUP BY p.id, c.name
  `);

  // 2. Bulk load into AxarDB in-memory database
  await fetch("https://my-store.axardb.com/query", {
    method: "POST",
    headers: {
      "Authorization": "Bearer axdb_YOUR_API_KEY",
      "Content-Type": "text/plain; charset=utf-8"
    },
    body: `
      var items = ${JSON.stringify(res.rows)};
      items.forEach(item => {
        var existing = db.products.find(p => p.id == item.id);
        if (existing) Object.assign(existing, item);
        else db.products.insert(item);
      });
      return { hydrated: items.length };
    `
  });
  await pg.end();
}
```

#### Step B: Read-Through Cache API Route (Next.js / Express)
```typescript
// Fast read-through pattern: AxarDB first (< 1ms), PostgreSQL fallback
export async function getProducts(category: string) {
  try {
    const axarRes = await fetch("https://my-store.axardb.com/query", {
      method: "POST",
      headers: { "Authorization": "Bearer axdb_YOUR_API_KEY", "Content-Type": "text/plain" },
      body: `return db.products.findall(p => p.category == "${category}" && p.stock > 0).take(25);`,
      cache: "no-store"
    });
    const { result } = await axarRes.json();
    if (result && result.length > 0) return { source: "axardb-ram", data: result };
  } catch (e) {
    console.warn("AxarDB cache miss, falling back to PostgreSQL:", e);
  }

  // Fallback to PostgreSQL
  const pgRes = await pg.query("SELECT * FROM products WHERE category = $1 AND stock > 0 LIMIT 25", [category]);
  return { source: "postgres-sor", data: pgRes.rows };
}
```

---

### 4.3 Scenario 2: MySQL — High-Throughput Leaderboard & Real-Time Session Store
**Problem**: A gaming/fintech app updates thousands of scores and sessions per second. Recalculating `ORDER BY score DESC LIMIT 100` on MySQL crashes the CPU.
**Solution**: AxarDB holds active player sessions in memory and registers a Public View that sorts and serves the top 100 instantly.

#### Step A: MySQL to AxarDB Sync Worker
```typescript
import mysql from "mysql2/promise";

async function syncLeaderboard() {
  const db = await mysql.createConnection({ host: "localhost", user: "root", database: "game" });
  const [rows] = await db.execute("SELECT id, username, score, rank_tier FROM players ORDER BY score DESC LIMIT 5000");

  await fetch("https://game-leaderboard.axardb.com/query", {
    method: "POST",
    headers: { "Authorization": "Bearer axdb_YOUR_API_KEY", "Content-Type": "text/plain" },
    body: `
      var players = ${JSON.stringify(rows)};
      players.forEach(p => {
        var existing = db.leaderboard.find(x => x.id == p.id);
        if (existing) Object.assign(existing, p);
        else db.leaderboard.insert(p);
      });

      // Register zero-credential Public View for live clients
      db.saveView("getTopLeaderboard", \`
        // @access public
        return db.leaderboard
          .findall()
          .sort((a, b) => b.score - a.score)
          .take(100)
          .select((p, idx) => ({ rank: idx + 1, username: p.username, score: p.score }));
      \`);
      return "Leaderboard synced!";
    `
  });
  await db.end();
}
```

#### Step B: Client Consumes Live Leaderboard (Zero Credentials)
```bash
curl "https://game-leaderboard.axardb.com/views/getTopLeaderboard"
```

---

### 4.4 Scenario 3: MongoDB — IoT Telemetry & Dynamic Document Stream Offloading
**Problem**: An IoT fleet writes millions of sensor telemetry documents to MongoDB Atlas. Direct queries from mobile apps or edge nodes consume high Atlas read IOPS and require distributing database credentials.
**Solution**: Summarize latest device telemetry into AxarDB in memory. Edge devices and mobile dashboards query device state in microseconds via parameterized Public Views.

#### Step A: MongoDB Aggregation & AxarDB Ingestion (Python)
```python
import pymongo, requests, json

def sync_mongo_to_axardb():
    client = pymongo.MongoClient("mongodb+srv://user:pass@cluster.mongodb.net/iot")
    raw = client.iot.telemetry.aggregate([
        {"$sort": {"timestamp": -1}},
        {"$group": {"_id": "$deviceId", "temp": {"$first": "$temp"}, "status": {"$first": "$status"}, "battery": {"$first": "$battery"}}},
        {"$limit": 5000}
    ])
    devices = [{"id": d["_id"], "temp": d["temp"], "status": d["status"], "battery": d["battery"]} for d in raw]

    js_code = f"""
    var devices = {json.dumps(devices)};
    devices.forEach(d => {{
        var item = db.devices.find(x => x.id == d.id);
        if (item) Object.assign(item, d);
        else db.devices.insert(d);
    }});
    db.saveView("getDeviceState", `
        // @access public
        var targetId = @id;
        return db.devices.find(x => x.id == targetId) || {{ error: "Device offline" }};
    `);
    return {{ devicesLoaded: devices.length }};
    """

    requests.post(
        "https://iot-fleet.axardb.com/query",
        headers={"Authorization": "Bearer axdb_YOUR_API_KEY", "Content-Type": "text/plain; charset=utf-8"},
        data=js_code.encode("utf-8")
    )

sync_mongo_to_axardb()
```

#### Step B: Edge Device Queries Live Status
```bash
curl "https://iot-fleet.axardb.com/views/getDeviceState?id=sensor-node-99"
```

---

### 4.5 Fast CLI Migration One-Liners (Terminal Pipelines)

#### PostgreSQL to AxarDB in One Command:
```bash
psql -d my_db -t -A -c "SELECT json_agg(t) FROM (SELECT id, title, price FROM products LIMIT 1000) t;" | \
curl -X POST "https://my-store.axardb.com/query" \
  -H "Authorization: Bearer axdb_YOUR_KEY" \
  -H "Content-Type: text/plain" \
  -d @- -G --data-urlencode 'prefix=var items = ' \
  --data-binary 'var items = JSON.parse(stdin); items.forEach(i => db.products.insert(i)); return items.length;'
```

#### MongoDB to AxarDB in One Command:
```bash
mongoexport --uri="mongodb://localhost:27017/iot" --collection=devices --jsonArray --limit=1000 | \
python -c '
import sys, json, requests
data = json.load(sys.stdin)
js = f"var items = {json.dumps(data)}; items.forEach(i => db.devices.insert(i)); return items.length;"
res = requests.post("https://iot-fleet.axardb.com/query", headers={"Authorization": "Bearer axdb_YOUR_KEY", "Content-Type": "text/plain"}, data=js)
print(res.json())
'
```

---

## Full Documentation & Specifications
For the complete API schema, all JavaScript methods, database migration pipelines, and full multi-platform SDK snippets (Flutter, React Native, Swift, Kotlin, Next.js, Vue, ESP32 C++, Raspberry Pi, PostgreSQL, MySQL, MongoDB):
- [Full LLM Specification](https://axardb.com/llms-full.txt)
- [Web Documentation](https://axardb.com/docs.html)
- [Official GitHub Repository](https://github.com/metin-yakar/AxarDB)