Database 매뉴얼 시작

QMachineStudio 는 SQLite 와 MSSQL 두 가지 데이터베이스를 같은 인터페이스로 다룹니다. 화면에서 연결을 등록하고, 스크립트(.xms)에서 키워드 한 줄로 접근하며, GUI 의 DataGrid 컨트롤에 array 변수를 연결해 결과를 표시하는 흐름입니다.

캡처 대기

public/manual/gui/database-overview.png

Database 매뉴얼 학습 흐름

핵심 키워드 — `X.DB["name"]`

스크립트에서 데이터베이스 연결은 항상 이름으로 접근합니다. IO["..."], MOTOR["..."] 같은 관용구와 동일합니다.

// 연결 열기
X.DB["local"].Open();
 
// SELECT (소량) 결과 캐싱
X.DB["local"].RunSqlSelect("SELECT * FROM order_history ORDER BY id DESC LIMIT 50");
int rows = X.DB["local"].RowCount;
 
// 단일 값
int today = X.DB["local"].RunSqlScalarInt(
   "SELECT COUNT(*) FROM order_history WHERE start_time LIKE '2026-05-01%'");

local 은 Database Connection 화면에서 등록한 이름입니다. 한 프로젝트에 여러 연결을 등록할 수 있고 스크립트에서는 동일한 패턴으로 골라 씁니다 (X.DB["mes"], X.DB["audit"] 등).

QMachineStudio 가 제공하는 세 화면

화면	역할
Database Connection	연결 이름 · 타입 · 파일 경로 등록. 백업 옵션 설정
Database Studio	스키마(Structure) · 데이터(Data) · SQL 직접 실행(SQL) 세 탭
Database Events	`OnDbOpened` · `OnDbError` · `OnBackupDone` 등 이벤트 핸들러 자동 생성

세 화면은 모두 Solution Explorer 의 Data Editor Pages → Database 아래에서 진입합니다.

학습 흐름 — 8 단계

#	단계	화면/도구
1	개요 (이 문서)	—
2	DB 연결 등록	Database Connection
3	스키마 적용 (빌트인 템플릿)	Database Studio · Structure
4	SQL · Data 탭으로 동작 확인	Database Studio · SQL / Data
5	스크립트로 INSERT · UPDATE	`.xms` 모듈
6	스크립트로 SELECT · 트랜잭션	`.xms` 모듈
7	DataGrid 에 array 연결	XDesigner
8	이벤트 후킹 + 백업	Database Events / 스크립트

각 단계는 다음 단계의 입력이 됩니다. 이 화면에서 등록한 이름은 다음 화면의 콤보로, 이 화면에서 만든 테이블은 다음 단계 스크립트의 SELECT 대상으로, 스크립트가 채운 array 변수는 DataGrid 의 DataName 프로퍼티로 그대로 이어집니다.

빌트인 템플릿 `order_history` 사용

이 매뉴얼은 처음부터 끝까지 빌트인 템플릿 order_history 한 가지 시나리오로 진행합니다. Database Studio 의 Structure 탭 → Template 콤보에서 그대로 선택할 수 있어 컬럼 설계에 시간을 쓸 필요가 없습니다.

컬럼	타입	비고
`id`	integer	PK · AutoIncrement
`order_no`	text	NOT NULL
`menu_name`	text	메뉴 이름
`start_time`	text	default `CURRENT_TIMESTAMP`
`end_time`	text	조리 종료 시각
`weight_g`	real	default 0 — 계량 결과 (g)
`result`	text	OK / NG / SKIP
`is_error`	integer	default 0 — 에러 플래그

인덱스도 함께 만들어집니다.

인덱스	컬럼
`idx_order_no`	`order_no`
`idx_order_start`	`start_time`

log 테이블 (시간/레벨/메시지) 도 빌트인이라, 운영 로그를 별도 코드 없이 적재할 때 유용합니다.

파일은 어디에 저장되는가

SQLite 의 경우 별도 경로를 지정하지 않으면 프로젝트 폴더 아래 XDatabase\ 안에 자동 생성됩니다.

<프로젝트 루트>
└── XDatabase
    ├── local.db                 ← Database Connection 의 Name=local
    ├── XDatabaseOption.json     ← 연결 옵션 파일
    ├── Schema/                  ← (선택) Save JSON 으로 보관한 스키마
    └── Backup/                  ← Backup() 호출 결과

같은 프로젝트의 여러 연결도 모두 이 폴더에 모이므로, 운영 중 백업/이관이 단순합니다.

학습 포인트

GUI 는 ‘선언/검증’ 도구, 스크립트는 ‘실행/자동화’ 도구. 화면에서 연결과 스키마를 한 번 만들고, 스크립트는 그 위에서 데이터를 넣고 빼는 일만 합니다.
DataGrid 에는 XAML 바인딩이 아니라 array 변수를 ‘이름으로’ 연결합니다. XDesigner 속성창의 DataName 에 모듈명::배열변수명 을 적습니다. 자세한 내용은 7장에서 다룹니다.
에러 가시성은 한 줄로 외우십시오. LastError (속성) → OnDbError (이벤트) → XLog.AddError (운영 로그) — 세 단계가 모두 기록됩니다.

다음 단계

2장 — DB 연결 등록