@xano/developer-mcp 1.0.27 → 1.0.28

package/dist/xanoscript_docs_auto/database.md

@@ -0,0 +1,551 @@
+---
+applyTo: "functions/**/*.xs,apis/**/*.xs,tasks/*.xs,tools/**/*.xs"
+---
+
+# Database Operations
+
+Complete reference for all db.* operations in XanoScript.
+
+## Quick Reference
+
+| Operation | Purpose |
+|-----------|---------|
+| `db.query` | Query records with filters, sorting, paging |
+| `db.get` | Get single record by field value |
+| `db.add` | Insert new record |
+| `db.edit` | Full update (PUT-style) |
+| `db.patch` | Partial update (PATCH-style) |
+| `db.add_or_edit` | Upsert - insert or update |
+| `db.del` | Delete record |
+| `db.has` | Check if record exists |
+| `db.transaction` | Atomic operations |
+| `db.bulk.*` | Bulk operations |
+| `db.direct_query` | Raw SQL execution |
+
+---
+
+## db.query
+
+Query multiple records with filtering, sorting, and pagination:
+
+```xs
+db.query user {
+  where = $db.user.active == true
+        && $db.user.created_at >= $start_date
+  order_by = {field: "created_at", direction: "desc"}
+  return = {type: "list", paging: {per_page: 20, page: $input.page}}
+} as $users
+```
+
+### Where Clauses
+
+```xs
+// Comparison operators
+$db.user.age >= 18
+$db.user.status == "active"
+$db.user.email != null
+
+// Null-safe operators (ignore if value is null)
+$db.product.category ==? $input.category
+$db.product.price >=? $input.min_price
+
+// Logical operators
+$db.user.active == true && $db.user.verified == true
+$db.user.role == "admin" || $db.user.role == "moderator"
+
+// IN clause
+$db.product.status in ["active", "pending"]
+$db.product.category not in ["deleted", "hidden"]
+
+// LIKE patterns
+$db.user.name like "John%"
+$db.user.email ilike "%@gmail.com"
+
+// BETWEEN
+$db.product.price between 10:100
+$db.order.created_at between $start:$end
+
+// Array operations
+$db.product.tags|contains:"featured"
+$db.post.categories|overlaps:["tech", "news"]
+
+// JSON contains
+$db.product.metadata @> {"featured": true}
+
+// Regex
+$db.product.sku ~ "^SKU-[0-9]+"
+
+// Full-text search
+$db.post.content search $input.query
+```
+
+### Return Types
+
+```xs
+// List with pagination
+return = {type: "list", paging: {per_page: 20, page: 1}}
+
+// All records (no pagination)
+return = {type: "all"}
+
+// Count only
+return = {type: "count"}
+
+// First record only
+return = {type: "first"}
+```
+
+### Ordering
+
+```xs
+// Single field
+order_by = {field: "created_at", direction: "desc"}
+
+// Multiple fields
+order_by = [
+  {field: "priority", direction: "desc"},
+  {field: "created_at", direction: "asc"}
+]
+```
+
+### Field Selection
+
+```xs
+// Select specific fields
+fields = ["id", "name", "email"]
+
+// Exclude fields
+exclude = ["password", "internal_notes"]
+```
+
+### Joins (Addons)
+
+```xs
+db.query order {
+  where = $db.order.user_id == $input.user_id
+  addons = [user, order_items]
+} as $orders
+```
+
+---
+
+## db.get
+
+Retrieve a single record by field value:
+
+```xs
+db.get user {
+  field_name = "id"
+  field_value = $input.user_id
+} as $user
+```
+
+### By Custom Field
+
+```xs
+db.get user {
+  field_name = "email"
+  field_value = $input.email
+} as $user
+```
+
+### With Addons
+
+```xs
+db.get order {
+  field_name = "id"
+  field_value = $input.order_id
+  addons = [user, order_items, shipping_address]
+} as $order
+```
+
+---
+
+## db.add
+
+Insert a new record:
+
+```xs
+db.add user {
+  data = {
+    name: $input.name,
+    email: $input.email,
+    created_at: now
+  }
+} as $new_user
+```
+
+### With Returning Fields
+
+```xs
+db.add product {
+  data = {
+    name: $input.name,
+    price: $input.price,
+    sku: |uuid
+  }
+  return = ["id", "sku", "created_at"]
+} as $product
+```
+
+---
+
+## db.edit
+
+Full update (replaces all fields):
+
+```xs
+db.edit user {
+  field_name = "id"
+  field_value = $input.user_id
+  data = {
+    name: $input.name,
+    email: $input.email,
+    updated_at: now
+  }
+} as $updated_user
+```
+
+---
+
+## db.patch
+
+Partial update (only specified fields):
+
+```xs
+db.patch user {
+  field_name = "id"
+  field_value = $input.user_id
+  data = {
+    last_login: now
+  }
+} as $patched_user
+```
+
+### Increment/Decrement
+
+```xs
+db.patch product {
+  field_name = "id"
+  field_value = $input.product_id
+  data = {
+    stock: $db.product.stock - $input.quantity,
+    sales_count: $db.product.sales_count + 1
+  }
+}
+```
+
+---
+
+## db.add_or_edit
+
+Upsert - insert if not exists, update if exists:
+
+```xs
+db.add_or_edit user_preference {
+  field_name = "user_id"
+  field_value = $input.user_id
+  data = {
+    user_id: $input.user_id,
+    theme: $input.theme,
+    updated_at: now
+  }
+} as $preference
+```
+
+---
+
+## db.del
+
+Delete a record:
+
+```xs
+db.del user {
+  field_name = "id"
+  field_value = $input.user_id
+}
+```
+
+### Soft Delete Pattern
+
+```xs
+// Instead of deleting, mark as deleted
+db.patch user {
+  field_name = "id"
+  field_value = $input.user_id
+  data = {
+    deleted_at: now,
+    active: false
+  }
+}
+```
+
+---
+
+## db.has
+
+Check if a record exists:
+
+```xs
+db.has user {
+  where = $db.user.email == $input.email
+} as $email_exists
+
+conditional {
+  if ($email_exists) {
+    throw {
+      name = "DuplicateError"
+      value = "Email already registered"
+    }
+  }
+}
+```
+
+---
+
+## db.transaction
+
+Execute multiple operations atomically:
+
+```xs
+db.transaction {
+  stack {
+    // Deduct from source account
+    db.patch account {
+      field_name = "id"
+      field_value = $input.from_account
+      data = {
+        balance: $db.account.balance - $input.amount
+      }
+    }
+
+    // Add to destination account
+    db.patch account {
+      field_name = "id"
+      field_value = $input.to_account
+      data = {
+        balance: $db.account.balance + $input.amount
+      }
+    }
+
+    // Record the transfer
+    db.add transfer {
+      data = {
+        from_account: $input.from_account,
+        to_account: $input.to_account,
+        amount: $input.amount,
+        created_at: now
+      }
+    } as $transfer
+  }
+} as $result
+```
+
+---
+
+## Bulk Operations
+
+### db.bulk.add
+
+Insert multiple records:
+
+```xs
+db.bulk.add product {
+  data = $input.products
+} as $inserted
+```
+
+### db.bulk.patch
+
+Update multiple records:
+
+```xs
+db.bulk.patch product {
+  where = $db.product.category == "electronics"
+  data = {
+    on_sale: true,
+    updated_at: now
+  }
+}
+```
+
+### db.bulk.delete
+
+Delete multiple records:
+
+```xs
+db.bulk.delete session {
+  where = $db.session.expires_at < now
+}
+```
+
+---
+
+## db.direct_query
+
+Execute raw SQL (use with caution):
+
+```xs
+db.direct_query {
+  query = "SELECT id, name FROM users WHERE created_at > $1"
+  params = [$start_date]
+} as $results
+```
+
+### External Databases
+
+```xs
+// PostgreSQL
+db.external.postgres.direct_query {
+  connection = $env.EXTERNAL_PG_URL
+  query = "SELECT * FROM external_table"
+} as $data
+
+// MySQL
+db.external.mysql.direct_query {
+  connection = $env.MYSQL_URL
+  query = "SELECT * FROM products"
+} as $data
+
+// SQL Server
+db.external.mssql.direct_query {
+  connection = $env.MSSQL_URL
+  query = "SELECT TOP 10 * FROM orders"
+} as $data
+```
+
+---
+
+## db.truncate
+
+Delete all records from a table:
+
+```xs
+db.truncate temp_data
+```
+
+---
+
+## db.schema
+
+Get table schema information:
+
+```xs
+db.schema user as $user_schema
+```
+
+---
+
+## db.set_datasource
+
+Switch to a different datasource:
+
+```xs
+db.set_datasource {
+  name = "analytics"
+}
+
+db.query events {} as $events
+```
+
+---
+
+## Query Filters
+
+Use filters in where clauses:
+
+### String Operations
+
+```xs
+$db.user.name|to_lower == $input.name|to_lower
+$db.product.sku|substr:0:3 == "SKU"
+```
+
+### Numeric Operations
+
+```xs
+$db.product.price|floor >= 10
+$db.stats.value|round:2 == 3.14
+```
+
+### Timestamp Operations
+
+```xs
+$db.order.created_at|timestamp_year == 2025
+$db.event.start_time|timestamp_day_of_week == 1
+```
+
+### Vector Operations (AI/ML)
+
+```xs
+// Cosine similarity for vector search
+db.query document {
+  where = $db.document.embedding|cosine_similarity:$input.vector > 0.8
+  order_by = {
+    field: $db.document.embedding|cosine_similarity:$input.vector,
+    direction: "desc"
+  }
+  return = {type: "list", paging: {per_page: 10}}
+} as $similar_docs
+```
+
+### Geo Operations
+
+```xs
+// Find locations within radius
+db.query store {
+  where = $db.store.location|within:$input.point:5000
+  order_by = {
+    field: $db.store.location|distance:$input.point,
+    direction: "asc"
+  }
+} as $nearby_stores
+```
+
+---
+
+## Best Practices
+
+### Use Indexes
+
+Define indexes for frequently queried columns:
+
+```xs
+table user {
+  schema {
+    int id primary=true
+    text email
+    timestamp created_at
+  }
+  index idx_email { columns = [email] unique=true }
+  index idx_created { columns = [created_at] }
+}
+```
+
+### Paginate Large Results
+
+```xs
+db.query product {
+  return = {type: "list", paging: {per_page: 100, page: $input.page}}
+} as $products
+```
+
+### Select Only Needed Fields
+
+```xs
+db.query user {
+  fields = ["id", "name", "email"]
+} as $users
+```
+
+### Use Transactions for Related Operations
+
+```xs
+db.transaction {
+  stack {
+    db.add order { ... } as $order
+    db.add order_item { ... } as $items
+    db.patch inventory { ... }
+  }
+}
+```