English for Astro DB

Astro DB brings a managed SQL database directly into the Astro build pipeline, which means teams evaluating it need to talk precisely about how it differs from bringing your own Postgres instance. This guide covers the vocabulary for discussing schema definition, seeding, and deployment with Astro DB.

Key Vocabulary

db/config.ts — the file where Astro DB table schemas are defined using the defineTable and column helpers, serving as the single source of truth for the database structure. “Before adding the new field, check db/config.ts — that’s where the Comment table’s columns are actually declared.”

libSQL — the SQLite-compatible database engine that powers Astro DB locally and in production via Turso, chosen for its edge-friendly, low-latency characteristics. “Locally we’re running on libSQL’s embedded file mode, but in production it connects to a remote Turso instance.”

Seed file — the db/seed.ts script that populates the local development database with sample data each time the dev server starts. “The empty product list you’re seeing is because the seed file wasn’t updated after we added the Category table.”

astro:db — the virtual module that exposes the typed database client (db, table references, and query builders like eq and like) inside Astro components and API routes. “Import db and the Product table from astro:db, then you get full type safety on the query without writing raw SQL.”

Astro Studio / remote database link — the hosted management layer that connects a local Astro DB project to a production libSQL database, handling migrations and credentials. “We linked the project to the remote database so that pushing a schema change also runs the migration against production.”

Push migration — the astro db push command that syncs local schema changes to the linked remote database, distinct from a seed operation. “Don’t just seed data and assume it’s live — you still need to push the migration for the schema change to reach production.”

Common Phrases

• “Is this table defined in db/config.ts, or are we still using a raw SQL migration for it?”
• “Did you push the schema change, or is the remote database still on the old version?”
• “This looks like a seed data issue, not a schema issue — check db/seed.ts first.”
• “Are we querying through astro:db’s typed client, or dropping down to raw SQL somewhere?”
• “Is this running against the local libSQL file or the remote Turso database?”

Example Sentences

Explaining a schema change in a PR: “I added a status column to the Order table in db/config.ts and pushed the migration — existing rows default to 'pending' since I set a default value on the column.”

Debugging empty local data: “The dashboard is showing no products locally because the seed file wasn’t re-run after the last schema reset — deleting the local .astro database file and restarting will fix it.”

Discussing production readiness: “Before we go live, we should confirm the remote database link is pointed at the production Turso instance, not the staging one we’ve been testing against.”

Professional Tips

• Distinguish seeding (sample data for local dev) from pushing (schema migration to remote) explicitly — conflating the two is a common source of “why is production empty” confusion.
• Reference db/config.ts by name when discussing schema, since it’s the canonical definition — don’t describe the schema from memory when the file is one command away.
• Say libSQL when discussing the underlying engine and Turso when discussing the hosted remote database — they’re related but not interchangeable terms in conversation.
• Confirm which environment (local file vs. remote) a query result came from before reporting a data discrepancy — it’s the most common false alarm with Astro DB.

Practice Exercise

1. Write a one-sentence PR description for adding a new table to db/config.ts.
2. Explain the difference between seeding and pushing a migration in your own words.
3. Write a bug report describing data that appears locally but not in production.