データベース（Managed SQLite）

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

何をどこに保存するか

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

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

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

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

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

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

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

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

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

Managed SQLite は SQLite 互換の DB なので、SQLite で作ったアプリの SQL やテーブル定義は通常そのまま使えます。変えるのは接続まわりで、sqlite3 や better-sqlite3 でサーバー内のファイルに直接保存している箇所を、libSQL クライアントでの接続に置き換えます。クライアントの API には差があり、Node.js は同期の better-sqlite3 から非同期の @libsql/client になるため await を各ハンドラに足します。Python の libsql は row_factory・型アダプタ・例外クラスが sqlite3 と異なります。Python / Node.js では同じクライアントに file:local.db のようなファイルを渡せば、ローカル開発ではファイル SQLite として動きます。

sqlite3 や better-sqlite3 で残しておきたいデータをファイルに保存している場合は、AI エージェントに次のように依頼できます。

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

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

Managed SQLite を使う

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

db:
  mode: libsql

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

接続コード

設定ファイルの変更に加えて、アプリ側も libSQL クライアントで DB に接続する必要があります。SQL は SQLite と同じように書けます。Keelson 上では、ローカルのファイルパスではなく、Keelson が渡す接続 URL と認証トークンを使います。Python / Node.js では、環境変数がないときに file:local.db へフォールバックする形にしておくと、ローカル開発では同じコードがファイル SQLite として動きます（Go の libSQL クライアントは file: を開けないため、この形は使えません）。対応クライアントは Python・Node.js・Go で利用できます。

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

Python

import os

import libsql

conn = libsql.connect(
    database=os.environ.get("KEELSON_DB_URL", "file:local.db"),  # file: = ローカル開発
    auth_token=os.environ.get("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 ?? "file:local.db", // file: = ローカル開発
  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: ["サンプル"] });

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

テーブルや列の名前、データ型、制約など、DB の構造を定義したものを「スキーマ」と呼びます。テーブルがまだなければ、上の例のように CREATE TABLE IF NOT EXISTS で作成できます。

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

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

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

同じコマンドを繰り返し実行しても、テーブルやデータの重複などが起きないようにします（冪等性）。変更後の DB は、それまでのコードでも読み書きできる状態にしてください。command のない静的サイトでは db.migrate は実行されません。詳しくは更新と復元を参照してください。

同時書き込み

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 には Django ORM 用のバックエンドがありません）。詳しくはフレームワーク別の注意点を参照してください。

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

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

バックアップと復元

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

方法	用途
日次バックアップ	毎日自動で保存されるバックアップから戻す
手動スナップショット	大きな変更の前など、必要なタイミングでバックアップを作る（1 アプリ 1 日 5 回まで。日付は UTC 基準）
時刻復元（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 の容量はこれとは別枠です

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