
# SQLite

SQLite はサーバーを持たない、ファイルの中のデータベースです。`sqlite3` パッケージを挙げ、`sqlite:` の URL を指定すれば、スターターは生成された `SqliteBinding` と `sqliteJdbcDriver` を通してそれを開きます。Flutter アプリ、コマンドラインツール、小さなサーバー、そしてテスト (`@DataTest` はメモリ上の SQLite データベースを使います) に向いています。

## 使う理由

多くのアプリケーションには、本物の SQL データベースは必要でも、データベースサーバーは必要ありません。スマートフォンのアプリ、デスクトップのツール、単一インスタンスのサービスなどです。SQLite は、一つのファイルでトランザクション、インデックス、SQL を提供します。スターターを使えば、同じリポジトリとマイグレーションが、Flutter アプリでは SQLite で、サーバーでは PostgreSQL で動きます。

## 例

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_data: ^0.9.0
  sqlite3: ^3.8.0
```

```properties
# 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 の方言を自分で追加します。ここでは、方言、ドライバーとの連携、型のマッピングがスターターに含まれています。

## 関連項目

- [データソース](data-sources.md)
- [PostgreSQL](postgresql.md)
- [テスト](testing.md)
