astro-db

Also covers integration with Astro Actions for end-to-end type-safe form-to-database flows. @astrojs/db is deprecated on npm (last release v0.21.3, June 2026) and listed as Removed in the official Astro v7 upgrade guide — for new projects this skill recommends Drizzle, Kysely, node:sqlite, or a direct libSQL client instead; existing Astro 6 projects must migrate off it before upgrading to Astro 7.

Astro DB

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

⚠️ Removal notice: @astrojs/db is deprecated on npm ("Use a database client (Drizzle, Kysely, etc.) directly instead"; last release v0.21.3) and the official Astro v7 upgrade guide lists it under "Removed" — remove it from dependencies when upgrading. Replacements: Node's built-in node:sqlite (Node adapter), Drizzle directly, Kysely, or a libSQL/Turso client. The content below documents the legacy Astro 6 API for maintaining/migrating existing projects.

Agent Workflow (MANDATORY)

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

fuse-ai-pilot:explore-codebase - Check existing db/config.ts, tables, and Actions
fuse-ai-pilot:research-expert - Verify Astro DB API via Context7/Exa
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	Table structure, column types
CRUD Operations	crud-operations.md	select, insert, update, delete
Seed Data	seed-data.md	db/seed.ts, remote seeding
Turso Production	turso-production.md	Deployment, env vars, push
Actions Integration	actions-integration.md	Type-safe form → DB flow

Templates

Template	When to Use
db-config.md	Complete db/config.ts + seed.ts
crud-example.md	Full CRUD with Actions

Best Practices

Export tables from config.ts - Import in pages and actions
Use Actions for mutations - Type-safe with Zod validation
.returning() after insert - Get back inserted rows
Push before deploy - Run astro db push in CI/CD
Turso free tier - 500 databases, generous for production
New projects: use Drizzle/Kysely/node:sqlite/libSQL instead - @astrojs/db is deprecated and listed as removed in the Astro v7 upgrade guide; migrate existing projects before upgrading to Astro 7