grey-haven-database-conventions

# Grey Haven Database Conventions

**Database schema standards for Drizzle ORM (TypeScript) and SQLModel (Python).**

Follow these conventions for all Grey Haven multi-tenant database schemas.

## Supporting Documentation

- **[examples/](examples/)** - Complete schema examples (all files <500 lines)
  - [drizzle-schemas.md](examples/drizzle-schemas.md) - TypeScript/Drizzle examples
  - [sqlmodel-schemas.md](examples/sqlmodel-schemas.md) - Python/SQLModel examples
  - [migrations.md](examples/migrations.md) - Migration patterns
  - [rls-policies.md](examples/rls-policies.md) - Row Level Security
- **[reference/](reference/)** - Detailed references (all files <500 lines)
  - [field-naming.md](reference/field-naming.md) - Naming conventions
  - [indexing.md](reference/indexing.md) - Index patterns
  - [relationships.md](reference/relationships.md) - Foreign keys and relations
- **[templates/](templates/)** - Copy-paste schema templates
- **[checklists/](checklists/)** - Schema validation checklists

## Critical Rules

### 1. snake_case Fields (ALWAYS)

**Database columns MUST use snake_case, never camelCase.**

```typescript
// ✅ CORRECT
export const users = pgTable("users", {
  id: uuid("id").primaryKey().defaultRandom(),
  created_at: timestamp("created_at").defaultNow().notNull(),
  tenant_id: uuid("tenant_id").notNull(),
  email_address: text("email_address").notNull(),
});

// ❌ WRONG - Don't use camelCase
export const users = pgTable("users", {
  createdAt: timestamp("createdAt"),  // WRONG!
  tenantId: uuid("tenantId"),        // WRONG!
});
```

### 2. tenant_id Required (Multi-Tenant)

**Every table MUST include tenant_id for data isolation.**

```typescript
// TypeScript - Drizzle
export const organizations = pgTable("organizations", {
  id: uuid("id").primaryKey().defaultRandom(),
  tenant_id: uuid("tenant_id").notNull(),  // REQUIRED
  name: text("name").notNull(),
});
```

```python
# Python - SQLModel
class Organization(SQLModel, table=True):
    id: UUID