> ## Documentation Index
> Fetch the complete documentation index at: https://backdrift.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Modeling

> Entities, fields, and relationships.

Backdrift automatically designs your database schema from natural language. Describe your data, and we handle the rest.

## Database Options

Backdrift supports two database backends:

| Option                 | Best For                | Features                                 |
| ---------------------- | ----------------------- | ---------------------------------------- |
| **DynamoDB** (default) | Simple apps, high scale | NoSQL, auto-scaling, pay-per-request     |
| **RDS PostgreSQL**     | Complex queries, joins  | Relational, SQL, foreign key constraints |

To request PostgreSQL, mention it in your prompt:

```
"A CRM with users, contacts, and deals. Use PostgreSQL for complex reporting queries."
```

## Entities

Entities are your data models. Each entity becomes a database table with automatic CRUD endpoints.

### Defining Entities

```
"Tasks have a title, description, due date, priority, and status."
```

This generates:

```typescript theme={null}
interface Task {
  id: string;           // Auto-generated primary key
  title: string;
  description?: string;
  due_date?: string;    // ISO datetime
  priority: 'low' | 'medium' | 'high';
  status: 'pending' | 'active' | 'done';
  created_at: string;   // Auto-managed
  updated_at: string;   // Auto-managed
}
```

## Field Types

| Type       | Description    | Example                  |
| ---------- | -------------- | ------------------------ |
| `string`   | Text data      | names, descriptions      |
| `number`   | Floating point | prices, scores           |
| `integer`  | Whole numbers  | counts, ages             |
| `boolean`  | True/false     | is\_active, is\_verified |
| `datetime` | ISO timestamp  | due\_date, created\_at   |
| `date`     | Date only      | birth\_date              |
| `enum`     | Fixed options  | status, priority         |
| `json`     | Arbitrary JSON | metadata, settings       |

## Field Constraints

### Required vs Optional

```
"Tasks have a required title and optional description."
```

### Unique Fields

```
"Users have a unique email address."
```

### Default Values

```
"Task status defaults to 'pending'."
```

### Enums

```
"Priority can be low, medium, or high."
```

## Relationships

### One-to-Many

```
"Tasks belong to projects. A project has many tasks."
```

This creates:

* `project_id` foreign key on Task
* Index for efficient queries
* Cascade delete options

### Many-to-Many

```
"Tasks can have multiple tags. Tags can be on multiple tasks."
```

This creates a join table automatically.

### Self-Referential

```
"Tasks can have subtasks."
```

Creates a `parent_task_id` field on Task.

## Automatic Fields

Backdrift adds useful fields automatically:

| Field        | Description                   |
| ------------ | ----------------------------- |
| `id`         | UUID primary key              |
| `created_at` | When record was created       |
| `updated_at` | When record was last modified |
| `org_id`     | Tenant ID (if multi-tenant)   |

## Indexes

Backdrift creates indexes for:

* Primary keys (`id`)
* Foreign keys (`project_id`)
* Tenant keys (`org_id`)
* Frequently queried fields

### Query Optimization

```
"Users often search tasks by status and due date."
```

This hints Backdrift to create a composite index on `(status, due_date)`.

## Multi-Tenant Data

In multi-tenant mode, every entity gets:

```typescript theme={null}
interface Task {
  id: string;
  org_id: string;  // Auto-injected tenant ID
  // ... other fields
}
```

All queries are automatically filtered by `org_id`.

## PII Detection

Backdrift detects Personally Identifiable Information:

| Field Pattern | Detection          |
| ------------- | ------------------ |
| `email`       | Email PII          |
| `phone`       | Phone PII          |
| `ssn`         | SSN PII (Critical) |
| `address`     | Address PII        |

When PII is detected, we recommend:

* Encryption at rest
* Access logging
* Data retention policies

## Example: E-commerce

```
"An e-commerce platform with:
- Products with name, description, price, and category
- Categories with name and description
- Orders with status, total, and customer
- Order items linking orders to products with quantity"
```

Generates:

```
┌─────────────┐     ┌─────────────┐
│  Category   │     │   Product   │
├─────────────┤     ├─────────────┤
│ id          │←────│ category_id │
│ name        │     │ name        │
│ description │     │ description │
└─────────────┘     │ price       │
                    └─────────────┘
                          ↑
┌─────────────┐     ┌─────────────┐
│   Order     │     │ Order Item  │
├─────────────┤     ├─────────────┤
│ id          │←────│ order_id    │
│ customer_id │     │ product_id  │─→
│ status      │     │ quantity    │
│ total       │     │ unit_price  │
└─────────────┘     └─────────────┘
```

<Card title="Scheduled Jobs" icon="clock" href="/capabilities/scheduled-jobs">
  Learn how to run background tasks on a schedule.
</Card>