SQL Database (D1)

D1 is a structured database for your Vulcan apps. Use it when you need to organize data into tables and run detailed queries across it.

---

What it is

A proper relational database. Data is organized into tables with rows and columns, and you can run complex queries across them. The AI handles all the SQL — you just describe the data you need.

---

When to use SQL

Use D1 when:

• You need filtering, sorting, or searching across multiple fields at once
• You want aggregations like totals, averages, or counts (e.g. "monthly expense summary")
• You're building a report or analytics feature
• You need to link data across multiple types (e.g. projects → tasks → comments)
• The template you're using has a -sql variant

Use KV instead when:

• You're building something simple without complex queries
• You want the fastest possible setup

---

How to add it to your app

Tell the AI your data needs and it'll choose D1 when appropriate. You can also explicitly ask:

"Use a SQL database for this" "I need to be able to filter by date, status, and assigned user all at once" "Build this using the crm-sql template"

The AI will:

1. Provision a D1 database for your project
2. Create migration files with your table structure
3. Seed example data so the app isn't empty

---

Migrations

SQL apps have a migrations/ folder with numbered .sql files:

migrations/
  0001_create_tables.sql
  0002_seed_data.sql

These run in order to set up your database schema. Don't delete or rename them — the system uses them to track which setup steps have already been applied.

When the AI needs to change your data structure (add a column, create a new table), it adds a new numbered migration file rather than modifying the existing ones.

---

Preview vs production databases

Preview and production each have their own separate database. Data you add in preview stays in preview. This lets you test schema changes safely before they go live.

---

SQL variants of templates

Many templates have an -sql version (e.g. crm → crm-sql, blog → blog-sql). These are identical in functionality but use D1 instead of KV, with richer filtering and analytics built in.

→ Browse SQL templates