Database マニュアル · Chapter 1

Database チュートリアル開始

本チュートリアルは、QMachineStudio に同梱されている SampleProject/Database/DB_Sqlite プロジェクトを最初から最後まで辿りながら、データベース機能を学ぶ構成です。

サンプルは SQLite ひとつで動く小さなツールで、オーダー作業履歴(order_history テーブル)を画面で登録 · 修正 · 削除します。本マニュアルに登場するコードはすべて、このプロジェクトの RunScript/*.xms から抜粋しています。

サンプルプロジェクトの場所

SampleProject/Database/DB_Sqlite/
├── DB_Sqlite.xmp                  # プロジェクトファイル(DatabaseOption を含む)
├── XDatabase/
│   ├── connections.json           # 接続設定(DB Studio と同期)
│   └── LocalDB.db                 # 実体の SQLite ファイル(自動生成)
└── RunScript/
    ├── Data.xms                   # DB_* 関数 (Open/Refresh/Insert/Update/Delete/...)
    ├── ViewRun.xms                # ボタンハンドラ (OnOpenClick / OnAddClick / ...)
    ├── ModifyDlg.xms              # レコード編集ダイアログ
    └── (その他 Init / Mon / Event / ViewMain ...)

画面構成 — ViewRun

ランページ(ViewRun)は 6 つのボタンと 1 つの XDataGrid で構成されます。

ボタン	呼び出し関数	動作
Open	`Data::DB_Open()`	接続 +(空なら)サンプル 5 件挿入 + DataGrid 更新
Add	`Data::DB_InsertSample()`	新規オーダーを 1 件 INSERT
Update	`Data::DB_UpdateSelected()`	選択行を完了(end_time / result)処理
Modify	`Data::DB_OpenModifyDlg()`	ダイアログを表示し自由編集 → OK で UPDATE
Delete	`Data::DB_DeleteSelected()`	選択行を 1 件削除
Close	`Data::DB_Close()`	接続終了 + DataGrid を空に

上部のラベル(Data::DbStatusText、● OPEN / ● CLOSED)が現在の接続状態を表示します。

中心キーワード — `DB["接続名"]`

スクリプトでは、データベースは常に接続名でアクセスします。サンプルの接続名は local ひとつです。

// 接続を開く
DB["local"].Open();
 
// SELECT して RowCount / GetRowArray で結果を読む
DB["local"].RunSqlSelect("SELECT id, order_no, menu_name FROM order_history ORDER BY id ASC");
int rows = DB["local"].RowCount;
 
// 単一値
int total = DB["local"].RunSqlScalarInt("SELECT COUNT(*) FROM order_history");
 
// パラメータバインディング(SQL インジェクション防止)
array p[] = {""};  p.Clear();
p.Add("O1234"); p.Add("Latte"); p.Add(SYS.DateTimeString);
DB["local"].RunSqlQueryParam(
    "INSERT INTO order_history(order_no, menu_name, start_time) VALUES(?,?,?)",
    p);
 
// トランザクション
DB["local"].BeginTransaction();
DB["local"].RunSqlQueryParam(/* ... */);
if( DB["local"].Commit() == false ) DB["local"].Rollback();
 
// 接続終了
DB["local"].Close();

IO["..."]、MOTOR["..."] と同じ「名前で引く」慣用句で、初めて触れても違和感がありません。

学習の流れ

章	テーマ	扱うサンプルコード
2	接続設定 — `connections.json` とプロジェクトオプション	`DB_Sqlite.xmp` `DatabaseOption`
3	テーブルスキーマ — `order_history`	`DB_InsertInitialSamples`
4	DB Studio の SQL · Data タブで動作検証	—
5	INSERT · UPDATE — パラメータバインディングとトランザクション	`DB_InsertSample` · `DB_UpdateSelected`
6	SELECT — `RowCount` · `GetRowArray` · `RunSqlScalarInt`	`DB_Refresh`
7	DataGrid · ModifyDlg バインディング	`DispData` · `SelectIndex` · `Edit*`
8	ボタンイベント — `ViewRun` ハンドラ	`OnOpenClick` 他 5 つ
9	バックアップ · WAL · 運用チェックポイント	`DatabaseOption.BackupFolder` 他

サンプルを動かしながら結果を確認しつつ章を進めることを推奨します。