Schema Design

This is a reference guide for Butterbase's declarative schema DSL, where you describe your desired database state and the platform diffs and applies the changes for you. You never write raw ALTER TABLE statements. The manage_schema tool gives you get, dry_run, apply, and list_migrations actions, all idempotent and transactional. The guide covers column types (with a strong warning to use timestamptz, not timestamp), foreign key syntax, the standard base pattern with uuid primary keys and timestamps, and index methods including hnsw for vector embeddings. It also walks through destructive operations, which require explicit _drop and _dropColumns flags. If you're building on Butterbase or need to understand its schema conventions quickly, this is the cheat sheet.

GitHub stars: 532
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add butterbase-ai/butterbase-skills --skill schema-design --agent claude-code

Installs into .claude/skills of the current project.

Files

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