[Flutter] 구글 드라이브로 앱 데이터 백업·복원·자동 동기화 구현하기

2026-11-20 hit count image

Flutter 앱의 SQLite 데이터를 자체 서버 없이 사용자의 구글 드라이브에 백업·복원하고, 여러 기기 사이에서 자동으로 동기화하는 방법을 정리합니다.

flutter

개요

사용자 데이터를 기기 안의 SQLite DB 에만 저장하는 앱은, 사용자가 기기를 바꾸거나 여러 기기에서 같이 쓰려고 할 때 데이터를 옮길 방법이 없습니다.

계정 시스템과 동기화 서버를 직접 만드는 대신, 사용자의 구글 드라이브 에 DB 파일을 올려 두는 방식을 택했습니다. 이렇게 하면 다음과 같은 장점이 있습니다.

  • 별도의 서버나 회원 가입이 필요 없다. 사용자는 이미 가진 구글 계정으로 로그인하기만 하면 된다.
  • 데이터는 사용자 본인의 드라이브 저장 공간에 저장된다.
  • 파일 하나를 통째로 올리고 받는 구조라, 테이블별 동기화 로직을 만들 필요가 없다.

처음에는 사용자가 설정 화면에서 직접 “업로드” / “다운로드” 버튼을 누르는 수동 방식으로 시작했고, 이후 앱을 쓰는 동안 알아서 동기화되는 자동 동기화 를 추가했습니다. 이 글에서는 이 두 단계를 어떻게 구현했는지, 그리고 실제 운영하면서 어떤 문제를 만나 보강했는지를 정리합니다.

전체 구조

사용한 패키지는 다음과 같습니다.

패키지용도
google_sign_in (7.x)구글 로그인과 드라이브 권한(스코프) 받기
googleapisDrive API v3 클라이언트
connectivity_plus오프라인·Wi-Fi 판정 (자동 동기화)

드라이브에는 다음 경로로 파일을 하나 저장합니다.

내 드라이브
└── <상위 폴더>/
    └── <앱 폴더>/
        └── <백업 파일>   ← 암호화한 SQLite DB 파일

상위 폴더 아래에 앱별 폴더를 한 단계 두면, 나중에 같은 방식으로 다른 앱을 만들어도 파일이 섞이지 않습니다.

전체 흐름은 단순합니다.

  • 업로드: 로컬 DB 복사 → 암호화 → 드라이브에 업로드
  • 다운로드: 드라이브에서 다운로드 → 복호화 → 무결성 검사 → 로컬 DB 교체

로그인과 권한 받기

google_sign_in 7 버전부터는 API 가 크게 바뀌어서, 로그인(인증) 과 스코프 권한(인가) 을 따로 요청합니다. 앱에서는 다음 순서로 호출합니다.

final _scopes = [drive.DriveApi.driveFileScope];

await GoogleSignIn.instance.initialize(serverClientId: serverClientId);

// 1. 이미 로그인한 적이 있으면 UI 없이 조용히 로그인한다.
GoogleSignInAccount? user =
    await GoogleSignIn.instance.attemptLightweightAuthentication();

// 2. 안 되면 계정 선택 화면을 띄운다.
user ??= await GoogleSignIn.instance.authenticate(scopeHint: _scopes);

// 3. 드라이브 권한도 마찬가지로 조용히 → 안 되면 동의 화면 순서.
var authorization =
    await user.authorizationClient.authorizationForScopes(_scopes);
authorization ??= await user.authorizationClient.authorizeScopes(_scopes);

(이해를 돕기 위해 단순화한 코드입니다. 실제 코드에서는 각 호출에 타임아웃과 예외 처리가 붙어 있습니다.)

스코프는 drive.file (DriveApi.driveFileScope) 하나만 요청합니다. 이 스코프는 앱이 직접 만든 파일과 폴더에만 접근할 수 있는 권한이라, 사용자의 다른 드라이브 파일은 보거나 수정할 수 없습니다. 동의 화면에서 사용자가 느끼는 부담이 적고, 앱 입장에서도 꼭 필요한 만큼만 권한을 갖게 됩니다.

사용자가 계정 선택이나 동의 화면을 닫으면 GoogleSignInException 이 canceled 코드로 던져집니다. 이 경우는 오류가 아니므로 에러 메시지를 띄우지 않고 조용히 끝냅니다.

DriveApi 클라이언트 만들기

googleapis 의 DriveApi 는 http.Client 를 받습니다. 로그인한 계정에서 인증 헤더를 받아, 모든 요청에 그 헤더를 붙이는 작은 클라이언트를 만들어 넘깁니다.

class GoogleAuthClient extends http.BaseClient {
  final Map<String, String> header;
  final http.Client httpClient = http.Client();

  GoogleAuthClient({required this.header});

  @override
  Future<http.StreamedResponse> send(http.BaseRequest request) {
    request.headers.addAll(header);
    return httpClient.send(request);
  }
}

final header = await user.authorizationClient
    .authorizationHeaders([drive.DriveApi.driveFileScope]);
final driveApi = drive.DriveApi(GoogleAuthClient(header: header!));

여기서 한 가지 기억해 둘 점이 있습니다. 이 헤더에는 만들 때 받은 액세스 토큰이 고정 되어 있어서, 시간이 지나 토큰이 만료되면 Drive API 가 401 을 돌려줍니다. 앱을 오래 켜 두면 실제로 이 상황이 생기는데, 처리 방법은 뒤의 운영하며 보강한 것들에서 다룹니다.

업로드: DB 파일을 드라이브에 올리기

업로드는 다음 순서로 진행합니다.

// 1. WAL 에 남아 있는 변경을 메인 DB 파일에 반영한다.
await dbHelper.walCheckpoint();

// 2. 사용 중인 DB 를 직접 올리지 않고 임시 파일로 복사한 뒤 암호화한다.
await fileHelper.copyFile(dbPath, tempPath);
await fileHelper.encryptFile(tempPath, key);

// 3. 상위 폴더와 앱 폴더를 찾고, 없으면 만든다.
final syncFolder = await driveHelper.getFolderInfo(folderName: rootFolderName) ??
    await driveHelper.createFolder(folderName: rootFolderName);
final appFolder = await driveHelper.getFolderInfo(
      folderName: appFolderName,
      folderId: syncFolder.id,
    ) ??
    await driveHelper.createFolder(folderName: appFolderName, folderId: syncFolder.id);

// 4. 파일을 올리면서 마지막 변경 시각을 appProperties 에 함께 붙인다.
await driveHelper.uploadFile(
  file: File(tempPath),
  folderId: appFolder.id,
  appProperties: {'localUpdatedAt': localUpdatedAtMs.toString()},
);

// 5. 임시 파일을 지운다.
await fileHelper.deleteFile(tempPath);

몇 가지 포인트를 짚어 보겠습니다.

WAL 체크포인트. SQLite 를 WAL 모드로 쓰고 있으면, 최근 변경 일부가 -wal 파일에만 있고 메인 DB 파일에는 아직 반영되지 않았을 수 있습니다. 메인 파일만 복사하면 최근 변경이 빠지므로, 복사 전에 PRAGMA wal_checkpoint 로 반영해 둡니다.

폴더 찾기. 드라이브는 이름이 같은 파일·폴더를 여러 개 허용하기 때문에 “경로” 로 찾을 수 없고, 쿼리로 검색해야 합니다.

final query = "name='$folderName' "
    "and mimeType='application/vnd.google-apps.folder' "
    "and trashed=false "
    "and '$parentId' in parents";
final result = await driveApi.files.list(q: query);

trashed=false 를 빼먹으면 사용자가 휴지통에 버린 폴더를 찾아 그 안에 올리게 되니 주의해야 합니다.

appProperties. Drive 파일에는 앱 전용 키-값 메타데이터인 appProperties 를 붙일 수 있습니다. 여기에 “이 DB 가 마지막으로 바뀐 시각” 을 넣어 두면, 나중에 파일을 내려받지 않고 메타데이터만 조회해서 어느 쪽이 최신인지 판단할 수 있습니다. 자동 동기화의 핵심이 되는 값입니다.

다운로드: 받은 파일을 검증하고 교체하기

다운로드는 업로드의 역순이지만, 받은 파일을 바로 쓰지 않는다 는 점이 중요합니다.

// 1. 폴더 → 파일 순으로 찾아 임시 경로에 다운로드한다.
final media = await driveApi.files.get(
  fileId,
  downloadOptions: drive.DownloadOptions.fullMedia,
) as drive.Media;
// media.stream 을 임시 파일(tempPath)에 저장한다.

// 2. 복호화한다.
await fileHelper.decryptFile(tempPath, key);

// 3. 정상적인 DB 인지 검사한다.
if (!await dbHelper.isDatabaseValid(tempPath)) {
  throw 'DownloadedDBCorrupt';
}

// 4. 검사를 통과했을 때만 기존 DB 를 닫고 교체한다.
await dbHelper.replaceDatabase(tempPath);

검사에서는 SQLite 의 PRAGMA quick_check 로 파일이 깨지지 않았는지 확인하고, 앱에 필요한 테이블과 컬럼이 있는지도 함께 확인합니다. 통신 중 파일이 잘렸거나 아주 오래된 버전의 백업이라면 여기서 걸러지고, 이때 기존 로컬 DB 는 그대로 남습니다. 사용자 데이터를 덮어쓰는 작업이니, 교체는 반드시 검증 이후에 일어나도록 순서를 지켜야 합니다.

자동 동기화: 무엇을 비교할 것인가

수동 방식은 사용자가 방향(업로드/다운로드)을 정해 주지만, 자동 동기화는 앱이 스스로 판단해야 합니다. “로컬과 드라이브 중 어느 쪽이 최신인가?” 를 판단하기 위해 다음 네 가지 시각을 씁니다.

기호의미저장 위치
L로컬 사용자 데이터를 마지막으로 바꾼 시각로컬 DB sync_metadata 테이블
S마지막으로 동기화에 성공한 시각로컬 DB sync_metadata 테이블
R드라이브 파일의 appProperties.localUpdatedAt드라이브
R0마지막 동기화 때 본 R 값로컬 DB sync_metadata 테이블

이 값으로 “로컬이 바뀌었나?” 와 “원격이 바뀌었나?” 를 각각 판단합니다.

final localChanged = L > S;                        // 마지막 동기화 이후 로컬이 바뀌었다
final remoteChanged = R != null && (R0 == null || R > R0); // 다른 기기가 새로 올렸다

이 두 값과 몇 가지 예외 상황을 조합하면 결정은 다음과 같이 정리됩니다.

상황결정
드라이브에 파일이 없고 로컬 데이터가 있음업로드 (첫 업로드)
드라이브에 파일이 있고 이 기기에 동기화 이력이 없음다운로드 (새 기기)
원격만 바뀜다운로드
로컬만 바뀜업로드
양쪽 다 바뀜 (충돌)더 최근 쪽이 이긴다 (Last-Write-Wins)
아무것도 안 바뀜아무것도 하지 않음

이 판단은 I/O 가 전혀 없는 순수 함수(decideAction)로 분리해 두었습니다. 입력 조합별로 단위 테스트를 쓰기 쉽고, 동기화 로직에서 가장 실수하기 쉬운 부분을 네트워크와 떼어 놓고 검증할 수 있습니다.

왜 드라이브의 modifiedTime 을 쓰지 않았나? 처음에는 드라이브 파일의 수정 시각과 로컬 변경 시각을 비교하면 될 것 같았지만, 이 방식은 “내가 방금 올린 것” 과 “다른 기기가 올린 것” 을 구분하지 못합니다. 업로드가 끝나면 원격 파일의 수정 시각은 항상 최신이 되기 때문입니다. 그래서 업로드할 때 로컬 변경 시각(L)을 appProperties 로 함께 올리고, 마지막에 본 값(R0)을 기억해 두는 방식을 택했습니다. 파일과 메타데이터가 한 번의 요청으로 함께 올라가기 때문에, 둘이 어긋날 일도 없습니다.

충돌 정책은 단순하게. 양쪽이 모두 바뀌었을 때 테이블별로 병합하는 방법도 검토했지만, 성격이 다른 데이터마다 병합 규칙을 만드는 것은 비용과 위험이 컸습니다. 한 사람이 여러 기기를 번갈아 쓰는 상황에서는 동시에 양쪽을 고치는 일이 드물기 때문에, “더 최근 쪽이 이긴다” 는 단순한 규칙을 쓰고, 충돌이 일어나면 어느 쪽을 남겼는지 스낵바로 알려 주는 정도로 정리했습니다.

새 기기에서는 묻는다. 다만 한 가지 경우는 자동으로 처리하지 않습니다. 새 기기에서 이미 앱을 쓰며 데이터를 쌓은 뒤 자동 동기화를 켜면, 규칙상 “새 기기 → 다운로드” 가 되어 그 기기에서 쌓은 데이터가 사라집니다. 이 경우에만 “드라이브 데이터 사용 / 이 기기 데이터 사용 / 나중에” 중에서 고르는 다이얼로그를 띄웁니다.

자동 동기화: 언제 실행할 것인가

처음에는 백그라운드에서 주기적으로 동기화하는 방식도 생각했지만, 포기했습니다.

  • iOS 의 백그라운드 작업(BGTaskScheduler)은 실행 시점을 OS 가 정하고, 실행을 보장하지 않는다.
  • Android 도 Doze 모드와 배터리 최적화로 주기 작업의 신뢰성이 낮다.
  • 메신저처럼 실시간 반영이 꼭 필요한 데이터가 아니다.

그래서 앱이 포그라운드에 있을 때만, 다음 네 가지 시점에 동기화를 실행합니다.

트리거디바운스
앱 시작 직후없음 (1회)
백그라운드에서 포그라운드로 복귀30초
사용자 데이터 변경5초
셀룰러/오프라인 → Wi-Fi 전환30초 (포그라운드 복귀와 공유)

데이터 변경 트리거는 DB 에 사용자 데이터를 쓰는 곳의 끝에서 L 값을 갱신하면서 함께 호출합니다. 사용자가 연달아 조작하면 변경이 계속 생기므로, 5초 디바운스로 마지막 변경 후 한 번만 동기화되게 했습니다.

이 밖에 다음 규칙을 함께 두었습니다.

  • 동시 실행 방지: 이미 동기화가 진행 중이면 새 트리거는 진행 중인 작업의 결과를 같이 기다린다. 사용자가 수동 업로드/다운로드를 하고 있으면 자동 동기화는 양보한다.
  • 재시도: 서버 오류처럼 일시적인 실패만 2초, 4초 간격으로 최대 3번 시도한다. 로그아웃·오프라인 같은 결과는 재시도하지 않는다.
  • Wi-Fi 전용 옵션: 기본값을 켜 두어 셀룰러에서는 자동 동기화를 하지 않는다. 대신 Wi-Fi 에 연결되는 순간 바로 동기화되므로 크게 늦어지지 않는다.
  • 자동 경로에서는 로그인 UI 를 띄우지 않는다: 사용자가 누르지도 않았는데 계정 선택 창이 뜨면 당황스럽다. 자동 동기화는 조용한 로그인(attemptLightweightAuthentication)만 시도하고, 실패하면 화면 상단에 “로그인 필요” 상태를 표시해 사용자가 직접 탭해서 다시 로그인하게 한다.

운영하며 보강한 것들

기본 기능은 위 내용으로 동작하지만, 실제 사용자 기기에서는 생각보다 다양한 실패가 일어났습니다. Crashlytics 로 들어오는 오류를 보며 보강한 내용 중 대표적인 것을 정리합니다.

401: 토큰이 만료됐을 때 한 번만 재인증

앞에서 말한 것처럼 인증 헤더의 토큰은 만료됩니다. Drive API 가 401 을 돌려주면 세션을 버리고 조용한 로그인으로 토큰을 다시 받은 뒤, 같은 요청을 정확히 한 번만 다시 시도합니다. 재시도에서도 401 이면 그 세션은 정말 죽은 것으로 보고, 다음 수동 작업에서 사용자에게 다시 로그인을 받습니다.

재인증했더니 다른 계정이었다

Android 에서는 조용한 로그인도 상황에 따라 계정 선택 시트를 띄울 수 있습니다. 이때 사용자가 다른 계정을 고르면, A 계정의 데이터를 B 계정 드라이브에 올리거나 B 계정의 백업으로 A 의 데이터를 덮어쓰는 사고가 날 수 있습니다.

그래서 각 드라이브 요청 전에 “작업을 시작할 때의 계정” 과 “지금 로그인된 계정” 이 같은지 확인하고, 다르면 작업을 멈춥니다. 또 처음 동기화에 성공한 계정을 기억해 두고, 자동 동기화가 다른 계정으로 동작하려 하면 막습니다. 계정이 바뀌는 것은 데이터 유실로 바로 이어지므로, 이 부분은 가장 보수적으로 다뤘습니다.

403 을 이유별로 나누기

403 은 원인이 여러 가지라 상태 코드만으로는 대응을 정할 수 없습니다. Drive API 오류(DetailedApiRequestError)의 errors[].reason 을 보고 다음과 같이 나눴습니다.

DriveFailureKind classifyDriveFailure(Object e) {
  if (e is drive.DetailedApiRequestError) {
    if (e.status == 403) {
      final reasons = [for (final d in e.errors) d.reason];
      if (reasons.isNotEmpty &&
          reasons.every((r) => r == 'storageQuotaExceeded')) {
        return DriveFailureKind.storageQuotaExceeded;
      }
      if (reasons.isNotEmpty &&
          reasons.every((r) => r == 'userRateLimitExceeded' ||
                               r == 'rateLimitExceeded')) {
        return DriveFailureKind.rateLimited;
      }
      return DriveFailureKind.other;
    }
    if (e.status == 429 || (e.status ?? 0) >= 500) {
      return DriveFailureKind.transient;
    }
  }
  return DriveFailureKind.other;
}
  • 저장 공간 부족(storageQuotaExceeded): 재시도해도 소용이 없다. 사용자에게 드라이브 용량이 부족하다고 한 번 알리고, 그 세션에서는 자동 업로드를 멈춘다. 데이터가 바뀔 때마다 실패 알림이 반복되지 않게 하기 위해서다.
  • 요청 한도 초과·서버 오류: 일시적인 실패로 보고 재시도한다. 오류 보고도 마지막 시도가 실패했을 때만 한다.
  • 그 밖의 403: 모르는 오류는 숨기지 않고 그대로 보고한다.

이 분류는 오류 응답에 errors 배열이 채워져 있어야 동작합니다. 현재 업로드는 multipart 방식이라 채워지지만, 업로드 방식을 resumable 로 바꾸면 응답 형식이 달라질 수 있어 함께 확인해야 합니다.

네이티브 호출에 타임아웃 걸기

드물게 google_sign_in 의 네이티브 호출이 응답하지 않고 계속 멈춰 있는 경우가 있었습니다. 이러면 동기화 버튼이 영원히 로딩 상태로 남습니다. 그래서 initialize·조용한 로그인·권한 조회처럼 UI 가 없는 호출에는 15초, 사용자가 계정을 고르는 대화형 호출에는 60초 타임아웃을 걸고, 어느 단계에서 멈췄는지를 오류에 담아 보고하도록 했습니다.

iOS 에서 백그라운드 연결 변경 이벤트

connectivity_plus 의 연결 변경 스트림을 계속 구독하고 있으면, iOS 에서 앱이 백그라운드에 있는 동안 이벤트가 전달되며 문제가 생기는 경우가 있었습니다. 앱이 paused 상태가 되면 구독을 끊고, resumed 로 돌아올 때 다시 구독하는 방식으로 피했습니다. 어차피 자동 동기화는 포그라운드에서만 동작하므로 백그라운드의 연결 변화를 들을 필요가 없습니다.

정리

  • 구글 드라이브에 DB 파일 하나를 올리고 받는 방식이면, 서버 없이도 기기 간 데이터 이전과 동기화를 만들 수 있다.
  • 권한은 drive.file 스코프만 요청해 앱이 만든 파일에만 접근한다.
  • 업로드 전에는 WAL 체크포인트를 하고, 다운로드한 파일은 무결성 검사를 통과한 뒤에만 교체한다.
  • 어느 쪽이 최신인지는 파일을 받지 않고 appProperties 에 붙인 변경 시각으로 판단한다. modifiedTime 만으로는 내가 올린 것과 남이 올린 것을 구분할 수 없다.
  • 비교 로직은 I/O 없는 순수 함수로 분리해 조합별로 테스트한다.
  • 자동 동기화는 포그라운드의 정해진 시점에만, 디바운스와 제한된 재시도를 두고 실행한다. 자동 경로에서는 로그인 UI 를 띄우지 않는다.
  • 실제 운영에서는 토큰 만료(401), 계정 바뀜, 저장 공간 부족(403), 멈춘 네이티브 호출처럼 정상 흐름 밖의 상황을 처리하는 코드가 훨씬 많아진다. 특히 계정이 섞이는 상황은 데이터 유실로 직결되므로 가장 보수적으로 막는 것이 좋다.

제 블로그가 도움이 되셨나요? 하단의 댓글을 달아주시면 저에게 큰 힘이 됩니다!

앱 홍보

책 홍보

블로그를 운영하면서 좋은 기회가 생겨 책을 출판하게 되었습니다.

아래 링크를 통해 제가 쓴 책을 구매하실 수 있습니다.
많은 분들에게 도움이 되면 좋겠네요.



SHARE
Twitter Facebook RSS