SQLite 파일 경로를 README에 명시해둬야 하는 이유

SQLite를 쓰다 보면 한 번쯤 이런 상황을 겪는다. 분명히 데이터를 넣었는데 조회하면 아무것도 없다. 에러도 없고, 앱은 정상 동작한다. 이유는 간단하다 — 연결 경로가 달라서 다른 파일에 쓰고 있었던 것이다.

SQLite 경로 문제가 조용히 실패하는 이유

SQLite는 지정한 경로에 파일이 없으면 에러를 내지 않고 새 파일을 만든다. Prisma 기준으로 datasource의 url이 잘못되면:

// schema.prisma
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

# .env
DATABASE_URL="file:./dev.db"

./dev.db의 기준 경로는 npx prisma를 실행하는 디렉토리다. 프로젝트 루트에서 실행하면 루트에 dev.db가 생기고, apps/api 하위에서 실행하면 그 안에 생긴다. 두 파일이 별개로 존재하면서 아무 경고 없이 다른 데이터를 보게 된다.

README에 적어둘 내용

짧게라도 파일 위치를 명시해두면 이런 혼란이 방지된다.

## 데이터베이스

- 엔진: SQLite
- 파일 위치: `<프로젝트 루트>/prisma/dev.db`
- 환경변수: `DATABASE_URL=file:../prisma/dev.db` (apps/api/.env 기준)
- 마이그레이션: `npx prisma migrate dev` (프로젝트 루트에서 실행)

특히 모노레포나 apps/* 구조를 쓰는 경우, 어디서 prisma 명령을 실행해야 하는지를 명시하지 않으면 새로 세팅하는 사람(또는 몇 달 후의 나)이 반드시 헷갈린다.

경로를 절대경로로 고정하는 방법

상대 경로 대신 절대 경로를 쓰면 실행 위치에 관계없이 항상 같은 파일을 바라본다.

# .env
DATABASE_URL="file:/home/dev/myapp/prisma/dev.db"

운영 환경에서는 /var/data/myapp/db.sqlite처럼 앱 코드와 분리된 경로를 쓰는 편이 배포 시 파일이 덮어쓰이는 사고를 막는다.

마이그레이션 상태 확인

경로가 맞는지 빠르게 확인하는 방법은 두 가지다.

# DB 파일이 실제로 존재하는지
ls -lh prisma/dev.db

# 마이그레이션 적용 상태
npx prisma migrate status

migrate status가 "Database schema is up to date"를 출력하면 파일이 올바른 위치에 있고 마이그레이션도 적용된 상태다. "The migration ... have not yet been applied"가 뜨면 경로나 마이그레이션 적용 여부를 다시 확인해야 한다.