SQLite on Dev TLDRLSS

SQLite의 관대함에 속지 마라! 동적 타입의 함정이란? ALTER TABLE은 왜 미완성인가? Node.js에서 방어적 프로그래밍으로 매끄러운 테이블 마이그레이션을 구현하는 방법

Tue, 19 May 2026 18:10:00 +0800

재활용 수거함에 ‘페트병 전용’이라는 라벨을 붙여 놓았는데, 누군가 종이 조각을 집어넣어도 아무런 항의 없이 묵묵히 받아들이는 모습을 상상해 보세요.

이것이 바로 개발자가 SQLite 타입 시스템을 처음 만났을 때 겪게 되는 등골 오싹한 경험입니다.

타입이 맞지 않으면 즉시 입국을 거부하는 PostgreSQL 같은 엄격한 세관 스타일에 익숙하다면, SQLite 소탈함(또는 느슨함)에 인생을 의심하게 될지도 모릅니다.

더 끔찍한 것은, 테이블 구조를 변경하려고 할 때 그것이 당신에게 이렇게 말한다는 것입니다:

“테이블을 직접 수정할 수 없습니다. 새 집을 짓고, 가구를 옮긴 다음, 오래된 집을 폭파하세요.”

SQLite의 내부에는 5가지 스토리지 클래스만 존재한다

CREATE TABLE에서 아무리 화려한 타입 이름(VARCHAR(255), BIGINT, DECIMAL)을 선언하더라도, SQLite 내부적으로는 다음 5가지 스토리지 클래스만 인식합니다:

스토리지 클래스	설명
NULL	빈 값
INTEGER	정수 (값의 크기에 따라 자동으로 1~8 바이트 점유)
REAL	부동 소수점 수 (고정 8 바이트)
TEXT	문자열 (기본 UTF-8 인코딩)
BLOB	바이너리 데이터 (입력된 상태 그대로 저장)

컬럼에 설정한 타입은 SQLite에게 단지 ‘권장 사항’일 뿐이며, ‘강제 규칙’이 아닙니다.

이를 **“타입 어피니티(Type Affinity)”**라고 부릅니다. SQLite는 데이터를 권장 타입으로 변환하려고 시도하지만, 변환할 수 없는 경우에는 에러 없이 원본 데이터를 그대로 삽입합니다.

SQLite에서 age INTEGER 컬럼을 선언하고 문자열 '영원한 18세'를 삽입해도 아주 기쁘게 받아들여집니다.

가장 쉽게 빠지기 쉬운 3가지 타입 함정

함정 1: 네이티브 Boolean 부재

SQLite에는 Boolean 타입이 없습니다. True와 False는 정수 1과 0으로만 표현할 수 있습니다.

Node.js를 사용해 SQLite에서 데이터를 조회할 때, true나 false가 아니라 숫자 1 또는 0이 반환됩니다.

if (user.is_admin === true)와 같은 조건식을 직접 사용하면 절대 참이 되지 않습니다.

함정 2: Date/Time 타입 부재

SQLite에는 날짜 시간 타입이 없습니다. 시간은 다음과 같이 저장할 수밖에 없습니다:

저장 방식	예시	장단점
TEXT (ISO-8601 문자열)	`'2026-05-19T18:00:00Z'`	가장 추천. 가독성이 높고 향후 PostgreSQL 마이그레이션 시 매끄럽게 변환 가능
INTEGER (Unix 타임스탬프)	`1747656000`	공간을 적게 차지하지만 사람이 읽을 수 없음

날짜를 2026/5/19 오후 6시와 같이 자신만의 커스텀 형식으로 저장하지 마세요. 향후 데이터 마이그레이션 시 재앙이 일어날 것입니다.

함정 3: INTEGER 컬럼에 문자열을 삽입해도 에러가 나지 않음

PostgreSQL에서는 INTEGER 컬럼에 문자열을 삽입하면 즉시 에러가 발생합니다. 하지만 SQLite는 묵묵히 변환을 시도하고, 실패하면 원본 그대로 수락합니다.

이는 오염된 데이터가 조용히 데이터베이스에 스며들 수 있음을 의미합니다. 어느 날 프로그램이 예상치 못한 타입을 받아 크래시가 나기 전까지는 문제를 발견할 수 없습니다.

방어적 프로그래밍: 관대한 데이터베이스를 엄격한 태도로 다루기

SQLite의 느슨함에 직면했을 때, Node.js 개발에서는 엄격한 방어 메커니즘을 구축해야 합니다:

방어 단계	도구	역할
컴파일 타임 가드	TypeScript	코드 작성 단계에서 잘못된 타입을 캐치함
API 입구 검증	Zod	입력되는 데이터를 엄격하게 검증함 (age가 반드시 숫자임을 보장)
내부 타입 변환	Prisma / Drizzle ORM	SQLite와 PostgreSQL 간의 타입 차이를 자동으로 처리함

**‘데이터 검증의 문지기’**를 데이터베이스 계층에서 Node.js 애플리케이션 계층으로 이동시키는 것이 SQLite의 개발 속도를 누리면서 향후 확장성을 확보하기 위한 핵심 전략입니다.

ORM을 사용할 경우 코드 내에서 type: 'boolean'으로 선언해 두면, ORM이 SQLite 저장 시 자동으로 1/0으로 변환하고, 조회 시 true/false로 자동 변환해 주어 기저의 타입 차이를 완벽히 가려줍니다.

ALTER TABLE은 미완성: 수정할 수 있는 것과 없는 것

SQLite의 테이블 구조 수정 지원은 매우 제한적입니다:

작업	지원 여부
컬럼 추가 (`ADD COLUMN`)	예
컬럼 이름 변경 (`RENAME COLUMN`)	예
컬럼 삭제 (`DROP COLUMN`)	예 (최신 버전에서 지원)
테이블 이름 변경 (`RENAME TO`)	예
컬럼 타입 변경	아니오
`UNIQUE`, `NOT NULL` 제약 조건 추가/제거	아니오
기본키(Primary Key) 수정	아니오
외래키(Foreign Key) 수정	아니오

‘지원되지 않는’ 수정을 수행해야 할 때, SQLite는 ‘재생성 및 마이그레이션’ 전략을 실행할 것을 요구합니다.

재생성 및 마이그레이션 4단계: SQLite식 테이블 업그레이드 방법

직접 변경이 불가능하므로 공식 문서가 권장하는 표준 방법은 새 집을 짓고, 가구를 옮기고, 이전 집을 날려버리고, 새 문패를 다는 것입니다:

단계	액션	설명
1	새 테이블 생성	올바른 구조로 `CREATE TABLE users_new (...)` 생성
2	데이터 복사	`INSERT INTO users_new SELECT ... FROM users`
3	이전 테이블 삭제	`DROP TABLE users`
4	테이블 이름 변경	`ALTER TABLE users_new RENAME TO users`

이 4개 단계는 일사천리로 실행되어야 합니다. 중간에 전원이 끊기거나 프로그램이 크래시 나면 데이터 유실로 이어집니다.

업그레이드 시 데이터 유실 방지: 두 가지 안전 방어선

방어선 1: 물리적 방어, 파일 직접 복사

SQLite는 본질적으로 하나의 파일입니다. 스키마 변경을 실행하기 전에 .db 파일을 복사해 백업본을 만드는 것으로 충분합니다.

const fs = require('fs');
fs.copyFileSync('my_project.db', 'my_project_backup.db');

만약 문제가 발생하더라도 파일을 덮어쓰는 것만으로 눈 깜짝할 사이에 복구할 수 있습니다. 이는 다른 대형 데이터베이스에서는 제공하지 않는 큰 장점입니다.

방어선 2: 트랜잭션 래퍼, 데이터베이스의 타임머신

이사 단계를 하나의 Transaction으로 감싸줍니다. 단계 중 하나라도 실패하면 전체 프로세스가 자동으로 롤백되어 아무 일도 없었던 것처럼 복원됩니다.

const Database = require('better-sqlite3');
const db = new Database('my_project.db');

const migrateData = db.transaction(() => {
  db.prepare(`
    CREATE TABLE users_new (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      name TEXT NOT NULL,
      age INTEGER NOT NULL DEFAULT 18
    )
  `).run();

  db.prepare(`
    INSERT INTO users_new (id, name, age)
    SELECT id, name, COALESCE(age, 18) FROM users
  `).run();

  db.prepare('DROP TABLE users').run();
  db.prepare('ALTER TABLE users_new RENAME TO users').run();
});

try {
  migrateData();
  console.log('테이블 업그레이드 완료');
} catch (error) {
  console.error('업그레이드 실패, 데이터가 안전하게 복원되었습니다:', error.message);
}

**“백업 파일 + 트랜잭션 바인딩”**이 데이터베이스 마이그레이션의 에어백 역할을 합니다.

엄격한 태도로 소탈한 SQLite 제어하기

소탈한 SQLite를 엄격한 애플리케이션 계층 아키텍처로 다룸으로써, 향후 기술 부채를 방지하면서 극도로 빠른 개발 속도의 장점을 안심하고 누릴 수 있습니다.

SQLite의 타입 시스템은 매우 유연하며, ALTER TABLE 역시 제약 조건이 많습니다.

하지만 Node.js 단에서 TypeScript 타입 검사 + Zod 검증 + ORM 추상화를 착실히 적용하고, 물리적 백업 + 트랜잭션 안전 전략을 결합하면 SQLite가 제공하는 뛰어난 개발 효율성을 마음껏 누릴 수 있으며 동시에 향후 PostgreSQL로의 순탄한 이전 경로를 닦아둘 수 있습니다.

Reference

모든 것에 PostgreSQL을 쓰지 마세요! SQLite의 임베디드 아키텍처와 제로 설정 장점은 무엇일까요? SQLite의 한계는 어디까지일까요? 언제 SQLite를 선택하고, 언제 PostgreSQL을 선택해야 할까요?

Tue, 19 May 2026 18:00:00 +0800

매일 열어보는 브라우저, 스마트폰의 메신저 앱, 심지어 바탕화면의 메모 도구 속에도 모두 동일한 경량 데이터베이스가 숨겨져 있다는 사실을 생각해 본 적이 있으신가요?

별도의 서버 소프트웨어를 설치할 필요도 없고, 계정이나 비밀번호 설정도 필요 없으며, 인터넷 연결조차 필요하지 않습니다. 그것은 그저 하나의 파일이며, 하드디스크에 조용히 누워 언제든지 서비스를 제공할 준비가 되어 있습니다.

이 조용하면서도 강력한 존재가 바로 SQLite입니다.

SQLite란 무엇일까요? 세계에서 가장 널리 배포된 데이터베이스

SQLite는 C 언어로 작성된 임베디드 관계형 데이터베이스 엔진입니다.

독립된 서버 프로세스 없이, 귀하의 애플리케이션에 직접 내장되어 동작합니다.

이는 우리에게 친숙한 PostgreSQL이나 MySQL과는 완전히 다릅니다. 전통적인 데이터베이스는 독립적으로 동작하는 서버이며, 프로그램은 **네트워크 프로토콜(TCP/IP)**을 통해 데이터베이스와 “통신"해야 합니다.

하지만 SQLite는 다릅니다. 그것은 단지 코드의 한 블록일 뿐이며, 애플리케이션 내부에서 직접 실행되어 하드디스크에 있는 .db 파일을 읽고 씁니다.

비교 기준	SQLite (임베디드)	PostgreSQL (클라이언트-서버)
동작 방식	애플리케이션에 직접 내장, 독립 서버 없음	독립된 서버 프로세스, 네트워크 연결을 통해 동작
설정 요구사항	제로 설정, 설치 불필요, 계정 불필요	설치, 계정/비밀번호 설정 및 방화벽 설정 필요
데이터 저장	단일 크로스 플랫폼 파일	서버 디렉터리 내의 여러 파일
백업 방식	해당 파일을 직접 복사	pg_dump 등 전용 도구 사용 필요

바로 이러한 “플러그 앤 플레이” 특성 덕분에 SQLite는 세계에서 가장 널리 배포된 데이터베이스 엔진이 되었습니다.

Android 및 iOS 운영체제, Chrome 및 Firefox 브라우저부터 Adobe Lightroom, WhatsApp, 심지어 Airbus A350의 비행 시스템에 이르기까지 도처에서 그 모습을 찾아볼 수 있습니다.

Node.js에서 SQLite 사용하기

Node.js 개발자라면 SQLite를 사용하는 것이 매우 간단합니다. 컴퓨터에 어떠한 데이터베이스 서버 소프트웨어도 설치할 필요 없이, npm 패키지 하나만 설치하면 바로 시작할 수 있습니다.

현재 업계에서 가장 흔히 사용되는 선택지:

패키지 이름	특징	추천 시나리오
`sqlite3`	가장 오래됨, 비동기 API 지원	동시에 많은 비동기 작업을 처리해야 할 때
`better-sqlite3`	뛰어난 성능, 직관적인 API 디자인, 매우 빠름	최우선 추천, 개발 효율성과 실행 속도를 추구할 때

better-sqlite3를 사용하여 데이터베이스를 생성하고 쿼리하는 과정은 5분도 채 걸리지 않습니다:

const Database = require('better-sqlite3');
const db = new Database('my_project.db');

db.prepare('CREATE TABLE IF NOT EXISTS users (name TEXT, age INTEGER)').run();

const insert = db.prepare('INSERT INTO users (name, age) VALUES (?, ?)');
insert.run('John', 25);

const user = db.prepare('SELECT * FROM users WHERE name = ?').get('John');
console.log(user); // { name: 'John', age: 25 }

파일이 존재하지 않는 경우, better-sqlite3가 자동으로 파일을 생성해 줍니다.

SQLite가 지원하는 SQL 구문은 생각보다 강력합니다

많은 사람들이 SQLite가 매우 원시적이라고 생각하지만, 실제로는 다음과 같은 고급 기능을 포함하여 표준 SQL 구문의 대부분을 지원합니다:

구문 범주	지원 항목
기본 조작	`SELECT`, `INSERT`, `UPDATE`, `DELETE`
데이터 정의	`CREATE TABLE`, `CREATE INDEX`, `CREATE VIEW`
고급 조회	`WITH` (재귀 CTE), 윈도우 함수 (Window Functions)
충돌 처리	`UPSERT` (`INSERT ... ON CONFLICT DO UPDATE`)
JSON 처리	`json_extract`, `json_array`, `json_object` 등 내장 함수
트랜잭션 제어	`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`
조인 조회	`INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL OUTER JOIN`

SQLite의 핵심 철학은 “작고 아름답게"입니다. 일상적으로 필요한 대부분의 SQL 기능을 지원하면서도 극도로 가벼운 상태를 유지합니다.

SQLite의 한계는 어디까지일까요?

가벼움에는 대가가 따릅니다. 만약 SQLite를 결제 카운터가 단 하나뿐인 동네 잡화점에 비유한다면, PostgreSQL은 50개의 계산대를 갖춘 코스트코와 같습니다.

1. 쓰기 병목 현상

SQLite는 데이터를 쓸 때 데이터베이스 파일 전체를 잠급니다.

화장실이 단 하나뿐인 식당을 상상해 보세요. 100명이 밖에서 동시에 메뉴판을 볼 수는 있지만(읽기), 단 1명이라도 들어가서 문을 잠그면(쓰기) 다른 모든 사람들은 줄을 서서 기다릴 수밖에 없습니다.

**WAL 모드(Write-Ahead Logging)**를 활성화하면 동시 읽기/쓰기 성능이 향상되지만, 본질적으로 여러 스레드가 서로 다른 데이터 행에 동시에 쓰는 것은 여전히 불가능합니다.

2. 여러 서버에 걸친 공유 불가

SQLite는 본질적으로 물리적인 하나의 파일입니다. 시스템을 여러 대의 서버에 배포하는 경우(수평 확장), 이 서버들이 동일한 파일을 안전하게 공유할 수 없습니다.

3. 세분화된 권한 관리의 부재

SQLite에는 ‘사용자 계정’이라는 개념이 없습니다. 운영체제 수준에서 해당 .db 파일에 접근해 읽을 수만 있다면, 누구나 모든 데이터를 확인하고 수정할 수 있습니다.

엄격한 개인정보 감사가 요구되는 비즈니스 시스템에서는 이를 받아들일 수 없습니다.

SQLite vs. PostgreSQL: 기술 선정 의사결정

도구에는 좋고 나쁨이 없으며, 오직 적합한가 그렇지 않은가만 존재합니다. 결정을 돕기 위한 궁극의 체크리스트를 확인해 보세요:

질문	답변이 “예” → SQLite 선택	답변이 “아니오” → PostgreSQL 선택
백엔드 서버가 단 한 대뿐이거나, 완전히 로컬에서만 실행되나요?	예	아니오 (수평 확장, 여러 장비가 필요함)
시스템 동작이 대부분 읽기 위주이며, 고주파 동시 쓰기가 없나요?	예	아니오 (동시에 여러 사용자가 쓰기를 경쟁함)
세분화된 계정 권한이나 고급 인덱스 기능이 필요 없나요?	예	아니오 (고급 기능에 깊이 의존함)

보다 구체적인 시나리오 대비:

시나리오	권장 선택	이유
데스크톱 소프트웨어, 모바일 앱, IoT 기기	SQLite	데이터가 기기를 따라 이동하며, 설치가 필요 없음
개인 블로그, 홍보용 쇼케이스 웹사이트	SQLite	읽기가 많고 쓰기가 적어 서버 유지 관리 비용 절감 가능
신속한 프로토타입 개발, 데모	SQLite	파일 하나만 만들면 바로 시작 가능
커뮤니티 포럼, 이커머스 플랫폼	PostgreSQL	높은 동시 쓰기가 발생하며, 행 수준 잠금이 필요함
여러 서버에 분산 배포	PostgreSQL	여러 장비 간에 데이터 소스를 공유해야 함
의료, 금융 등 민감한 시스템	PostgreSQL	역할 기반의 엄격한 권한 제어가 필요함

귀하의 데이터베이스는 주머니 속 수첩인가요, 아니면 중앙 교환기인가요?

데이터가 **“단일 장비, 정적, 단일 소유”**인 경우, SQLite를 선택하여 극도의 가벼움과 자유를 누리십시오.

데이터가 **“클라우드, 동적, 고도의 상호작용”**인 경우, PostgreSQL에 맡기십시오.

SQLite는 **“애플리케이션의 내부 컴포넌트”**라는 철학을 가지고 있으며, PostgreSQL은 **“시스템 아키텍처의 독립된 중심”**으로 위치합니다.

다음번에 아키텍처 의사결정을 내릴 때, 성급하게 PostgreSQL을 꺼내 들기 전에 먼저 스스로에게 질문해 보십시오:

“내 데이터베이스는 주머니 속 수첩인가요, 아니면 중앙 교환기인가요?”

답이 명확해지면 선택도 자연스럽게 확실해집니다.