@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.
Installation
Section titled InstallationAstro 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.
Manual Installation
Section titled Manual InstallationIf 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 manager2. Add the integration to astro.config.mjs
Section titled 2. Add the integration to astro.config.mjs3. Configure your database
Section titled 3. Configure your databaseCreate 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.
Table configuration reference
Section titled Table configuration referencecolumns
Section titled columnsTable columns are configured using the columns
object:
Columns are configured using the column
utility. column
supports the following types:
column.text(...)
- store either plain or rich text contentcolumn.number(...)
- store integer and floating point valuescolumn.boolean(...)
- store true / false valuescolumn.date(...)
- storeDate
objects, parsed as ISO strings for data storagecolumn.json(...)
- store arbitrary JSON blobs, parsed as stringified JSON for data storage
There are a few shared configuration values across all columns:
primaryKey
- Set anumber
ortext
column as the unique identifier.optional
- Astro DB usesNOT NULL
for all columns by default. Setoptional
totrue
to allow null values.default
- Set the default value for newly inserted entries. This accepts either a static value or a string ofsql
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 indexesTable 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:
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 totrue
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 foreignKeysforeignKeys
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:
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 referenceAstro 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 pushFlags:
--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 verifyCheck 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.
Astro DB utility reference
Section titled Astro DB utility referenceisDbError()
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: