Skip to content

@astrojs/ db

v0.11.0 GitHub npm Changelog

Astro DB is a fully-managed SQL database designed for the Astro ecosystem: develop locally in Astro and deploy from your Astro Studio dashboard.

With Astro DB you have a powerful, local, type-safe tool to query and model content as a relational database. View, manage and deploy your hosted remote data through your interactive Studio dashboard.

See the Astro DB guide for full usage and examples.

Installation

Section titled Installation

Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

Run one of the following commands in a new terminal window.

Terminal window
npx astro add db

Manual Installation

Section titled Manual Installation

If you prefer to set things up from scratch yourself, skip astro add and follow these instructions to install Astro DB yourself.

1. Install the integration from npm via a package manager
Section titled 1. Install the integration from npm via a package manager
Terminal window
npm install @astrojs/db
2. Add the integration to astro.config.mjs
Section titled 2. Add the integration to astro.config.mjs
astro.config.mjs
import { defineConfig } from 'astro/config';
import db from '@astrojs/db';


export default defineConfig({
  integrations: [
   db()
  ]
});
3. Configure your database
Section titled 3. Configure your database

Create a db/config.ts file at the root of your project. This is a special file that Astro will automatically load and use to configure your database tables.

db/config.ts
import { defineDb } from 'astro:db';


export default defineDb({
  tables: {},
})

Table configuration reference

Section titled Table configuration reference

columns

Section titled columns

Table columns are configured using the columns object:

import { defineTable, column, NOW } from 'astro:db';


const Comment = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    author: column.text(),
    content: column.text({ optional: true }),
    published: column.date({ default: NOW }),
  },
});

Columns are configured using the column utility. column supports the following types:

  • column.text(...) - store either plain or rich text content
  • column.number(...) - store integer and floating point values
  • column.boolean(...) - store true / false values
  • column.date(...) - store Date objects, parsed as ISO strings for data storage
  • column.json(...) - store arbitrary JSON blobs, parsed as stringified JSON for data storage

There are a few shared configuration values across all columns:

  • primaryKey - Set a number or text column as the unique identifier.
  • optional - Astro DB uses NOT NULL for all columns by default. Set optional to true to allow null values.
  • default - Set the default value for newly inserted entries. This accepts either a static value or a string of sql for generated values like timestamps.
  • unique - Mark a column as unique. This prevents duplicate values across entries in the table.
  • references - Reference a related table by column. This establishes a foreign key constraint, meaning each column value must have a matching value in the referenced table.

indexes

Section titled indexes

Table indexes are used to improve lookup speeds on a given column or combination of columns. The indexes property accepts an array of configuration objects specifying the columns to index:

db/config.ts
import { defineTable, column } from 'astro:db';


const Comment = defineTable({
  columns: {
    authorId: column.number(),
    published: column.date(),
    body: column.text(),
  },
  indexes: [
    { on: ["authorId", "published"], unique: true },
  ]
});

This will generate a unique index on the authorId and published columns with the name Comment_authorId_published_idx.

The following configuration options are available for each index:

  • on: string | string[] - A single column or array of column names to index.
  • unique: boolean - Set to true to enforce unique values across the indexed columns.
  • name: string (optional) - A custom name for the unique index. This will override Astro’s generated name based on the table and column names being indexed (e.g. Comment_authorId_published_idx). Custom names are global, so ensure index names do not conflict between tables.

foreignKeys

Section titled foreignKeys

Foreign keys are used to establish a relationship between two tables. The foreignKeys property accepts an array of configuration objects that may relate one or more columns between tables:

db/config.ts
import { defineTable, column } from 'astro:db';


const Author = defineTable({
  columns: {
    firstName: column.text(),
    lastName: column.text(),
  },
});


const Comment = defineTable({
  columns: {
    authorFirstName: column.text(),
    authorLastName: column.text(),
    body: column.text(),
  },
  foreignKeys: [
    {
      columns: ["authorFirstName", "authorLastName"],
      references: () => [Author.columns.firstName, Author.columns.lastName],
    },
  ],
});

Each foreign key configuration object accepts the following properties:

  • columns: string[] - An array of column names to relate to the referenced table.
  • references: () => Column[] - A function that returns an array of columns from the referenced table.

Astro DB CLI reference

Section titled Astro DB CLI reference

Astro DB includes a set of CLI commands to interact with your hosted project database and your Astro Studio account.

These commands are called automatically when using a GitHub CI action, and can be called manually using the astro db CLI.

astro db push

Section titled astro db push

Flags:

  • --force-reset Reset all production data if a breaking schema change is required.

Safely push database configuration changes to your project database. This will check for any risk of data loss and guide you on any recommended migration steps. If a breaking schema change must be made, use the --force-reset flag to reset all production data.

astro db verify

Section titled astro db verify

Check for any differences between your local and remote database configurations. This is automatically run by astro db push. verify will compare your local db/config.ts file with the remote database and warn if changes are detected.

astro db execute <file-path>

Section titled astro db execute &lt;file-path&gt;

Flags:

  • --remote Run against your Studio project database. Omit to run against your development server.

Execute a .ts or .js file to read or write to your database. This accepts a file path as an argument, and supports usage of the astro:db module to write type-safe queries. Use the --remote flag to run against your Studio project database, or omit the flag to run against your development server. See how to seed development data for an example file.

astro db shell --query <sql-string>

Section titled astro db shell --query &lt;sql-string&gt;

Flags:

  • --query Raw SQL query to execute.
  • --remote Run against your Studio project database. Omit to run against your development server.

Execute a raw SQL query against your database. Use the --remote flag to run against your Studio project database, or omit the flag to run against your development server.

Astro DB utility reference

Section titled Astro DB utility reference

isDbError()

Section titled isDbError()

The isDbError() function checks if an error is a libSQL database exception. This may include a foreign key constraint error when using references, or missing fields when inserting data. You can combine isDbError() with a try / catch block to handle database errors in your application:

src/pages/api/comment/[id].ts
import { db, Comment, isDbError } from 'astro:db';
import type { APIRoute } from 'astro';


export const POST: APIRoute = (ctx) => {
  try {
    await db.insert(Comment).values({
      id: ctx.params.id,
      content: 'Hello, world!'
    });
  } catch (e) {
    if (isDbError(e)) {
      return new Response(`Cannot insert comment with id ${id}\n\n${e.message}`, { status: 400 });
    }
    return new Response('An unexpected error occurred', { status: 500 });
  }


  return new Response(null, { status: 201 });
};

More integrations

UI Frameworks

SSR Adapters

Other integrations