ストレージバックエンド
Tip
この記事を読むタイミング:sqlite / mysql / postgres またはカスタムストレージバックエンドに切り替える場合。必要ない場合は飛ばしても、他の機能の使用に影響はありません。
ErisPulse には、3 種類の非同期ネイティブストレージバックエンドが内蔵されており、設定を変更するだけで簡単に切り替えが可能です。API は完全に同一で、コードの変更は一切不要です。
| バックエンド | ドライバー | インストール | 特徴 |
|---|---|---|---|
| SQLite(デフォルト) | aiosqlite | すぐに使用可能 | 設定不要、単一ファイル、WAL による並行処理 |
| MySQL / MariaDB | aiomysql | pip install ErisPulse[mysql] |
既存の MySQL インフラストラクチャがある場合、複数インスタンスで共有するのに適しています |
| PostgreSQL | asyncpg | pip install ErisPulse[postgres] |
トランザクション性能が高く、JSONB エコシステム、高並行性 |
{!--< tips >!--}
- 非同期はネイティブの主インターフェース(
aget/aset/atransaction/aExecute)であり、同期 API は互換性層です。 - フレームワーク自身の設定の永続化、セッション受信箱、対話のチェックポイントなどはすべて同一のストレージバックエンドを経由します。バックエンドを切り替えると、全体の移行が行われます。
[mysql]extra にはcryptographyが含まれています。MySQL 8 のデフォルトのcaching_sha2_password認証には必須です。不足している場合、接続プールの初期化時に失敗します。 {!--< /tips >!--}
バックエンドの選択
config/config.toml で設定します:
[ErisPulse.storage]
backend = "sqlite" # "sqlite"(デフォルト)/ "mysql" / "postgres"
use_global_db = false # SQLite のみ有効:パッケージ内のグローバルデータベース data/config.db を使用
また、Docker / 12-factor アプリケーション仕様に準拠した環境変数による上書きもサポートしています:
ERISPULSE_STORAGE_BACKEND=postgres
ERISPULSE_STORAGE_POSTGRES_HOST=db.example.com
ERISPULSE_STORAGE_POSTGRES_PASSWORD=secret
環境変数の命名規則は、設定パスを大文字にし、ドットをアンダースコアに変換します。
(ErisPulse.storage.postgres.host → ERISPULSE_STORAGE_POSTGRES_HOST)。
接続パラメータ
MySQL(ErisPulse.storage.mysql)
[ErisPulse.storage.mysql]
host = "127.0.0.1"
port = 3306
user = "erispulse"
password = ""
database = "erispulse"
charset = "utf8mb4"
pool_min = 1
pool_max = 10
PostgreSQL(ErisPulse.storage.postgres)
[ErisPulse.storage.postgres]
host = "127.0.0.1"
port = 5432
user = "erispulse"
password = ""
database = "erispulse"
pool_min = 1
pool_max = 10
Note
接続パラメータを変更した後は、フレームワークを再起動する必要があります(設定のホット更新時に再起動のリマインダーログが出力されます)。 接続プールはイベントループに従って惰性作成され、作成時に瞬間的な失敗(ネットワークの揺れ / データベースの再起動期間)が発生した場合、自動的に指数型の退避再試行が行われます。
接続失敗時の動作
フレームワークの起動と実行はデータベースの利用可能性に依存しません。MySQL / PostgreSQL への接続失敗は、フレームワークのクラッシュや起動不能を引き起こしません。
- プール作成時の瞬時失敗は、指数関数的退避再試行(デフォルト 3 回)で自動的に処理されます。
- 再試行回数をすべて使用した場合 → WARNING ログを記録(原因とクールダウン期間を含む)、フレームワークは通常通り起動 / 継続的に動作しますが、ストレージ操作は一時的に利用できません。
- クールダウン期間(デフォルト 30 秒)内では、その後のストレージ操作は即時失敗します(ブロックされず、他の機能の遅延もありません)。
- クールダウン終了後は自動的に再接続を試みます。データベースが復旧するとストレージも復旧し、フレームワークの再起動は不要です。
ログ例: mysql 接続プールの作成が最終的に失敗しました(再試行を 3 回行いました)。30 秒後に自動的に再接続を試みます。この間、ストレージ操作は即時失敗しますが、フレームワークの他の機能には影響しません。
失敗の意味(2.12 以降)
| ステージ | 行動 |
|---|---|
| 操作実行の失敗(書き込みロックのタイムアウト / SQL エラー / 制約違反) | StorageOperationError をスロー(書き込みパス:aset / adelete / aclear / set_multi および同期ブリッジの同パス)——静かに False を返すことはなくなり、重要な書き込みの失敗は明示的に見えるようにします |
| 接続レベルでの到達不能(クールダウン期間中の迅速な失敗) | False / None を返します(ルール 26 のフレームワークの回復力の意味、storage.unreachable / storage.recovered イベントも別途あります) |
| トランザクションの開始タイムアウト(>30秒) | StorageOperationError をスロー(STORAGE_TXN_BEGIN_TIMEOUT_SECS) |
重要な書き込み操作は try/except で囲み、補償処理を行う必要があります。トランザクションブロック内には純粋な DB 操作のみを含めるようにしてください。
異スレッド API
# KV 操作
await sdk.storage.aset("app.name", "MyApp")
value = await sdk.storage.aget("app.name")
keys = await sdk.storage.aget_all_keys()
# 表操作
await sdk.storage.aCreateTable("users", {
"id": "INTEGER PRIMARY KEY AUTOINCREMENT",
"name": "TEXT NOT NULL",
})
rows = await sdk.storage.Table("users").Select("name").ToDict().aExecute()
# 異スレッドトランザクション
async with sdk.storage.atransaction():
await sdk.storage.aset("key1", "value1")
await sdk.storage.Table("users").Insert({"name": "Alice"}).aExecute()
同期 API (get/set/transaction/Table(...).Execute()) は引き続き使用可能です。内部では AsyncBridge がバックグラウンドイベントループを橋渡しして実行しています。非同期ハンドラ内で同期 API を呼び出すと、イベントループが一時的にブロックされます。初回呼び出し時に一回限りの警告(「a 前置きの非同期メソッドの使用を推奨」)が出力されます。非同期メソッドの使用を推奨します。以下の境界条件に注意してください:
- 橋渡しスレッド内では再び同期インターフェースを呼び出せない:同期インターフェースは橋渡しスレッド内で実行され、この状態で再度同期インターフェースを呼び出すと
RuntimeErrorが発生します(再入防止の保護により、自己デッドロックを回避します)。 - 橋渡し対象のループが閉じた後に呼び出すと失敗する:
uninit()の後にストレージインターフェースを呼び出さないでください。
完全なメソッド対照は SQL クエリビルダ を参照してください。
方言の動作の違い
方言の違いはすべてフレームワーク内部で吸収され、呼び出し元のコードはその違いを意識する必要はありません。
| 差異点 | SQLite | MySQL | PostgreSQL |
|---|---|---|---|
| プレースホルダ | ? |
%s(自動変換) |
$1..$n(自動変換) |
| KV UPSERT | INSERT OR REPLACE |
ON DUPLICATE KEY UPDATE |
ON CONFLICT DO UPDATE |
| KV 値の列型 | TEXT |
LONGTEXT |
TEXT |
| 自動増分主キー | 原生サポート | AUTO_INCREMENT(自動変換) |
SERIAL(自動変換) |
列の定義はすべて SQLite のスタイルを使用します(例: "INTEGER PRIMARY KEY AUTOINCREMENT"、"TEXT NOT NULL"、"DOUBLE DEFAULT 0.0")。これらの定義は、後端のデータベースに等価な形式に自動的に変換されます。
SQLite "データベースはロックされています" のトラブルシューティング
フレームワークの SQLite バックエンドには、WAL ログモード(読み取りと書き込みが排他にならない)+ busy_timeout 5000ms(書き込みロックの競合時に自動で待機)+ autocommit 接続 + 複数のイベントループが共有接続を持つ + **トランザクション BEGIN IMMEDIATE**(2.12 以降——トランザクション開始時に書き込みロックを取得し、deferred トランザクションの「先読み後書き込み」のアップグレード時に発生する SQLITE_BUSY_SNAPSHOT を排除。この busy は再試行せず、busy_timeout でも緩和できないため、頻繁な読み書き混在下での間欠的な locked はフレームワーク内の根本原因)が内蔵されています。
2.12 以降の純粋なフレームワーク使用(ストレージ / ORM / 混合双経路の交差書き込み)では、locked が発生することはなくなります。それでも発生する場合は、以下の順序でトラブルシューティングを行ってください。
| シナリオ | 判定基準 | 対処方法 |
|---|---|---|
| トランザクション内の遅い操作 | atransaction ブロック内に外部 HTTP や大規模な計算などの遅い処理があり、ロックを保持して busy_timeout を超える |
トランザクションブロック内ではデータベース操作のみを行い、遅い処理はブロック外へ移動する |
| 第二の ORM を混用 | 同一プロセス内で sqlmodel / SQLAlchemy / 裸の sqlite3 が独自の接続で同じデータベースファイルを書き込む | 同一のデータベースファイルには 1 つの ORM を使用する(内部では非同期ネイティブ接続を使用しているため)。ORM の混用は避ける |
| 複数プロセスが同一ファイルにアクセス | 複数のインスタンス / Dashboard / データベースツールが同一の sqlite ファイルを開いている | 各インスタンスは独立した config/ ディレクトリを使用する。管理ツールは読み取り専用モードで開く。頻繁な書き込みが必要な場合は mysql / postgres に切り替える(設定変更だけでコード変更なしに移行可能) |
| 古いフレームワークバージョン | <2.12 の deferred トランザクションのアップグレード問題 |
フレームワークをアップグレードする |
busy_timeoutは現在、定数_SQLITE_BUSY_TIMEOUT_MS = 5000(Core/storage/sqlite.py)として定義されています。調整が必要な場合はソースコードの変更が必要であり、実行時の設定として公開されていません。
自定义 SQL バックエンド
純粋な SQL バックエンドは、共有基底クラスを継承し、接続管理と方言実行ファネルを提供するだけです。
from ErisPulse.Core.Bases.sql_base import SQLDialect, SQLStorageBase
class MyDialect(SQLDialect):
name = "mydb"
# オーバーライド: プレースホルダ翻訳 / イデンティファイア引用 / UPSERT / タイプマッピング ...
class MyStorage(SQLStorageBase):
dialect = MyDialect()
async def _create_loop_resource(self): ... # 接続プール
async def _destroy_loop_resource(self, r): ...
async def _acquire_resource_conn(self, r): ...
async def _release_resource_conn(self, r, c): ...
async def _open_txn_conn(self): ...
async def _close_txn_conn(self, c): ...
async def _exec_query_on(self, kind, sql, params, conn): ... # 実行ファネル
非 SQL バックエンド(例: Redis)は BaseStorage を継承して KV 非同期インターフェースを実装した後、
KVQueryBuilder を使ってチェーン式の表クエリ機能(メモリ内フィルタ、中小データ量に適している)を直接利用できます。
関連ドキュメント
- SQL クエリビルダー - チェーン式クエリ構文と非同期 API の対照表
- コアモジュール API - Storage モジュールの完全な API
- ストレージ基底クラス API - SQLStorageBase / SQLDialect 抽象インターフェース