@astrojs/db

@astrojs/db is Astro's integrated database experience: a libSQL-backed local development DB, a typed schema-and-seed system, and a Studio UI. It is the only package in the monorepo that hoists itself into node_modules at the root (pnpm-workspace.yaml's publicHoistPattern) so that astro sync can resolve it without special-casing.

Purpose

• Define a typed schema in db/config.ts using column.text(), column.number(), etc.
• Seed local data in db/seed.ts for dev.
• Query from any .astro file via the astro:db virtual module: import { db, eq, Comment } from 'astro:db'.
• Push schema and data to a remote libSQL server (Turso) for production.

Directory layout

packages/db/
├── src/             # Plugin, virtual modules, CLI commands (push/pull/execute/shell/verify)
├── test/fixtures/   # Multi-feature test apps
├── virtual.d.ts     # Public types for the astro:db virtual module
├── index.d.ts
└── package.json

The integration registers itself with Astro through the standard AstroIntegration interface; the heavy lifting is done by Vite plugins inside src/ that emit the astro:db virtual module backed by a generated drizzle-style ORM API.

How it works

graph TD
    A[db/config.ts] -->|schema definitions| B[Astro integration]
    B -->|defineDb hook| C[Vite plugin chain]
    C -->|virtual module| D[astro:db]
    A -->|sync| E[(local libSQL file)]
    D -->|queries| E
    F[db/seed.ts] -->|on dev start| E
    G[astro db push] -->|migration plan| H[(remote libSQL)]
    D -->|prod queries| H

The integration relies on the astro sync command to regenerate astro:db types whenever the schema changes (one of the reasons astro sync exists in the first place).

Subcommands

astro db <subcommand> is delegated to packages/astro/src/cli/db/index.ts which dynamically imports @astrojs/db's CLI implementation. Subcommands include:

• astro db push — apply schema changes to the remote DB.
• astro db pull — download remote schema (rarely used).
• astro db execute — run a one-off SQL or TS migration script.
• astro db shell — open a REPL.
• astro db verify — ensure local and remote schemas agree.
• astro login, astro logout, astro link, astro init — Studio auth and project linking.

Tests

packages/db/test/ includes fixtures for column types, foreign keys, seed flows, indexes, and the studio API surface.

Related pages

• systems / CLI for how astro db is wired in.
• packages / astro for the integration interface that @astrojs/db consumes.