/astro-db

name: astro-db
description: Use when doing database operations in an Astro project via Astro DB (defineDb, defineTable, db/config.ts, Turso).
versions:
  astro: "7"
user-invocable: true
references: references/schema-definition.md, references/crud-operations.md, references/seed-data.md, references/turso-production.md, references/actions-integration.md, references/templates/db-config.md, references/templates/crud-example.md
related-skills: astro-7, astro-actions, astro-deployment

<objective> Implements Astro DB (`@astrojs/db`): schema definition with `defineDb`/`defineTable` in `db/config.ts`, column types (`text`, `number`, `boolean`, `date`, `json`), type-safe CRUD via `db.select/insert/update/delete`, development seeding in `db/seed.ts`, and production deployment to Turso (libSQL) with `ASTRO_DB_REMOTE_URL`/`ASTRO_DB_APP_TOKEN` and `astro db push`.

Also covers integration with Astro Actions for end-to-end type-safe form-to-database flows. `@astrojs/db` is deprecated and no longer actively maintained (still published, v0.21.3, not removed from Astro 7) — for new projects this skill recommends Drizzle, Kysely, or a direct libSQL client instead; existing projects can keep using it but should plan a migration. </objective>

Astro DB

Type-safe SQL database built into Astro, powered by libSQL/Turso. Use for structured data without external backend services.

> **⚠️ Deprecation notice**: `@astrojs/db` is **deprecated and no longer actively maintained** (still published on npm, currently v0.21.3 — it has not been removed from Astro 7). For new projects, prefer **Drizzle**, **Kysely**, or a direct **libSQL** client instead. Existing projects can keep using it, but should plan a migration.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Check existing db/config.ts, tables, and Actions 2. **fuse-ai-pilot:research-expert** - Verify Astro DB API via Context7/Exa 3. **mcp__context7__query-docs** - Check Astro 6 DB docs for column types and CRUD

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

Overview

When to Use

• Storing structured data (comments, users, posts, forms)
• Building full-stack Astro apps without external DB setup
• Combining with Astro Actions for type-safe form handling
• Deploying to production with Turso (libSQL cloud)
• Seeding development data for local testing

Architecture

db/
├── config.ts   # Schema definition (defineDb, defineTable)
└── seed.ts     # Development data seeding

---

Core Concepts

Schema Definition

Define tables in `db/config.ts` using `defineDb` and `defineTable`. Export tables for use in pages and actions. Column types: `column.text()`, `column.number()`, `column.boolean()`, `column.date()`, `column.json()`.

CRUD Operations

Import `db` and table from `astro:db`. All operations are async and type-safe based on your schema definition.

Turso for Production

Set `ASTRO_DB_REMOTE_URL` and `ASTRO_DB_APP_TOKEN` environment variables. Run `astro db push` to sync schema to Turso. Use `astro db execute` to run seed scripts against remote DB.

Actions Integration

Combine with `astro:actions` for end-to-end type safety: Zod input validation → DB operation → typed response.

---

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | **Schema Definition** | [schema-definition.md](references/schema-definition.md) | Table structure, column types | | **CRUD Operations** | [crud-operations.md](references/crud-operations.md) | select, insert, update, delete | | **Seed Data** | [seed-data.md](references/seed-data.md) | db/seed.ts, remote seeding | | **Turso Production** | [turso-production.md](references/turso-production.md) | Deployment, env vars, push | | **Actions Integration** | [actions-integration.md](references/actions-integration.md) | Type-safe form → DB flow |

Templates

| Template | When to Use | |----------|-------------| | [db-config.md](references/templates/db-config.md) | Complete db/config.ts + seed.ts | | [crud-example.md](references/templates/crud-example.md) | Full CRUD with Actions |

---

Best Practices

1. **Export tables from config.ts** - Import in pages and actions 2. **Use Actions for mutations** - Type-safe with Zod validation 3. **`.returning()` after insert** - Get back inserted rows 4. **Push before deploy** - Run `astro db push` in CI/CD 5. **Turso free tier** - 500 databases, generous for production 6. **New projects: consider Drizzle/Kysely/libSQL instead** - `@astrojs/db` is deprecated and unmaintained; still usable for existing projects, but not recommended as a starting point