Floor — 무엇인가, Flutter에서 SQLite 위의 ORM

Floor란 무엇인가?

Floor는 SQLite 위에 구축된 Flutter 및 Dart용 ORM 라이브러리입니다. 엔티티(Entity), Data Access Objects(DAO) 및 데이터베이스(Database)를 설명하기 위해 어노테이션을 사용합니다. 코드 생성은 build_runner 및 floor_generator를 통해 수행됩니다 — 컴파일러가 DAO 구현 및 관리 데이터베이스 클래스를 생성합니다. 원시 sqflite와 달리 Floor는 타입 리플렉션을 통해 열을 Entity 필드에 자동으로 매핑하여 ResultSet에서 Dart 객체로의 수동 변환 필요성을 완전히 제거합니다.

Floor는 Android 개발자에게 Room에서 친숙한 Repository + DAO 패턴을 따릅니다. 각 테이블은 @Entity 어노테이션이 있는 Dart 클래스로 표현되며, SQL 쿼리는 @dao 어노테이션이 있는 인터페이스로 그룹화되고, 데이터베이스는 @Database가 있는 추상 클래스에서 조합됩니다. 이 접근 방식은 데이터 모델을 쿼리 로직에서 엄격히 분리합니다.

Flutter Pulse(2023)에 따르면, 로컬 데이터베이스가 필요한 Flutter 프로젝트의 28%에서 Floor가 선택됩니다. 선택하는 주요 이유는 SQL에 대한 친숙함(새로운 쿼리 언어를 배울 필요 없음)과 컴파일 타임 쿼리 검사입니다. 또한 Floor는 사용자 정의 DSL을 가진 더 추상적인 ORM에 비해 디버깅이 쉬운 읽기 가능한 코드를 생성하므로 팀의 새로운 개발자에 대한 진입 장벽을 낮춥니다.

Floor 아키텍처

Floor는 세 가지 계층으로 구성됩니다: Entity(테이블 모델), DAO(쿼리 인터페이스) 및 Database(진입점). 생성기는 필드 매핑을 위한 _$_Entity 구현과 SQL 실행을 위한 _$_Dao를 만듭니다. Entity 또는 DAO가 변경되면 build_runner를 다시 시작하기만 하면 코드가 자동으로 업데이트됩니다. 스키마 버전 간 마이그레이션을 위해 Floor는 순차적 버전 번호를 사용하여 사용자 기기에서 앱을 업데이트할 때 데이터 무결성을 보장합니다.

Flutter에서 Floor는 어떻게 작동하는가?

Floor는 플랫폼 빌드의 경우 sqflite 패키지를 통해, 데스크톱 및 웹의 경우 sqlite3를 통해 SQLite를 사용합니다. 앱이 시작되면 Floor는 SQLite 파일을 생성하거나 열고, 마이그레이션을 적용하며, 쿼리 실행을 위한 DAO 메서드를 준비합니다. 모든 작업은 Future 및 Stream을 통해 비동기적으로 수행됩니다.

Floor의 코드 생성은 다음과 같이 작동합니다: 파서가 소스 파일에서 어노테이션을 읽고, 모델 및 쿼리의 AST(추상 구문 트리)를 만든 다음, _$ 접두사가 있는 Dart 파일을 생성합니다. 생성된 코드에는 ResultSet → Entity 매퍼와 그 반대가 포함됩니다.

스레드 안전성

Floor는 단일 isolate에서 SQLite와 함께 작동합니다. 모든 쿼리는 비동기적으로 실행되지만, 동시 쓰기는 SQLite 수준에서 잠깁니다. 트랜잭션의 경우 @transaction 어노테이션이 사용되며, 이는 쿼리 그룹의 원자성과 오류 시 롤백을 보장합니다.

Floor vs Drift: Flutter용 ORM 비교

Floor와 Drift는 모두 SQLite 위의 ORM이지만 철학이 다릅니다. Floor는 Android의 Room에 더 가깝고, Drift는 내장 Stream API와 SQL 파일을 통한 쿼리 컴파일로 더 반응적입니다. 둘 중 선택은 팀 경험과 필요한 반응성에 따라 달라집니다.

Floor를 선택해야 할 때

Floor는 이미 SQL 및 Android Room에 익숙한 팀을 위한 선택입니다. 개발자가 수동으로 SQL 쿼리를 작성하는 데 익숙하고 SQLite 위에 최소한의 래퍼를 원한다면 — Floor는 새로운 DSL을 배우지 않고도 타입화를 제공합니다. 생성된 코드가 읽기 쉽고 예측 가능하므로 디버깅도 더 쉽습니다.

Drift가 더 나을 때

Drift는 더 강력한 반응성을 제공하고 더 많은 플랫폼을 지원합니다. 앱이 UI 업데이트를 위해 Stream을 적극적으로 사용하고, JOIN 및 하위 쿼리가 포함된 복잡한 쿼리가 필요하거나 웹을 대상으로 하는 경우 — Drift가 더 좋습니다. 그러나 자체 DSL을 배워야 하므로 진입 장벽이 더 높습니다.

Floor를 사용한 코드 예제

Floor는 어노테이션을 중심으로 구축됩니다. 아래는 작업 목록 앱을 위한 Entity, DAO 및 Database의 전체 예제입니다. build_runner를 실행한 후 생성된 클래스를 즉시 사용할 수 있습니다.

Entity 및 DAO 정의

TaskEntity 클래스는 @Entity 어노테이션으로 task 테이블에 매핑됩니다. @primaryKey가 있는 필드가 기본 키가 됩니다. TaskDao 인터페이스에는 테이블 작업을 위한 메서드가 포함되어 있습니다 — 각 메서드는 @Query, @Insert, @Update 또는 @Delete로 어노테이션됩니다.

@entity
class TaskEntity {
    @PrimaryKey(autoGenerate: true)
    final int id;
    final String title;
    final bool isCompleted;
    final int priority;

    TaskEntity({this.id, required this.title,
        this.isCompleted = false, this.priority = 0});
}

@dao
abstract class TaskDao {
    @Query('SELECT * FROM TaskEntity ORDER BY priority DESC')
    Future<List<TaskEntity>> getAllTasks();

    @Insert
    Future<int> insertTask(TaskEntity task);

    @Update
    Future<void> updateTask(TaskEntity task);

    @Query('SELECT * FROM TaskEntity WHERE isCompleted = :status')
    Stream<List<TaskEntity>> watchTasks(bool status);
}

데이터베이스 초기화

@Database 어노테이션이 있는 추상 클래스가 Entity와 DAO를 연결합니다. databaseBuilder 메서드는 데이터베이스 인스턴스를 생성합니다. build를 호출한 후 데이터베이스가 준비됩니다: Floor가 SQLite 파일을 열고, 마이그레이션을 적용하며, 작업을 위한 DAO를 반환합니다.

@Database(version: 1, entities: [TaskEntity])
abstract class AppDatabase extends FloorDatabase {
    TaskDao get taskDao;
}

// 사용
final database = await $FloorAppDatabase.databaseBuilder('app.db').build();
final taskDao = database.taskDao;
final tasks = await taskDao.getAllTasks();

Stream을 통한 반응형 쿼리

Floor는 DAO 메서드에서 Stream 반환을 지원합니다. 테이블에 변경 사항이 있으면 Stream이 새 목록을 내보냅니다. 이는 Flutter의 StreamBuilder와 통합되어 — 레코드가 추가, 수정 또는 삭제될 때 UI가 자동으로 업데이트됩니다.

@Query('SELECT * FROM TaskEntity ORDER BY priority DESC')
Stream<List<TaskEntity>> watchAllTasks();

// Flutter 위젯에서
StreamBuilder<List<TaskEntity>>(
    stream: taskDao.watchAllTasks(),
    builder: (context, snapshot) {
        final tasks = snapshot.data ?? [];
        return ListView.builder(
            itemCount: tasks.length,
            itemBuilder: (_, i) => TaskTile(tasks[i]),
        );
    },
)

Floor에서의 마이그레이션 및 버전 관리

Floor는 @Database 어노테이션의 version 매개변수를 통해 데이터베이스 버전 관리를 지원합니다. Entity가 변경되면(필드 추가 또는 제거) 버전을 높이고 마이그레이션을 추가해야 합니다. 마이그레이션은 트랜잭션을 받아 ALTER TABLE SQL 쿼리를 실행하는 Dart 함수입니다.

마이그레이션 예제

버전 2에서 TaskEntity에 dueDate 필드를 추가했다고 가정합니다. 마이그레이션은 ALTER TABLE SQL 쿼리를 통해 수행됩니다. 마이그레이션이 지정되지 않은 경우 Floor는 MigrationStrategy를 호출하여 폴백을 설정할 수 있습니다(예: 데이터 손실과 함께 테이블 재생성).

Floor 쿼리 테스트

Floor는 내장 모의 프레임워크를 제공하지 않지만 데이터베이스는 테스트에서 쉽게 교체할 수 있습니다. inMemoryDatabaseBuilder를 만드세요 — 스키마가 프로덕션과 동일한 인메모리 SQLite 데이터베이스를 생성합니다. 각 테스트 후 deleteDatabase를 통해 데이터를 지워 테스트 시나리오를 격리합니다.

Floor에서의 트랜잭션 및 배치 작업

Floor는 DAO 메서드의 @transaction 어노테이션을 통해 트랜잭션을 지원합니다. 트랜잭션 내에서는 여러 쿼리가 오류 시 롤백 보장과 함께 순차적으로 실행됩니다. List 매개변수가 있는 @Insert를 통한 배치 삽입은 단일 호출에서 여러 레코드 삽입을 최적화합니다 — 이는 루프에서 한 번에 하나의 레코드를 삽입하는 것보다 몇 배 더 빠릅니다. 대량 작업의 경우 100-200개 레코드의 배치 삽입을 사용하세요: 리소스가 제한된 모바일 장치에서 실행 속도와 RAM 소비 간의 최적의 균형입니다.

final migration1to2 = Migration(1, 2, (database) async {
    await database.execute(
        'ALTER TABLE TaskEntity ADD COLUMN dueDate TEXT'
    );
});

final database = await $FloorAppDatabase.databaseBuilder('app.db')
    .addMigrations([migration1to2])
    .build();