SQLite 파일을 서버에서만 못 읽을 때

개발 환경에서는 SQLite가 잘 작동하는데, 서버에 배포하면 갑자기 파일을 못 열거나 쓸 수 없다는 에러가 나타날 수 있다. 대부분 권한과 파일 경로 문제다.

먼저 확인할 것: 파일이 존재하는가

서버에서 직접 확인한다:

ssh user@server

# SQLite 파일이 있는지 확인
ls -la /path/to/data.db

# 파일이 없다면 해당 디렉토리가 있는지 확인
ls -la /path/to/

파일이 없다면 배포 스크립트에서 데이터베이스를 생성하는 부분이 실행되지 않은 것이다. 또는 컨테이너가 재시작될 때 파일이 사라지는 임시 볼륨을 쓰고 있을 수도 있다.

파일이 있다면 권한 확인

# 파일의 소유자와 권한을 본다
ls -l /path/to/data.db
# 출력: -rw-r--r-- 1 root root 4096 Jun 28 10:30 /path/to/data.db

# 디렉토리의 권한도 확인
ls -ld /path/to/
# 출력: drwxr-xr-x 2 root root 4096 Jun 28 10:30 /path/to/

만약 root가 소유하고 있고, 앱을 실행하는 사용자가 root가 아니라면 읽고 쓸 수 없다. 권한을 바꿔야 한다:

# 앱이 실행되는 사용자 확인 (예: www-data)
sudo ps aux | grep app

# 파일의 소유자를 바꿈
sudo chown www-data:www-data /path/to/data.db

# 읽고 쓸 수 있도록 권한 설정
sudo chmod 644 /path/to/data.db

# 디렉토리도 권한을 줘야 새 파일을 만들 수 있음
sudo chmod 755 /path/to/

로그를 보면 알 수 있는 것들

# 앱 실행 로그를 본다
sudo journalctl -u app-service -n 100 -f
# 또는 Docker라면
docker logs app-container -f

SQLite 에러 메시지:

• "database is locked": 다른 프로세스가 파일을 쓰고 있는 중
• "Permission denied": 파일 권한이 없음
• "unable to open database file": 경로가 잘못됐거나 파일이 없음

볼륨이 제대로 마운트되었는지 확인

Docker나 Kubernetes를 쓴다면, SQLite 파일이 영속적인 볼륨에 저장되는지 확인한다:

# Docker
docker inspect app-container | grep -A 10 Mounts

# Kubernetes
kubectl describe pod app-pod-name | grep -A 10 Mounts

만약 임시 볼륨(tmpfs)에 저장되고 있다면, 컨테이너 재시작 때마다 파일이 사라진다. Docker Compose라면 volumes 섹션을 확인한다:

services:
  app:
    volumes:
      - ./data:/app/data  # 호스트의 data 디렉토리가 /app/data에 마운트됨

WAL 모드 관련 문제

SQLite가 Write-Ahead Logging (WAL) 모드를 쓰면 여러 파일(-wal, -shm)이 생긴다. 이들이 모두 같은 디렉토리에서 같은 권한을 가져야 한다:

# WAL 관련 파일들이 모두 있는지 확인
ls -la /path/to/data.db*

# 모두 같은 소유자 권한으로 설정
sudo chown www-data:www-data /path/to/data.db*

수정 후 확인

권한을 고쳤거나 환경 변수를 바꾼 후:

# 앱을 재시작
sudo systemctl restart app-service
# 또는
docker restart app-container

# 로그를 보면서 에러가 나는지 확인
grep -i error /var/log/app/app.log

에러가 없으면 데이터베이스가 정상 작동하는 것이다. 이렇게 한 번 정리하면, 다음 배포 때는 같은 실수를 반복하지 않을 수 있다.