DB 엔진과 SQL 운영

Unibase DB 엔진은 언어의 SQL 문장 표현식을 처리하는 데이터 계층이며 독립 SQL shell도 제공합니다. .uni compiler, 언어 DB SDK, DB 서버와 외부 MySQL 연결은 역할이 다릅니다. SQL 바인딩은 언어 입문, 이 장은 엔진 사용법입니다.

실행 방식 선택

방식	용도	준비할 것
독립 SQL shell	SQL을 한 줄씩 실행	준비된 `unibase` 실행 파일·새 데이터 폴더
언어의 `Database.memory()`	일시적인 프로그램 데이터	일치하는 compiler·native DB 런타임
네이티브 `Database.open(path)`	프로그램 데이터를 지정 경로에 보존	사용할 데이터 폴더 경로
`unibase.db.mysql.Database`	외부 MySQL 연결	별도 서버·driver·권한·확인된 연결 설정
DB 서버	여러 client의 연결	포트·데이터 폴더·인증·네트워크 운영 설정

shell은 unibase <데이터-폴더>로 실행하고 exit 또는 quit로 종료합니다. 제품 소스의 서버 진입점은 --server --port <포트> --data-dir <폴더>지만, 이는 운영 준비 완료를 뜻하지 않습니다. 설치·서버 시작은 해당 환경의 운영 절차를 따르세요.

처음 실행하는 SQL

새 빈 데이터 폴더와 새 작업 폴더에서만 실행하세요. 아래는 manual_demo DB를 만들고 그 DB를 백업·복원합니다. 같은 이름의 사용자 DB나 manual-backup 폴더를 사용하지 않습니다. 각 SQL은 한 줄씩 shell에 입력합니다.

CREATE DATABASE manual_demo;
USE manual_demo;
CREATE TABLE items (id BIGINT PRIMARY KEY, name VARCHAR(100));
INSERT INTO items (id, name) VALUES (1, 'Before');
BEGIN;
UPDATE items SET name = 'Changed' WHERE id = 1;
ROLLBACK;
SELECT id, name FROM items WHERE id = 1;
CREATE INDEX idx_items_name ON items (name);
EXPLAIN SELECT id FROM items WHERE name = 'Before';
BACKUP DATABASE manual_demo TO 'manual-backup';
UPDATE items SET name = 'AfterBackup' WHERE id = 1;
RESTORE DATABASE manual_demo FROM 'manual-backup';
USE manual_demo;
SELECT id, name FROM items WHERE id = 1;
SHOW METRICS;

첫 SELECT는 rollback 때문에 Before, 복원 후 SELECT도 백업 시점의 Before여야 합니다. EXPLAIN은 계획, SHOW METRICS는 관측 정보를 반환하며 업무 결과와 구분합니다.

SQL과 연결 수명

CRUD·JOIN·집계·정렬·제약은 지원하는 문법 범위에서 사용합니다. ANSI SQL 전체 또는 다른 DBMS의 함수·DDL과 완전히 호환된다고 가정하지 마세요. 외부 입력은 바인딩 API를 사용하며 문자열 연결로 SQL을 만들지 않습니다.

네이티브 Database.memory()는 전용 임시 폴더를 사용하고 close()에서 제거합니다. open(path)는 지정 경로의 데이터를 보존합니다. execute(SqlText)는 변경 결과, query(SqlText)는 ResultSet을 반환합니다. prepareInsert/Update/Delete/Select는 선언에 있지만 네이티브에서 실행할 수 없습니다.

ResultSet은 getString/getInt/getLong/getDouble/getBool/isNull로 행과 열을 읽습니다. 네이티브에서는 빈 셀을 NULL로 취급하고 숫자·bool 읽기는 NULL·타입 불일치를 오류로 처리합니다. 생성 대상의 DB 드라이버는 빈 문자열과 NULL을 구분하므로 같은 값으로 가정하지 마세요. 연결을 닫은 뒤 재사용하지 않고 행·열 존재도 먼저 확인합니다.

트랜잭션·인덱스·진단

BEGIN/COMMIT/ROLLBACK으로 변경 경계를 정합니다. 실제 다중 연결·동시 실행·복구 동작은 별도 검증이 필요합니다. 인덱스는 조회 조건에 맞게 만들고 EXPLAIN·실제 응답을 비교합니다. 이름만으로 특정 index가 선택된다고 판단하지 않습니다.

운영 질문	확인 기능
어떤 계획으로 조회하는가	`EXPLAIN SELECT ...`
엔진 상태는 어떤가	`SHOW METRICS`
느린 질의가 있는가	`SHOW SLOW QUERIES`
스키마가 바뀌었는가	`SHOW SCHEMA FINGERPRINT`
변경을 되돌릴 수 있는가	트랜잭션 rollback과 백업 restore를 구분

사용자·역할·권한

엔진은 CREATE/ALTER USER, LOGIN, GRANT/REVOKE와 역할 카탈로그를 갖습니다. 사용자 생성·인증, DB/테이블 권한, 역할 상속을 분리해 확인합니다. 실사용 계정은 최소 권한으로 시험하고 권한 부족이 실제 거절되는지 확인하세요. 예제 암호·관리자 세션을 그대로 운영에 사용하지 않습니다.

고급 데이터 기능

기능	사용하는 목적	별도로 확인할 사항
DOCUMENT	반정형 데이터와 필드 조회	JSON 경로·인덱스·지원 연산
FILE	파일 참조·내용·메타데이터	파일 저장소·크기·수명·권한
VECTOR(n)	임베딩과 유사도	차원·거리 함수·인덱스·정확도
METADATA	태그·속성	필터와 인덱스 계약
HISTORY(n)	컬럼의 제한된 값 이력	보관 개수·조회·갱신 의미
메모리 테이블	key/value·hash·TTL	영속 테이블과 다른 수명·복구
LLM provider·job	DB의 AI 작업 구성	provider·비밀값·비동기 결과·실행 지원

이 표는 소스에 있는 기능의 안내이며 모두의 실제 실행을 인증한 표가 아닙니다. LLM provider 선언이나 job 접수가 외부 모델 호출 성공을 뜻하지 않습니다. 기존 서비스 MCP는 라이브러리 조회용이므로 DB의 LLM 기능과 혼동하지 마세요.

백업·복원과 내구성

BACKUP/RESTORE는 별도 경로와 manifest를 사용합니다. 원본 DB와 백업 경로가 겹치지 않아야 하며 실제 복원 후 핵심 데이터·스키마·권한을 재조회합니다. 백업 파일의 존재만으로 복구 가능하다고 판정하지 않습니다.

백업·복원은 데이터가 저장되는 환경에서 시험하세요. 전원 차단이나 복구 중 재중단에 대비하려면 사용 중인 DB 버전과 저장 방식의 내구성 제한을 확인하고 별도의 백업을 유지해야 합니다.