データベースを使う（ベータ版）

hanamii では、プロジェクトごとに専用のデータベースを作成できます（ベータ版）。SQLite 互換（libSQL）のデータベースで、発行した接続 URL とトークンを使って、デプロイしたアプリからもローカル開発環境からも接続できます。

データベースはプロジェクト詳細の データベース タブで管理します。

前提

• データベースを管理できるのは、ワークスペースの オーナー と 管理者 です（開発者・閲覧者にはデータベースタブが表示されません）
• 作成できるデータベースは 1 プロジェクトにつき 1 つ です
• ベータ版のため、仕様や上限は今後変更される場合があります

データベースを作成する

1. プロジェクト詳細の データベース タブを開く
2. データベースを作成 を押す
3. 作成方法を選んで 作成する を押す

作成方法は 2 つあります。

• 表示名は任意です（100 文字以内）。空のままにすると、自動で採番された名前が表示されます
• 作成は通常数秒で完了し、ステータスが 利用可能 になると接続情報が表示されます。3 分以上経ってもステータスが変わらない場合は、お問い合わせください

接続情報を取得する

アプリからの接続には、次の 2 つが必要です。

1. データベース URL — libsql:// で始まる URL。データベースタブに常に表示されており、コピーできます
2. 接続トークン — 接続トークンを発行 ボタンから発行します

接続トークンを発行する

発行時に次の 3 つを選びます。

トークンは発行直後に一度だけ表示されます。 hanamii 側には保存されないため、この画面で必ずコピーしてください。控え忘れた場合は、新しいトークンを発行し直せば問題ありません。

トークン運用のおすすめ

• 用途ごとにトークンを分けて発行してください（本番用・開発用など）。漏えいや期限切れの際に、影響範囲をそのトークンだけに絞れます
• 読み取りしかしない用途（集計・閲覧など）には 読み取り 権限のトークンを使ってください
• トークンが漏えいした可能性がある場合は、一覧の 失効 からすぐに無効化できます。失効すると、そのトークンを使っているアプリは即座に接続できなくなるため、先に新しいトークンへ差し替えてから失効する順番が安全です
• 有効期限が切れる前に、新しいトークンを発行してアプリ側を差し替えてください。期限切れは一覧のステータスで確認できます

アプリから接続する

1. クライアントライブラリをインストールする

npm install @libsql/client

2. 接続情報を環境変数に設定する

接続 URL とトークンはコードに直接書かず、環境変数として設定します。hanamii にデプロイするアプリの場合は、プロジェクト詳細の 環境変数 タブに登録してください。

環境変数は保存しただけでは稼働中のアプリに反映されません。保存後の反映手順は環境変数の設定と反映を参照してください。

なお、データベースを作成しても環境変数が自動で追加されることはありません。上記の登録は手動で行ってください。

3. コードから接続する

import { createClient } from '@libsql/client'

const client = createClient({
  url: process.env.DATABASE_URL,
  authToken: process.env.DATABASE_AUTH_TOKEN,
})

const result = await client.execute('SELECT 1')

• SQL の文法は SQLite に準拠します
• 接続は HTTPS 経由で行われます。@libsql/client は既定のインポート（@libsql/client）をそのまま使ってください。WebSocket 接続（@libsql/client/ws）には対応していません
• libSQL 互換のため、Drizzle ORM の libsql ドライバなど、url と authToken で接続する他の libSQL 対応クライアントからも同様に接続できます

ローカル開発から接続する

接続 URL とトークンはインターネット経由で使えるため、ローカル開発環境からも同じ方法で接続できます。ローカル用には有効期限の短いトークンを別途発行することをおすすめします。

データをエクスポートする

データベースタブの SQLiteファイルダウンロード から、データベースの内容全体を 1 つの SQLite ファイル（.db）として書き出せます。

• ダウンロードしたファイルは、ローカルでの動作確認（sqlite3 コマンドや各種 GUI ツールで開けます）や、バックアップとして使えます
• ベータ版の間は、大切なデータについて定期的なエクスポートをおすすめします。 ベータ版では自動フェイルオーバーや任意時点への復元機能は提供していないため、手元のエクスポートが復旧手段になります
• エクスポートの実行回数には上限があります。上限に達した場合は、しばらく待ってから再度お試しください

データベースを削除する

データベースタブの データベースを削除 から削除できます。削除したデータベースと中のデータは元に戻せません。 必要なデータは削除前にエクスポートしてください。

削除後は、同じプロジェクトに新しいデータベースを作成し直せます。

よくある質問

Q. トークンを控え忘れた・失くした

トークンをあとから再表示することはできません。新しいトークンを発行してアプリ側を差し替え、古いトークンは一覧から失効してください。

Q. どんなデータベースですか？

SQLite 互換（libSQL）のデータベースです。SQLite の SQL 文法・データ型がそのまま使えます。PostgreSQL や MySQL ではないため、それらの専用機能（拡張、ストアドプロシージャなど）は利用できません。

Q. 作成が「作成中」のまま進まない

通常は数秒で完了します。3 分以上経っても変わらない場合は一時的な問題の可能性があるため、お問い合わせください。

Q. チームの開発者メンバーにも接続情報を渡したい

データベースタブの操作（トークン発行など）はオーナー・管理者のみ行えます。開発者メンバーには、発行済みの接続情報を環境変数タブ経由で共有するか、オーナー・管理者がトークンを発行して安全な方法で渡してください。

Q. SQLite ファイルの取り込みに失敗する

ファイルの拡張子（.db / .sqlite / .sqlite3 / .db3）とサイズ（100MiB 以下）を確認してください。それでも失敗する場合は、sqlite3 コマンドの .dump などでファイルを作り直すと解消することがあります。

Q. 本番運用に使えますか？

ベータ版として提供中のため、高可用構成や自動復旧は提供していません。その前提でご利用のうえ、定期的なエクスポートによるバックアップを併用してください。