PRAGMA 문
PRAGMA 문 (PRAGMA Statements)
PRAGMA 문은 데이터베이스 설정을 조회하거나 수정하고, 메타데이터를 꺼내고, 데이터베이스 동작을 제어하는 특수 명령이에요. 표준 SQL과 달리 PRAGMA는 SQLite와 Turso에 특화된 기능이에요.
출처: 문서
본문
PRAGMA 문은 데이터베이스 설정을 조회하거나 수정하고, 메타데이터를 얻고, 데이터베이스 동작을 제어하는 데 쓰는 특수 명령이에요. 표준 SQL과 달리, PRAGMA는 SQLite와 Turso에 고유한 것이에요.
문법
PRAGMA pragma-name;
PRAGMA pragma-name = value;
PRAGMA pragma-name(value);
데이터베이스 메타데이터
database_list
붙어 있는(attached) 데이터베이스마다 한 행을 반환해요.
PRAGMA database_list;
-- seq | name | file
-- 0 | main | /path/to/database.db
page_count
데이터베이스 파일의 전체 페이지 수를 반환해요.
PRAGMA page_count;
-- 42
page_size
데이터베이스의 페이지 크기를 반환하거나 설정해요. 페이지 크기는 테이블을 만들기 전에만 설정할 수 있어요.
PRAGMA page_size;
-- 4096
PRAGMA page_size = 8192;
max_page_count
데이터베이스 파일에 허용되는 최대 페이지 수를 반환하거나 설정해요.
PRAGMA max_page_count;
PRAGMA max_page_count = 1000000;
freelist_count
데이터베이스 파일에서 사용되지 않는 페이지 수를 반환해요.
PRAGMA freelist_count;
encoding
데이터베이스가 쓰는 텍스트 인코딩을 반환해요.
PRAGMA encoding;
-- UTF-8
schema_version
스키마 버전 번호를 반환해요. 스키마가 바뀔 때마다 이 값이 1씩 증가해요.
PRAGMA schema_version;
-- 5
application_id
데이터베이스 헤더에 저장된 애플리케이션 ID를 반환하거나 설정해요. 애플리케이션은 이 32비트 정수로 데이터베이스 파일 형식을 식별할 수 있어요.
PRAGMA application_id;
PRAGMA application_id = 12345;
user_version
사용자 버전 번호를 반환하거나 설정해요. 애플리케이션이 자유롭게 쓸 수 있는 32비트 정수예요.
PRAGMA user_version;
PRAGMA user_version = 3;
스키마 내성(introspection)
table_info
이름 붙은 테이블의 컬럼마다 한 행을 반환해요.
PRAGMA table_info(table-name);
| 컬럼 | 타입 | 설명 |
|---|---|---|
| cid | INTEGER | 컬럼 인덱스 (0부터 시작) |
| name | TEXT | 컬럼 이름 |
| type | TEXT | 선언된 타입 이름 |
| notnull | INTEGER | NOT NULL 제약이 있으면 1 |
| dflt_value | TEXT | 기본값 표현식, 또는 NULL |
| pk | INTEGER | 컬럼이 PRIMARY KEY에 속하면 1 |
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT);
PRAGMA table_info(users);
-- cid | name | type | notnull | dflt_value | pk
-- 0 | id | INTEGER | 0 | | 1
-- 1 | name | TEXT | 1 | | 0
-- 2 | email | TEXT | 0 | | 0
table_xinfo
table_info와 비슷하지만 숨겨진 컬럼과 추가 메타데이터도 포함해요.
PRAGMA table_xinfo(table-name);
table_info와 같은 컬럼에 hidden 컬럼이 더해져요 (일반 컬럼은 0, 가상 테이블의 숨겨진 컬럼은 0이 아니에요).
table_list
데이터베이스의 테이블과 뷰마다 한 행을 반환해요.
PRAGMA table_list;
-- schema | name | type | ncol | wr | strict
-- main | users | table | 3 | 0 | 0
-- main | orders | table | 4 | 0 | 0
index_list
이름 붙은 테이블의 인덱스마다 한 행을 반환해요.
PRAGMA index_list(table-name);
-- seq | name | unique | origin | partial
-- 0 | idx_email | 1 | c | 0
| 컬럼 | 타입 | 설명 |
|---|---|---|
| seq | INTEGER | 인덱스 순번 |
| name | TEXT | 인덱스 이름 |
| unique | INTEGER | 인덱스가 UNIQUE이면 1 |
| origin | TEXT | CREATE INDEX면 c, UNIQUE 제약이면 u, PRIMARY KEY면 pk |
| partial | INTEGER | 부분(partial) 인덱스면 1 |
index_info
이름 붙은 인덱스의 컬럼마다 한 행을 반환해요.
PRAGMA index_info(index-name);
-- seqno | cid | name
-- 0 | 2 | email
index_xinfo
index_info와 비슷하지만 추가 컬럼을 포함해요.
PRAGMA index_xinfo(index-name);
function_list
사용 가능한 SQL 함수마다 한 행을 반환해요.
PRAGMA function_list;
-- name | builtin | type | enc | narg | flags
pragma_list
지원되는 모든 PRAGMA 명령의 목록을 반환해요.
PRAGMA pragma_list;
데이터베이스 설정
journal_mode
저널 모드를 반환하거나 설정해요.
PRAGMA journal_mode;
-- wal
PRAGMA journal_mode = wal;
Turso는 WAL(Write-Ahead Logging) 모드를 지원해요. 롤백 저널 모드(DELETE, TRUNCATE, PERSIST, MEMORY)는 지원되지 않아요.
**Turso 확장 기능**: Turso는 동시 쓰기를 위한 실험적 MVCC 저널 모드를 지원해요:PRAGMA journal_mode = mvcc;
MVCC 모드가 활성화되어 있으면, 낙관적 동시 쓰기 트랜잭션에 BEGIN CONCURRENT를 쓸 수 있어요. 자세한 내용은 트랜잭션을 참고하세요.
cache_size
메모리에 유지할 데이터베이스 페이지의 권장 최대 개수를 반환하거나 설정해요.
PRAGMA cache_size;
PRAGMA cache_size = 2000; -- positive: number of pages
PRAGMA cache_size = -2000; -- negative: kilobytes of memory
cache_spill
캐시 스플링(캐시가 가득 차기 전에 더러운 페이지를 WAL에 기록)을 켜거나 꺼요.
PRAGMA cache_spill;
PRAGMA cache_spill = 0; -- disable
PRAGMA cache_spill = 1; -- enable
synchronous
내구성 보장을 위한 fsync 동작을 제어해요.
PRAGMA synchronous;
PRAGMA synchronous = OFF; -- no fsync (fastest, risk of corruption on crash)
PRAGMA synchronous = FULL; -- fsync after every transaction (safest)
Turso에서는 OFF와 FULL만 지원돼요.
temp_store
임시 테이블과 인덱스를 어디에 저장할지 제어해요.
PRAGMA temp_store;
PRAGMA temp_store = 0; -- DEFAULT
PRAGMA temp_store = 1; -- FILE
PRAGMA temp_store = 2; -- MEMORY
busy_timeout
바쁨(busy) 타임아웃을 밀리초 단위로 설정해요. 테이블이 잠겨 있을 때 Turso는 SQLITE_BUSY를 반환하기 전에 이 밀리초만큼 기다려요.
PRAGMA busy_timeout;
PRAGMA busy_timeout = 5000; -- 5 seconds
query_only
활성화하면 데이터베이스에 어떤 변경도 못 하게 막아요.
PRAGMA query_only = 1; -- enable read-only mode
PRAGMA query_only = 0; -- disable read-only mode
foreign_keys
외래 키 제약 강제를 켜거나 꺼요.
PRAGMA foreign_keys;
PRAGMA foreign_keys = ON;
PRAGMA foreign_keys = OFF;
외래 키 강제는 SQLite 호환성을 위해 기본으로 꺼져 있어요.
legacy_file_format
레거시 파일 형식 플래그를 반환해요.
PRAGMA legacy_file_format;
ignore_check_constraints
활성화하면 CHECK 제약이 강제되지 않아요.
PRAGMA ignore_check_constraints = 1; -- disable CHECK constraints
PRAGMA ignore_check_constraints = 0; -- enable CHECK constraints
data_sync_retry
디스크 동기화(fsync)가 실패했을 때 치명적으로 취급하는 대신 재시도할지 제어해요.
PRAGMA data_sync_retry = 1; -- retry on sync failure
PRAGMA data_sync_retry = 0; -- do not retry (default)
require_where
**Turso 확장 기능**: SQLite에는 없는 안전성 프라그마예요.활성화하면 WHERE 절이 없는 UPDATE나 DELETE를 거절해서, 실수로 테이블 전체를 고치는 사고를 막아줘요. i_am_a_dummy는 같은 동작을 켜는 별칭이에요.
PRAGMA require_where = 1;
DELETE FROM users; -- rejected: no WHERE clause
DELETE FROM users WHERE id = 1; -- allowed
PRAGMA i_am_a_dummy = 1; -- equivalent to require_where = 1
무결성 검사
integrity_check
데이터베이스 전체를 철저히 무결성 검사해요.
PRAGMA integrity_check;
-- ok
PRAGMA integrity_check(N); -- check only the first N errors
문제가 없으면 ok를 반환하고, 아니면 오류마다 한 행씩 반환해요.
quick_check
integrity_check보다 빠르지만 덜 철저한 무결성 검사를 해요.
PRAGMA quick_check;
WAL 연산
wal_checkpoint
WAL 체크포인트를 강제해요.
PRAGMA wal_checkpoint;
체크포인트는 WAL 파일의 페이지를 데이터베이스 파일로 기록해요.
MVCC 튜닝
**Turso 확장 기능**: 이 프라그마들은 MVCC 모드가 활성화되어 있을 때만 적용돼요 (`PRAGMA journal_mode = mvcc`).mvcc_checkpoint_threshold
Turso가 MVCC 체크포인트를 트리거하기 전에 쌓이는 커밋된 작업량을 설정해요.
PRAGMA mvcc_checkpoint_threshold = 1000;
mvcc_gc_threshold
Turso가 쓸모없는 MVCC 행 버전을 얼마나 공격적으로 가비지 컬렉션할지 제어하는 임계값을 설정해요.
PRAGMA mvcc_gc_threshold = 1000;
변경 데이터 캡처 (CDC)
**Turso 확장 기능**: CDC(Change Data Capture)는 복제, 감사, 리액티브 애플리케이션을 위해 모든 데이터 변경을 추적하는 Turso 전용 기능이에요.capture_data_changes_conn
현재 연결에 CDC를 켜요. 변경 사항은 지정된 테이블에 기록돼요.
PRAGMA capture_data_changes_conn('mode');
PRAGMA capture_data_changes_conn('mode,table_name');
레거시 이름 unstable_capture_data_changes_conn도 하위 호환성을 위해 계속 받아들여져요.
| 매개변수 | 설명 |
|---|---|
| mode | 캡처 모드: off, id, before, after, full |
| table_name | 변경 사항을 저장할 커스텀 테이블 이름 (기본값: turso_cdc) |
캡처 모드
| 모드 | 설명 |
|---|---|
off |
이 연결에서 CDC 끄기 |
id |
변경된 행의 기본 키/rowid만 캡처 |
before |
변경 전 행 상태 캡처 (UPDATE/DELETE용) |
after |
변경 후 행 상태 캡처 (INSERT/UPDATE용) |
full |
변경 전·후 상태 모두 캡처 + 업데이트 세부 정보 |
CDC 테이블 구조
CDC 테이블에는 다음 컬럼이 있어요:
| 컬럼 | 타입 | 설명 |
|---|---|---|
| change_id | INTEGER | 자동 증가하는 고유 식별자 |
| change_time | INTEGER | Unix epoch 타임스탬프 |
| change_type | INTEGER | 1 (INSERT), 0 (UPDATE), -1 (DELETE) |
| table_name | TEXT | 변경된 테이블 이름 |
| id | varies | 변경된 행의 기본 키/rowid |
| before | BLOB | 변경 전 행 데이터 (모드: before, full) |
| after | BLOB | 변경 후 행 데이터 (모드: after, full) |
| updates | BLOB | 업데이트된 컬럼 세부 정보 (모드: full) |
CDC 예제
-- Enable full CDC
PRAGMA capture_data_changes_conn('full');
-- Make changes
CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
INSERT INTO users VALUES (1, 'Alice');
UPDATE users SET name = 'Alicia' WHERE id = 1;
DELETE FROM users WHERE id = 1;
-- Query the changes
SELECT change_type, table_name, id FROM turso_cdc;
-- 1 | users | 1 (INSERT)
-- 0 | users | 1 (UPDATE)
-- -1 | users | 1 (DELETE)
-- Use a custom table name
PRAGMA capture_data_changes_conn('full,audit_log');
-- Disable CDC
PRAGMA capture_data_changes_conn('off');
CDC는 트랜잭션 경계를 존중해요. 변경 사항은 트랜잭션이 커밋될 때만 기록돼요. 트랜잭션이 롤백되면 CDC 항목은 만들어지지 않아요.
암호화
**Turso 확장 기능**: 저장 시(at-rest) 암호화는 Turso 전용 기능이에요. 이 기능은 실험적이며 사용 전에 [활성화](/sql-reference/experimental-features)해야 해요.cipher
데이터베이스의 암호화 암호(cipher)를 설정해요.
PRAGMA cipher = 'aegis256';
지원되는 암호:
| 암호 | 키 크기 | 설명 |
|---|---|---|
aes128gcm |
16 bytes | Galois/Counter Mode의 AES-128 |
aes256gcm |
32 bytes | Galois/Counter Mode의 AES-256 |
aegis128l |
16 bytes | AEGIS-128L |
aegis256 |
32 bytes | AEGIS-256 (권장) |
aegis128x2 |
16 bytes | 2배 병렬화를 쓰는 AEGIS-128 |
aegis128x4 |
16 bytes | 4배 병렬화를 쓰는 AEGIS-128 |
aegis256x2 |
32 bytes | 2배 병렬화를 쓰는 AEGIS-256 |
aegis256x4 |
32 bytes | 4배 병렬화를 쓰는 AEGIS-256 |
hexkey
암호화 키를 16진수 문자열로 설정해요.
PRAGMA hexkey = '2d7a30108d3eb3e45c90a732041fe54778bdcf707c76749fab7da335d1b39c1d';
암호화 예제
-- Set cipher and key before creating tables
PRAGMA cipher = 'aegis256';
PRAGMA hexkey = '2d7a30108d3eb3e45c90a732041fe54778bdcf707c76749fab7da335d1b39c1d';
CREATE TABLE secrets (id INTEGER PRIMARY KEY, data TEXT);
INSERT INTO secrets VALUES (1, 'sensitive data');
데이터베이스 URI에 암호화 매개변수를 지정할 수도 있어요:
file:database.db?cipher=aegis256&hexkey=2d7a30...
기존 암호화 데이터베이스를 열 때는 암호와 키를 반드시 URI 매개변수로 제공해야 해요.
커스텀 타입
**Turso 확장 기능**: 커스텀 타입은 Turso 전용 기능이에요.list_types
사용 가능한 모든 타입(내장 + 커스텀)을 메타데이터와 함께 나열해요.
PRAGMA list_types;
-- type | parent | encode | decode | default | operators
-- INTEGER | | | | |
-- REAL | | | | |
-- TEXT | | | | |
-- BLOB | | | | |
-- ANY | | | | |
커스텀 타입 만들기는 CREATE TYPE을 참고하세요.
더 알아보기 (Learn more)
- 트랜잭션 - 트랜잭션 제어
- CREATE TYPE - 커스텀 타입 정의
- 호환성 - 지원되는 PRAGMA 전체 목록