@astrojs/ db

Astro DBはAstroのために設計されたSQLベースのデータベースです。ローカル環境で開発し、Astro Studio dashboard からデプロイしましょう。

強力なローカルの型安全ツールを備えたAstro DBを使用し、リレーショナルデータベースとしてコンテンツをモデル、またはクエリしましょう。インタラクティブなStudio Dashboardから、ホストされているリモートデータを表示、管理、デプロイできます。

AstroDBの詳しい使い方や例に関してはAstro DBガイドをご覧ください

インストール

Astroは公式インテグレーションのセットアップを自動化するために標準でastro addコマンドを搭載しています。自動で行いたくない場合、手動でインテグレーションをインストールすることもできます。

以下のコマンドの内いずれか一つをターミナルで実行してください。

npx astro add db

pnpm astro add db

yarn astro add db

手動でのインストール

AstroDBのインストールを手動で行いたい場合、astro addコマンドを実行するのではなく、以下のステップに従って手動でインストールしてください。

1. npmのパッケージマネージャー経由でインテグレーションをインストールする

npm install @astrojs/db

pnpm add @astrojs/db

yarn add @astrojs/db

2. インテグレーションを`astro.config.mjs`に追加する

import { defineConfig } from 'astro/config';
import db from '@astrojs/db';

export default defineConfig({
  integrations: [
   db()
  ]
});

3. データベースを設定する

プロジェクトディレクトリの一番高い階層にdb/config.tsを作成してください。このファイルはAstroが自動的にロードする特別なファイルで、データベーステーブルを設定するのに使用されます。

import { defineDb } from 'astro:db';

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

テーブル構成の参照

`columns`

テーブルの行の設定をするには、以下のコードのようにcolumnsオブジェクトを使用します。

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 }),
  },
});

テーブルの行を細かく設定するには columnユーティリティーを使用します。columnは以下の型に対応しています。

column.text(...) - プレーンまたはリッチテキストを保存
column.number(...) - 整数（integer）や浮動小数点数（float）を保存する
column.boolean(...) - trueまたはfalseの値を保存する
column.date(...) - データストレージ向けにISO StringとしてパースされたDateオブジェクトを保存する
column.json(...) - データストレージ向けに文字列されたJSONとしてパースされた任意のJSON blobを保存する

以下の追加設定は全ての列で共通に使用できます。

primaryKey - numberまたはtextの列をユニークな識別子として設定します。
optional - Astro DBはNOT NULLオプションを標準で使用しています。nullな値に対応したい場合位はoptionalの値をtrueに設定してください。
default - 新しく追加された値のデフォルト値を設定します。デフォルト値としてAstroDBは静的な値かSQLによって生成されたタイムスタンプのような文字列のいずれかを受け付けます。
unique - この列をユニークと設定します。これにより、テーブル上のエントリ間で値が重複することを防げます。
references - 関連したテーブルを列ごとに参照します。これにより、外部キー制約が設定されます。参照を設定する場合、参照先のテーブルと参照している列が同じ値を持つ必要があります。

`indexes`

テーブルインデックスは与えられた列や列の組み合わせを探すスピードを向上させるために使用されます。indexesプロパティはユニークなインデックス名を持つオブジェクトをKeyとして受け入れます。

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

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

各インデックスには、以下のような追加設定が可能です。

on: string | string[] - インデックスする単一の列、または複数の列が入っている配列。
unique: boolean - ユニークな値をインデックスされた列に強制するにはtrueに設定してください。

`foreignKeys`

Foreign keysは二つのテーブル同士を関連づけるために使用されます。foreignKeysプロパティはテーブルの列同士を関連づける設定オブジェクトが入った配列を受け入れます。

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],
     },
   ],
 });

各キー設定オブジェクトは以下のようなプロパティを受け入れます。

columns: string[] - 参照されたテーブルと関連づける列名の配列
references: () => Column[] - 参照されたテーブルの列を配列として返す関数

Astro DB CLI レファレンス

Astro DBにはAstro Studioのアカウントやホストされたデータベースと対話するためのCLIコマンドが含まれています。

これらのコマンドはGitHub CIアクションを使用している場合は自動的に実行されます。astro db CLIを使用することで手動でコマンドを実行することもできます。

`astro db push`

フラグ

--force-reset 重大なスキーマの変更が必要な場合に、全てのプロダクションデータをリセットする

データベースの変更をプロジェクトデータベースに安全にプッシュします。このコマンドはデータ損失のリスクを確認し、推奨された移行手順を案内します。もし重大なスキーマの変更を行わなければいけない場合、--force-resetフラグを使用してプロダクションデータを１度全てリセットしてください。

`astro db verify`

ローカルのデータベースとリモートのデータベースの設定を違いを確認します。このコマンドはastro db pushが実行された時に自動的に実行されます。verifyはローカルのdb/config.tsファイルをリモートのデータベースと比較し、変更があった場合は警告します。

`astro db execute <file-path>`

フラグ:

--remote Studioのプロジェクトのデータベースに対して実行します。開発用サーバーに対して実行したい場合は省略してください。

.tsまたは.jsファイルを実行し、データベース上で読み書きを行います。このコマンドはファイルパスを引数として受け入れ、型安全なクエリを書くためのastro:dbモジュールの使用もサポートしています。Studioのプロジェクトのデータベースに対して実行したい場合は--remoteフラグを、開発用サーバーに対して実行したい場合は--remoteフラグを省いて実行してください。サンプルファイルを見るには開発データのシードを確認してください。

`astro db shell --query <sql-string>`

フラグ:

--query 実行したいプレーンなSQLクエリ
--remote Studioのプロジェクトのデータベースに対して実行します。開発用サーバーに対して実行したい場合は省略してください。

SQLクエリをデータベースに対して実行します。Studioのプロジェクトのデータベースに対して実行したい場合は--remoteフラグを、開発用サーバーに対して実行したい場合は--remoteフラグを省いて実行してください。

Astro DB utility レファレンス

`isDbError()`

isDbError()関数はエラーがlibSQLデータベースの例外であるか確認します。This may include a　レファレンスを使用するときに起こるforeign key制約エラーやデータを追加するときに必要な情報が足りないかどうかも含まれます。 isDbError()と try / catch ブロックと合わせて使用してデータベースのエラーを処理することもできます。

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 });
};