작은 사이드 프로젝트에서 DB 마이그레이션을 수동 SQL로 남긴 체크리스트

왜 수동 SQL을 남겼나

작은 사이드 프로젝트에서 테이블에 컬럼 하나를 추가해야 했다. ORM 마이그레이션 도구를 붙일 수도 있었지만, 프로젝트 규모에 비해 설정이 더 커지는 느낌이었다. 대신 SQL 파일을 직접 남기고 적용 순서를 체크리스트로 관리했다.

처음에는 관리자 페이지에서 바로 ALTER TABLE을 실행하고 끝내려 했다. 그런데 나중에 새 서버를 만들 때 같은 변경을 재현할 방법이 없다는 걸 깨달았다. 그때부터 수동 SQL도 기록물로 남기기로 했다.

파일 이름 규칙

저는 적용 순서가 보이도록 날짜와 번호를 붙였다.

migrations/
20260711_01_add_last_login_at.sql
20260711_02_create_audit_log.sql

파일 하나에는 가능하면 한 가지 의도만 담았다. 여러 변경을 한 파일에 넣으면 실패했을 때 어디까지 반영됐는지 판단하기 어려웠다.

SQL 파일에 같이 적은 내용

단순히 쿼리만 두지 않고, 왜 필요한지도 짧게 적었다.

-- 로그인 기록 화면에서 마지막 접속 시간을 보여주기 위해 추가
ALTER TABLE users ADD COLUMN last_login_at TEXT;

-- 기존 사용자에게는 값이 없을 수 있으므로 화면에서는 null 처리를 한다

SQLite를 쓸 때는 컬럼 삭제나 타입 변경이 생각보다 제한적이라, 변경 전에 백업을 먼저 만들었다.

sqlite3 app.db ".backup app-before-migration.db"

적용 전 체크리스트

• 운영 DB 파일 위치가 맞는지 확인한다.
• 백업 파일을 만들고 크기가 0이 아닌지 본다.
• SQL을 로컬 복사본에 먼저 실행한다.
• 앱 코드가 새 컬럼의 null 값을 처리하는지 확인한다.
• 적용 후 확인할 SELECT 쿼리를 미리 적어 둔다.

확인 쿼리는 이런 식으로 짧게 준비했다.

PRAGMA table_info(users);
SELECT id, last_login_at FROM users LIMIT 3;

적용 후 기록

적용이 끝나면 파일명 옆에 실행 시간을 남겼다. 거창한 도구는 아니지만, 적어도 어떤 변경이 운영에 들어갔는지 추적할 수 있었다.

20260711_01_add_last_login_at.sql applied at 2026-07-11 09:12 KST

나중에 마이그레이션 도구를 도입하더라도 이 기록은 도움이 된다. 도구가 없어서 위험한 게 아니라, 변경을 다시 설명할 수 없는 상태가 위험하다고 느꼈다.

마무리 체크

작은 프로젝트라고 DB 변경을 기억에 맡기면 금방 꼬인다. 수동 SQL을 쓰더라도 파일로 남기고, 백업하고, 확인 쿼리까지 같이 두면 다음 배포 때 훨씬 덜 불안하다.