SQLite
SQLite はサーバーを持たない、ファイルの中のデータベースです。sqlite3 パッケージを挙げ、sqlite: の URL を指定すれば、スターターは生成された SqliteBinding と sqliteJdbcDriver を通してそれを開きます。Flutter アプリ、コマンドラインツール、小さなサーバー、そしてテスト (@DataTest はメモリ上の SQLite データベースを使います) に向いています。
使う理由
多くのアプリケーションには、本物の SQL データベースは必要でも、データベースサーバーは必要ありません。スマートフォンのアプリ、デスクトップのツール、単一インスタンスのサービスなどです。SQLite は、一つのファイルでトランザクション、インデックス、SQL を提供します。スターターを使えば、同じリポジトリとマイグレーションが、Flutter アプリでは SQLite で、サーバーでは PostgreSQL で動きます。
例
# pubspec.yaml
dependencies:
spring_boot_starter_data: ^0.9.0
sqlite3: ^3.8.0
# lib/resources/application.properties
spring.datasource.url=sqlite:file:library.db
spring.datasource.sqlite.base-directory=/var/lib/library
spring.datasource.sqlite.busy-timeout=2000
spring.datasource.sqlite.isolate=true
spring.datasource.pool.max-size=4
sqlite3 を追加した後、ジェネレーターを一度実行してください。バインディングとドライバーの Bean を書きます。
URL
| URL | データベース |
|---|---|
sqlite:file:library.db |
base-directory からの相対のファイル。 |
sqlite:file:/var/lib/library/library.db |
絶対パス。 |
sqlite::memory: |
メモリ上。接続ごとに独自のデータベースを持ち、同梱の SQLite には共有キャッシュがない: pool.max-size=1、pool.min-idle=0、pool.idle-timeout=0、pool.max-lifetime=0 を使う。そうしないと、プールが接続を閉じたときにデータが失われる。 |
設定
| キー | デフォルト | 意味 |
|---|---|---|
spring.datasource.sqlite.busy-timeout |
5000 |
CannotAcquireLockException までに、接続が SQLite のロックを待つミリ秒。 |
spring.datasource.sqlite.base-directory |
作業ディレクトリ | 相対の sqlite:file: の名前を探す場所。SqliteJdbcDriver.baseDirectory より優先される。 |
spring.datasource.sqlite.isolate |
false |
true は各接続を専用の Isolate の中で開く。SqliteJdbcDriver(isolate:) より優先される。 |
spring.datasource.sqlite.location |
support |
Flutter スターターだけが読む: support、cache、documents。base-directory に設定するアプリのディレクトリ。 |
同じキーが spring.datasources.<name>.sqlite.* の下にも、spring.datasource.sqlite3.* (ドライバーの名前が優先される) としても存在します。
専用の Isolate
SQLite の呼び出しは同期的です。Flutter の UI の Isolate やサーバーのイベントループでは、長いクエリやロックの待機が他のすべてを止めてしまいます。spring.datasource.sqlite.isolate=true では、各接続はワーカーの Isolate の中でデータベースを開き、すべての文はそれへのメッセージになります。
それ以外は何も変わりません。トランザクション、セーブポイント、読み取り専用モード、ストリーム (行はまとめて届き、ストリームがキャンセルされるとカーソルは閉じられます)、そして型を含むエラーは、以前と同じく動きます。知っておくべきこと:
- 値は Isolate 間でコピーされるため、非常に大きな結果はコピーのコストがかかります。
- 接続は閉じなければならず、それがその Isolate を終わらせます。プールはアプリケーションが閉じるときにそれを行います。
- Isolate が終了すると、保留中とそれ以降の文は、
connectionLostがtrueのSqlErrorで失敗します。 - 生成された
SqliteBindingは Isolate に送られるため、独自のバインディングはネイティブのリソースを持ってはいけません。 sqlite3パッケージのローダーのオーバーライド (open.overrideFor(...)) は、それを実行した Isolate のものです。mainで行ったものはワーカーに届かず、スターターにはワーカーでコードを実行するフックがありません。プラットフォームがオーバーライドを必要とする場合は、isolate=falseのままにしてください。
Flutter アプリで
spring_boot_starter_flutter は、アプリが SQL データベースを構成すると 2 つのプロパティを設定します。base-directory をアプリ自身のディレクトリ (spring.datasource.sqlite.location で選ぶ) に、そして isolate=true です。これらは最も優先度が低いため、自分のプロパティが優先されます。スターターは互いに依存しません。Flutter スターターはプロパティを設定するだけです。
location |
ディレクトリ |
|---|---|
support (デフォルト) |
アプリのプライベートなデータ。システムが削除することはなく、デバイスとともにバックアップされる。Android では、アプリの databases/ ディレクトリ。 |
cache |
容量が足りなくなると削除されることがある: 作り直せるデータベース向け。 |
documents |
ユーザーのドキュメントフォルダー。 |
それ以外の値は、この 3 つを示して起動を止めます。Web にはそうしたディレクトリがないため、そこでは何も設定されません。
値の保存方法
| Dart | SQLite |
|---|---|
int、bool (0 または 1) |
INTEGER |
double、num |
REAL |
String、列挙型 |
TEXT |
DateTime |
UTC の ISO 8601 の TEXT (2026-03-01T10:00:00.000Z)。時点と同じ順に並ぶ。読み戻した整数はエポックからのミリ秒とみなされる |
Uint8List、List<int> |
BLOB |
BigInt |
TEXT。INTEGER は 64 ビットしか保持できないため |
生成される ID は INTEGER PRIMARY KEY です。
トランザクションとロック
- 分離レベルは serializable だけです。
Isolation.defaultLevelとIsolation.serializableは受け入れられ、それ以外はInvalidIsolationLevelExceptionです。 - 行ロックはありません。
@Lockのクエリを持つトランザクションは、開始時にデータベース全体の書き込みロックを取ります (BEGIN IMMEDIATE)。@LockのtimeoutとskipLockedは無視され、ビジータイムアウトが適用されます。 - セーブポイントが
Propagation.nestedを提供します。 - 外部キーは有効 (
foreign_keys = ON) なので参照は強制され、メモリ上のストアも同じように動作します。
テキスト
- テキストは、照合順序ではなく、メモリ上のストアと同じくコードユニットで比較されます。
IgnoreCaseは、ドライバーが各接続に登録するlower関数 (Dart のtoLowerCase) を使います。SQLite 自身のものは ASCII しか畳み込まないためです。- 派生の
Inは要素ごとに一つの値をバインドします。SQLite は一つの文に 32 766 個の値まで許し、それより長いリストは明確なメッセージとともに拒否されます。
Spring (Java) との対応
Spring Boot には独自の SQLite のサポートがありません。JDBC ドライバーと、Hibernate の方言か Spring Data JDBC の方言を自分で追加します。ここでは、方言、ドライバーとの連携、型のマッピングがスターターに含まれています。