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()`	DB 연결 + (비어있으면) 샘플 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` 외

샘플을 실행해 결과를 직접 확인하면서 챕터를 따라가는 것을 권장합니다.