@astrojs/ db

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.

npm

npx astro add db

pnpm

pnpm astro add db

Yarn

yarn 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

npm

npm install @astrojs/db

pnpm

pnpm add @astrojs/db

Yarn

yarn add @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 for improve lookup speeds on a given column or combination of columns. The indexes property accepts an object with a unique index name as the key:

db/config.ts

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

const Comment = defineTable({
  authorId: column.number(),
  body: column.text(),
  indexes: {
    author_idx: { on: ['authorId'], unique: true },
  }
});

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.

foreignKeys

Section titled foreignKeys

Tip

foreignKeys is an advanced API for relating multiple table columns. If you only need to reference a single column, try using the column references property.

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({
  firstName: column.text(),
  lastName: column.text(),
});

const Comment = defineTable({
  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 <file-path>

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 <sql-string>

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.

더 많은 통합

UI 프레임워크

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 어댑터

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

기타 통합

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind