@xano/developer-mcp 1.0.27 → 1.0.28

package/dist/xanoscript_docs_auto/tables.md

@@ -0,0 +1,447 @@
+---
+applyTo: "tables/*.xs"
+---
+
+# Tables
+
+Database schema definitions with columns, types, indexes, and relationships.
+
+## Quick Reference
+
+```xs
+table "<name>" {
+  schema {
+    int id primary=true
+    text name
+    timestamp created_at default=now
+  }
+  index idx_name { columns = [name] }
+}
+```
+
+---
+
+## Table Definition
+
+### Basic Table
+
+```xs
+table "user" {
+  schema {
+    int id primary=true
+    text name
+    text email
+    timestamp created_at default=now
+    timestamp? updated_at
+  }
+}
+```
+
+### With All Options
+
+```xs
+table "product" {
+  schema {
+    int id primary=true
+    text name
+    text? description
+    decimal price
+    int stock default=0
+    bool active default=true
+    json metadata
+    timestamp created_at default=now
+    timestamp? updated_at
+    timestamp? deleted_at
+  }
+
+  index idx_active { columns = [active] }
+  index idx_created { columns = [created_at] }
+  index idx_price { columns = [price] }
+
+  history {
+    enabled = true
+    retention = 30
+  }
+}
+```
+
+---
+
+## Column Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `int` | Integer | `int id` |
+| `decimal` | Floating-point | `decimal price` |
+| `text` | String | `text name` |
+| `email` | Email format | `email user_email` |
+| `password` | Hashed password | `password pwd` |
+| `bool` | Boolean | `bool active` |
+| `date` | Date only | `date birth_date` |
+| `time` | Time only | `time start_time` |
+| `timestamp` | Date and time | `timestamp created_at` |
+| `json` | JSON object/array | `json metadata` |
+| `uuid` | UUID identifier | `uuid guid` |
+| `file` | File reference | `file avatar` |
+| `array` | Array type | `array<text> tags` |
+
+---
+
+## Column Modifiers
+
+### Primary Key
+
+```xs
+int id primary=true
+```
+
+### Optional (Nullable)
+
+```xs
+text? middle_name       // Can be null
+timestamp? deleted_at   // Can be null
+```
+
+### Default Values
+
+```xs
+int count default=0
+bool active default=true
+text status default="pending"
+timestamp created_at default=now
+```
+
+### Unique Constraint
+
+```xs
+text email unique=true
+text username unique=true
+```
+
+### Description
+
+```xs
+text internal_code description="For internal use only"
+```
+
+---
+
+## Indexes
+
+### Single Column Index
+
+```xs
+index idx_email { columns = [email] }
+```
+
+### Unique Index
+
+```xs
+index idx_email { columns = [email] unique=true }
+```
+
+### Composite Index
+
+```xs
+index idx_user_status {
+  columns = [user_id, status]
+}
+```
+
+### Partial Index (with condition)
+
+```xs
+index idx_active_users {
+  columns = [email]
+  where = "active = true"
+}
+```
+
+---
+
+## Foreign Keys (Table Links)
+
+Reference another table:
+
+```xs
+table "order" {
+  schema {
+    int id primary=true
+    tablelink user_id table=user      // References user.id
+    decimal total
+    text status
+    timestamp created_at default=now
+  }
+}
+```
+
+### Table Link Options
+
+```xs
+// Basic reference
+tablelink user_id table=user
+
+// With custom display
+tablelink user_id table=user display=name
+
+// Nullable reference
+tablelink? category_id table=category
+```
+
+---
+
+## History Tracking
+
+Track changes to records:
+
+```xs
+table "document" {
+  schema {
+    int id primary=true
+    text title
+    text content
+    int version default=1
+    timestamp created_at default=now
+  }
+
+  history {
+    enabled = true
+    retention = 90  // Days to keep history
+  }
+}
+```
+
+---
+
+## Common Table Patterns
+
+### User Table
+
+```xs
+table "user" {
+  schema {
+    int id primary=true
+    text name
+    text email unique=true
+    password password_hash
+    text? avatar
+    text role default="user"
+    bool active default=true
+    bool verified default=false
+    timestamp? last_login
+    timestamp created_at default=now
+    timestamp? updated_at
+  }
+
+  index idx_email { columns = [email] unique=true }
+  index idx_role { columns = [role] }
+  index idx_active { columns = [active] }
+}
+```
+
+### Product Table
+
+```xs
+table "product" {
+  schema {
+    int id primary=true
+    text name
+    text? description
+    text sku unique=true
+    decimal price
+    decimal? sale_price
+    int stock default=0
+    tablelink category_id table=category
+    array<text> tags
+    json attributes
+    bool active default=true
+    bool featured default=false
+    timestamp created_at default=now
+    timestamp? updated_at
+  }
+
+  index idx_sku { columns = [sku] unique=true }
+  index idx_category { columns = [category_id] }
+  index idx_active { columns = [active] }
+  index idx_featured { columns = [featured] where = "featured = true" }
+}
+```
+
+### Order Table
+
+```xs
+table "order" {
+  schema {
+    int id primary=true
+    text order_number unique=true
+    tablelink user_id table=user
+    decimal subtotal
+    decimal? discount
+    decimal tax
+    decimal total
+    text status default="pending"
+    json shipping_address
+    json? billing_address
+    text? notes
+    timestamp? paid_at
+    timestamp? shipped_at
+    timestamp? delivered_at
+    timestamp created_at default=now
+    timestamp? updated_at
+  }
+
+  index idx_user { columns = [user_id] }
+  index idx_status { columns = [status] }
+  index idx_created { columns = [created_at] }
+}
+```
+
+### Order Items (Join Table)
+
+```xs
+table "order_item" {
+  schema {
+    int id primary=true
+    tablelink order_id table=order
+    tablelink product_id table=product
+    int quantity
+    decimal unit_price
+    decimal total
+    timestamp created_at default=now
+  }
+
+  index idx_order { columns = [order_id] }
+  index idx_product { columns = [product_id] }
+}
+```
+
+### Session Table
+
+```xs
+table "session" {
+  schema {
+    int id primary=true
+    text token unique=true
+    tablelink user_id table=user
+    json data
+    text ip_address
+    text user_agent
+    timestamp expires_at
+    timestamp created_at default=now
+  }
+
+  index idx_token { columns = [token] unique=true }
+  index idx_user { columns = [user_id] }
+  index idx_expires { columns = [expires_at] }
+}
+```
+
+### Audit Log Table
+
+```xs
+table "audit_log" {
+  schema {
+    int id primary=true
+    tablelink? user_id table=user
+    text action
+    text entity_type
+    int entity_id
+    json old_data
+    json new_data
+    text ip_address
+    timestamp created_at default=now
+  }
+
+  index idx_user { columns = [user_id] }
+  index idx_entity { columns = [entity_type, entity_id] }
+  index idx_created { columns = [created_at] }
+}
+```
+
+---
+
+## Vector Column (AI/ML)
+
+For AI embeddings:
+
+```xs
+table "document" {
+  schema {
+    int id primary=true
+    text title
+    text content
+    vector embedding dimensions=1536  // OpenAI embeddings
+    timestamp created_at default=now
+  }
+
+  index idx_embedding {
+    columns = [embedding]
+    type = "ivfflat"
+    options = {lists: 100}
+  }
+}
+```
+
+---
+
+## Geo Column
+
+For location data:
+
+```xs
+table "store" {
+  schema {
+    int id primary=true
+    text name
+    text address
+    geo location
+    timestamp created_at default=now
+  }
+
+  index idx_location {
+    columns = [location]
+    type = "gist"
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### Naming Conventions
+
+- Use singular table names: `user`, `product`, `order`
+- Use snake_case for column names
+- Prefix indexes with `idx_`
+- Use descriptive index names
+
+### Always Include
+
+- `id` as primary key
+- `created_at` timestamp
+- `updated_at` for mutable data
+
+### Soft Deletes
+
+```xs
+table "resource" {
+  schema {
+    // ... other columns
+    timestamp? deleted_at   // NULL = active, timestamp = deleted
+  }
+
+  index idx_active {
+    columns = [deleted_at]
+    where = "deleted_at IS NULL"
+  }
+}
+```
+
+### Timestamps
+
+```xs
+timestamp created_at default=now
+timestamp? updated_at  // Set on updates
+timestamp? deleted_at  // For soft deletes
+```