RxDB 컬렉션

RxDB 컬렉션은 TanStack DB와 RxDB를 원활하게 통합하여, 메모리 내 TanStack DB 컬렉션과 RxDB의 로컬 우선 데이터베이스 간 자동 동기화를 지원합니다. 오프라인을 지원하는 영속성과 다양한 백엔드를 활용한 강력한 동기화 기능을 제공합니다.

개요

@tanstack/rxdb-db-collection 패키지를 사용하면 다음과 같은 컬렉션을 생성할 수 있습니다:

기본 RxDB 컬렉션의 상태를 자동으로 미러링합니다.
RxDB 문서가 변경될 때 반응적으로 업데이트합니다.
오류 발생 시 롤백되는 낙관적 뮤테이션을 지원합니다.
TanStack DB 트랜잭션과 RxDB를 동기화하는 영속성 핸들러를 제공합니다.
브라우저 탭 간 동기화를 지원합니다. 한 탭의 변경 사항이 모든 탭의 RxDB 및 TanStack DB 컬렉션에 반영됩니다.
RxDB의 스토리지 엔진 중 하나를 사용합니다.
오프라인 우선 및 동기화 시나리오에서 RxDB의 복제 기능과 함께 작동합니다.
RxDB의 복제 플러그인을 활용하여 CouchDB, MongoDB, Supabase, REST API, GraphQL, WebRTC(P2P) 등과 동기화합니다.

1. 설치

선호하는 프레임워크 통합과 함께 RxDB 컬렉션 패키지를 설치합니다.

npm install @tanstack/rxdb-db-collection rxdb @tanstack/react-db

2. RxDatabase 및 RxCollection 생성

import { createRxDatabase, addRxPlugin } from 'rxdb/plugins/core'

/**
 * Here we use the localStorage based storage for RxDB.
 * RxDB has a wide range of storages based on Dexie.js, IndexedDB, SQLite, and more.
 */
import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage'

// add json-schema validation (optional)
import { wrappedValidateAjvStorage } from 'rxdb/plugins/validate-ajv';

// Enable dev mode (optional, recommended during development)
import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode'
addRxPlugin(RxDBDevModePlugin)

type Todo = { id: string; text: string; completed: boolean }

const db = await createRxDatabase({
  name: 'my-todos',
  storage: wrappedValidateAjvStorage({
    storage: getRxStorageLocalstorage()
  })
})

await db.addCollections({
  todos: {
    schema: {
      title: 'todos',
      version: 0,
      type: 'object',
      primaryKey: 'id',
      properties: {
        id: { type: 'string', maxLength: 100 },
        text: { type: 'string' },
        completed: { type: 'boolean' },
      },
      required: ['id', 'text', 'completed'],
    },
  },
})

3. (선택 사항) 백엔드와 동기화

import { replicateRxCollection } from 'rxdb/plugins/replication'
const replicationState = replicateRxCollection({
  collection: db.todos,
  pull: { handler: myPullHandler },
  push: { handler: myPushHandler },
})

4. RxDB 컬렉션을 TanStack DB로 래핑

import { createCollection } from '@tanstack/react-db'
import { rxdbCollectionOptions } from '@tanstack/rxdb-db-collection'

const todosCollection = createCollection(
  rxdbCollectionOptions({
    rxCollection: db.todos,
    startSync: true, // start ingesting RxDB data immediately
  })
)

이제 todosCollection은 RxDB가 구동하는 반응형 TanStack DB 컬렉션입니다:

todosCollection.insert/update/delete을 통한 쓰기는 RxDB에 영속화됩니다.
RxDB에서 직접 수행한 쓰기(또는 복제를 통한 쓰기)는 변경 스트림을 통해 TanStack 컬렉션으로 전달됩니다.

구성 옵션

rxdbCollectionOptions 함수는 다음 옵션을 허용합니다:

필수

rxCollection: 기본 RxDB 컬렉션

선택 사항

id: 컬렉션의 고유 식별자
schema: 항목을 검증하기 위한 스키마입니다. RxDB에는 이미 스키마 검증 기능이 있지만, TanStack DB 측에 추가 검증을 두면 서로 다른 TanStack 컬렉션 간 오류 처리를 통합하는 데 도움이 됩니다.
startSync: 즉시 동기화를 시작할지 여부입니다(기본값: true).
onInsert, onUpdate, onDelete: 기본 영속성 핸들러를 재정의합니다. 기본적으로 TanStack DB 쓰기는 bulkUpsert, patch 및 bulkRemove를 사용하여 RxDB에 영속화됩니다.
syncBatchSize: RxDB에서 TanStack DB로 초기 동기화하는 동안 배치별로 가져오는 문서의 최대 개수입니다(기본값: 1000). 값이 클수록 왕복 횟수가 줄지만 메모리를 더 사용하고, 값이 작을수록 가볍지만 쿼리 호출이 늘어날 수 있습니다. 이는 초기 동기화에만 영향을 줍니다. 지속적인 라이브 업데이트는 RxDB의 변경 피드를 통해 한 번에 하나씩 스트리밍됩니다.

백엔드와 동기화

RxDB의 복제 및 동기화는 TanStack DB와 독립적으로 실행됩니다. RxDB의 복제 플러그인(CouchDB, GraphQL, WebRTC, REST API 등)을 사용하여 RxCollection에서 직접 복제를 설정합니다.

복제가 실행되면 백엔드에서 변경 사항을 가져오고 백엔드로 변경 사항을 푸시한 다음 RxDB 컬렉션에 적용합니다. TanStack DB 통합은 RxDB 변경 스트림을 구독하므로 복제로 적용된 모든 변경 사항이 TanStack DB 컬렉션에 자동으로 반영됩니다.

이러한 관심사 분리를 통해 복제를 전적으로 RxDB에서 구성할 수 있으며 TanStack DB는 자동으로 그 이점을 얻습니다. 즉, 선택한 동기화 전략이 무엇이든 TanStack 컬렉션은 항상 최신 상태로 유지됩니다.

자주 묻는 질문

TanStack DB만 쿼리하는 경우에도 RxDB 스키마 인덱스가 필요한가요?

일반적으로 TanStack DB 쿼리 자체에는 필요하지 않습니다. TanStack DB 쿼리는 전적으로 메모리에서 실행되므로 RxDB 스키마 인덱스는 TanStack DB 라이브 쿼리의 성능에 영향을 주지 않습니다. 그러나 다음과 같은 경우에는 RxDB 인덱스가 여전히 중요할 수 있습니다:

RxDB에 직접 쿼리를 실행하는 경우(예: rxCollection.find(...)).
복제 설정에서 필터링된 쿼리 또는 셀렉터를 사용하는 경우.
모든 데이터를 메모리에 구체화하는 대신 RxDB를 사용하여 데이터 하위 집합만 선택적으로 로드하는 경우.

RxDB와 TanStack DB 간에 데이터가 중복되나요?

예, 의도적으로 중복됩니다. RxDB는 데이터를 디스크에 내구성 있게 저장합니다. TanStack DB는 빠른 쿼리와 반응성을 위해 데이터를 메모리에 저장합니다. 이러한 중복을 통해 고성능 UI 쿼리를 제공하면서 로컬 우선 영속성과 동기화를 유지할 수 있습니다.

백엔드 ↔ RxDB ↔ TanStack DB 동기화는 어떻게 작동하나요?

동기화는 RxDB와 TanStack DB 간의 명확한 책임 분리를 따릅니다.

RxDB는 영속성과 네트워킹을 담당합니다. 로컬 스토리지 엔진(IndexedDB, SQLite 등)을 사용하여 데이터를 내구성 있게 저장하고 모든 복제 로직을 처리합니다. 복제는 RxDB 컬렉션에서 직접 구성되며 TanStack DB와 독립적으로 실행됩니다. RxDB는 백엔드에서 변경 사항을 가져와 로컬에 적용하고, 충돌을 해결하며, 로컬 변경 사항을 백엔드로 다시 푸시합니다.

TanStack DB는 메모리 기반 반응형 쿼리 계층으로 상위에 위치합니다. 백엔드와 직접 통신하지 않으며 복제에도 참여하지 않습니다. 대신 RxDB 컬렉션의 현재 상태를 메모리에 미러링하고 UI를 위한 빠른 라이브 쿼리와 낙관적 뮤테이션을 제공합니다.

이 설계는 의도적으로 두 개의 독립적인 루프를 형성합니다:

전적으로 RxDB가 관리하는 내구성 및 동기화 루프(백엔드에서 RxDB로).
TanStack DB가 관리하는 반응형 UI 루프(RxDB 변경 스트림에서 메모리 내 컬렉션을 거쳐 라이브 쿼리로).

개요​

1. 설치​

2. RxDatabase 및 RxCollection 생성​

3. (선택 사항) 백엔드와 동기화​

4. RxDB 컬렉션을 TanStack DB로 래핑​

구성 옵션​

필수​

선택 사항​

백엔드와 동기화​

자주 묻는 질문​

TanStack DB만 쿼리하는 경우에도 RxDB 스키마 인덱스가 필요한가요?​

RxDB와 TanStack DB 간에 데이터가 중복되나요?​

백엔드 ↔ RxDB ↔ TanStack DB 동기화는 어떻게 작동하나요?​

자세히 알아보기​

개요