schema-design

# Schema Design Skill Reference guide for Butterbase's declarative schema DSL. Covers column types, constraints, indexes, and common data modeling patterns. --- ## 1. Overview Butterbase uses a **declarative schema DSL** — you describe the desired end state of your database, and the platform computes and applies the diff. You never write raw `ALTER TABLE` or `CREATE TABLE` SQL. Instead, call `manage_schema` with `action: "apply"` and a JSON payload describing your tables, columns, and indexes. The single `manage_schema` tool exposes four actions: | Action | Purpose | |--------|---------| | `"get"` | Read the current schema | | `"dry_run"` | Preview SQL that `apply` would execute, without running it | | `"apply"` | Apply a declarative schema (diffs against current, runs safe DDL) | | `"list_migrations"` | List applied migrations, most recent first | Key principles: - **Idempotent**: applying the same schema twice is safe — returns "Schema is up to date" if no changes needed - **Additive by default**: new columns and tables are created automatically - **Explicit drops**: destructive operations require opt-in via `_drop` / `_dropColumns` - **Preview first**: use `action: "dry_run"` to see what will change before committing - **Transactional**: each migration runs in a single transaction — all changes commit or all roll back --- ## 2. Column Types Reference | Type | PostgreSQL | Use case | |------|-----------|----------| | `uuid` | UUID | Primary keys, foreign keys | | ...