データベース（Managed SQLite）

顧客情報、案件、申請内容など、アプリで登録・検索・更新するデータには Managed SQLite を使います。Keelson がアプリ専用に用意するデータベースで、保存したデータはアプリを再起動・再デプロイしても残ります。

何をどこに保存するか

画像や設定ファイルにも、再起動後に残せる保存先があります。保存したいものと用途で選びます。

保存したいもの・用途	保存先
顧客情報、案件、申請などを登録・検索・更新する	Managed SQLite
設定ファイルや処理済みデータの記録を、アプリ内部で読み書きする	Files SDK
画像を画面に表示する、PDF や添付ファイルを利用者が開く	Media SDK

たとえば案件管理アプリなら、案件名や担当者は DB に、添付 PDF は Media に保存します。DB には添付ファイルの ID も記録し、案件とファイルを関連付けます。

ファイルの保存方法はファイルとメディアを参照してください。

ローカルファイルは消える

ここでいう「ローカルファイル」は、Keelson 上でアプリが動くサーバー内に書き込むファイルです。アプリを再起動・再デプロイしたり、アクセスがなくなって停止したりすると、そのファイルは失われます。この性質を「揮発性」と呼びます。

./data.db、/tmp/data.db、/data/main.db のように保存先のフォルダを変えても、再起動後にデータを残すことはできません。定期実行ジョブは Web アプリとは別の環境で動くため、これらのファイルを共有することもできません。

アップロードの受け取りや変換途中のファイルなど、処理中だけ使う一時ファイルは /tmp に置いて構いません。後で必要になるデータは、上の表の保存先に保存してください。

ファイル SQLite を使っているアプリ

sqlite3 や better-sqlite3 でファイルに保存している場合は、Managed SQLite に接続するコードへ変更します。AI エージェントに、次のように依頼できます。

このアプリのデータが、Keelson で再起動・再デプロイした後も残るようにしてください。ファイル SQLite を使っている箇所を確認し、Managed SQLite への変更と、既存データの移し方を説明してください。

ファイル SQLite を使うコードはデプロイ時に検出され、宣言がなければ拒否されます。再生成できるキャッシュ用途に限り、db.local_sqlite で一時ファイルの利用を宣言できます。この設定でもファイルは再起動後に残りません。詳しくはリファレンスを参照してください。

Managed SQLite を使う

keelson.yaml に次の設定を書くと、アプリ専用のデータベースが用意されます。通常は AI エージェントが設定と接続コードを作成します。

db:
  mode: libsql

DB サーバーの準備は不要です。 接続 URL と認証トークンは、Keelson がアプリの環境変数に設定します。
アプリごとにデータを分けます。 接続用の認証情報でアクセスできるのは、そのアプリの DB だけです。
保存を確定したデータは再起動後も残ります。 SQL のコミットが完了した時点で保存されます。
日本リージョンに配置されます。 米国西海岸リージョンは近日リリース予定です。
バックアップから戻せます。 日次バックアップ、手動バックアップ、指定時刻への復元に対応しています。

接続コード

設定ファイルの変更に加えて、アプリ側も libSQL クライアントで DB に接続する必要があります。SQL は SQLite と同じように書けますが、ローカルのファイルパスではなく、Keelson が渡す接続 URL と認証トークンを使います。対応クライアントは Python・Node.js・Go で利用できます。

以下はテーブルを作り、データを 1 件保存する例です。Python は libsql、Node.js は @libsql/client を依存パッケージに追加します。

Python

import os, libsql

conn = libsql.connect(
    database=os.environ["KEELSON_DB_URL"],
    auth_token=os.environ["KEELSON_DB_AUTH_TOKEN"],
)
conn.execute("""
    CREATE TABLE IF NOT EXISTS items (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT NOT NULL,
        created_at TEXT DEFAULT CURRENT_TIMESTAMP
    )
""")
conn.execute("INSERT INTO items (name) VALUES (?)", ("サンプル",))
conn.commit()

Node.js

import { createClient } from "@libsql/client";

const db = createClient({
  url: process.env.KEELSON_DB_URL,
  authToken: process.env.KEELSON_DB_AUTH_TOKEN,
});
await db.execute(`
  CREATE TABLE IF NOT EXISTS items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
  )
`);
await db.execute({ sql: "INSERT INTO items (name) VALUES (?)", args: ["サンプル"] });

テーブルや列を追加・変更する

顧客名や案件名など、何を保存するかを定義したものを「スキーマ」と呼びます。テーブルがまだなければ、上の例のように CREATE TABLE IF NOT EXISTS で作成できます。

デプロイに合わせてテーブルや列を変更する場合は、db.migrate に変更用のコマンドを書きます。この処理を「マイグレーション」と呼びます。

db:
  mode: libsql
  migrate: "python migrate.py"

db.migrate は新しいコードに切り替える前に実行されます。失敗した場合は、それまでのコードでアプリの提供を続けます。ただし、DB に加えた変更は自動では戻りません。

同じコマンドがデプロイのたびに実行されても結果が壊れないようにし（冪等性）、それまでのコードでも読み書きできる変更にしてください。詳しくは更新と復元を参照してください。

同時書き込み

SQLite は、同時に書き込みを行う処理を 1 つずつ実行します。Web アプリと定期実行ジョブなどが同時に書き込むと、待ち時間が発生することがあります。書き込みが集中し、応答時間に影響する場合は、処理の見直しや外部の PostgreSQL などを検討してください。

外部データベースを使う

すでに使っている PostgreSQL、MySQL、外部の libSQL などに接続する場合は、db.mode: none にします。接続情報は自分で用意し、シークレットとして設定してください。この設定で Keelson が外部 DB を作成したり、既存のデータを移したりすることはありません。

db:
  mode: none
secrets:
  items:
    - name: DATABASE_URL
      description: "PostgreSQL の接続文字列"
  required:
    - all_of: [DATABASE_URL]

Django は現在未対応です。詳しくはフレームワーク別の注意点を参照してください。

外部 DB を使う主なケースです。

ケース	選択肢
データ量や必要な処理速度が Managed SQLite では対応できない	外部 PostgreSQL
同時書き込みが非常に多い	PostgreSQL、MySQL
BI ツールや基幹システムから直接参照する	共有の PostgreSQL、データウェアハウス
Keelson のプランより長い期間のバックアップが必要	外部のマネージド DB

バックアップと復元

誤ってデータを削除・更新した場合に備えて、すべてのプランでバックアップと復元を利用できます。

方法	用途
日次バックアップ	毎日自動で保存されるバックアップから戻す
手動スナップショット	大きな変更の前など、必要なタイミングでバックアップを作る（1 アプリ 1 日 5 回まで）
時刻復元（PITR）	戻せる期間内の時刻を指定し、その時点のデータに戻す
ダウンロード	バックアップや指定時刻のデータを手元に保存する

保存されるバックアップと戻せる期間

	Starter	Plus	Team
日次バックアップの保存数	1 回分	3 回分	7 回分
時刻を指定して戻せる期間	過去 24 時間	過去 7 日	過去 14 日

コンソールのアプリ画面で「復元ポイント」を開き、タイムライン上のバックアップや時刻を選ぶと、復元やダウンロードができます。

復元はアプリ単位で、他のアプリには影響しません。復元前の状態は 72 時間保持され、その間は復元を取り消せます。復元の実行には、ブラウザでの承認が必要です。

復元の対象

このバックアップで戻せるのは Managed SQLite のデータだけです。Files / Media SDK のファイル、外部 DB、アプリのコードや設定は対象外です。

たとえば、DB に保存した添付ファイルの ID を復元しても、Media から削除済みのファイル本体は戻りません。コードや設定を含めた変更の戻し方は更新と復元を参照してください。

容量

Managed SQLite にはプランごとの固定上限はありません。ただし、基盤側の技術上限は適用されます。また、平常の業務利用を著しく超える負荷や、プラットフォームの安定運用・他のお客様の利用・当社の合理的な運用コストに影響を及ぼす利用を検知した場合、アプリの実行を制限または停止することがあります。緊急時は事前の通知なく制限することがあります
ワークスペースのストレージ（Files / Media SDK のファイル、スナップショット、デプロイ用ファイルなどの合計）はプランごとに上限があります。DB の容量はこれとは別枠です

プラン別の制限はプランと制限を参照してください。