Flutter 앱에서 SQLite 마이그레이션 처리하기

문제 상황

운영 중인 Flutter 앱에 새 기능을 추가하면서 로컬 DB 테이블에 컬럼을 추가해야 했다. 이미 배포된 앱의 데이터를 유지하면서 스키마를 변경하는 마이그레이션 로직이 필요했다.

sqflite의 버전 관리

sqflite는 onUpgrade 콜백을 통해 DB 버전 관리를 지원한다. 초기 버전을 1로 시작해서, 스키마 변경 시마다 버전을 올리는 방식이다.

Future<Database> _initDatabase() async {
  final dbPath = await getDatabasesPath();
  final path = join(dbPath, 'app.db');

  return await openDatabase(
    path,
    version: 2,  // 버전 증가
    onCreate: _onCreate,
    onUpgrade: _onUpgrade,
  );
}

마이그레이션 구현

버전별 마이그레이션을 switch 문으로 처리했다. 각 버전 변경사항을 순차적으로 적용하는 구조다.

Future<void> _onUpgrade(Database db, int oldVersion, int newVersion) async {
  if (oldVersion < 2) {
    await db.execute('ALTER TABLE users ADD COLUMN profile_image TEXT');
    await db.execute('ALTER TABLE users ADD COLUMN last_login INTEGER');
  }
  // 향후 버전 3, 4 등도 추가 가능
}

테스트 방법

로컬에서 이전 버전 앱을 설치하고 더미 데이터를 생성한 뒤, 새 버전으로 업데이트해서 마이그레이션을 확인했다. 기존 데이터가 유실되지 않고 새 컬럼이 정상 추가되는지 검증했다.

주의사항

• SQLite는 컬럼 삭제나 타입 변경이 제한적이다. 테이블 재생성이 필요한 경우 임시 테이블을 활용해야 한다.
• 마이그레이션 실패 시 롤백이 어려우므로, 충분한 테스트가 필수다.
• 버전 점프 시나리오도 고려해야 한다. (v1 → v3 등)

실제 운영 환경에 배포 후 별다른 이슈 없이 마이그레이션이 진행됐다. 다음 스키마 변경에도 동일한 패턴을 적용할 예정이다.