---
title: "TanStack DBとは？TanStack Queryとの違い・使い方と1.0 RCの変更点"
url: "https://www.issoh.co.jp/tech/details/8738/"
published: 2025-09-09
updated: 2026-11-07
categories: ["React"]
publisher: "株式会社一創"
---

# TanStack DBとは？TanStack Queryとの違い・使い方と1.0 RCの変更点

TanStack DBは、APIから取ってきたデータをブラウザ側のコレクションに持ち、SQLに似たライブクエリで絞り込み・結合し、楽観的更新までを引き受けるライブラリです。名前にDBと付きますが、公式リポジトリの説明は「The reactive client store for your API.」で、ストレージエンジンではありません。2026年10月29日に1.0.0-rc.1が出て、11月7日時点のnpmの`latest`タグは1.0.0-rc.1.4を指しています。ここではTanStack Queryとの役割分担、0.9系から書き換えが必要になった箇所、IndexedDBへの保存を、公式の資料と手元での実行結果に沿って説明します。

## まとめ

- TanStack Queryの置き換えではありません。取得はQuery、取得後の保持・検索・楽観的更新をDBが受け持ちます。
- 2026年10月29日に1.0.0-rc.1。タグを付けずに`npm install`してもRCが入ります。
- RCではQueryコレクションのハンドラが自動でrefetchしなくなりました。0.9.2と同じハンドラのままだと、サーバー更新が成功しても画面の値が元に戻ります（実測）。
- `useLiveQuery`の依存配列は廃止され、渡すと型エラーになります。`where`にJavaScriptの比較演算子を書くと、型チェックは通るのに実行時に落ちます。
- 0.13.0からIndexedDBコレクションがコアに同梱されました。ストアの全行をメモリに読み込む方式なので、大きなデータはSQLite永続化を選びます。

## TanStack DBの位置づけと1.0 RCの現在地

### APIの前に置くリアクティブなクライアントストア

TanStack DBが解こうとしているのは、画面ごとに専用のAPIを増やすか、全部取ってきてクライアントで絞り込むか、という二択です。[公式Overview](https://tanstack.com/db/latest/docs/overview)は、正規化したコレクションにデータを入れ、そこへライブクエリを投げる3つ目の道を示しています。差分だけを再計算するエンジン（differential dataflowのTypeScript実装）を使い、「Updating one row in a sorted 100,000-item collection completes in \~0.7ms on an M1 Pro MacBook」としています。特定マシンでの計測値なので、自社の見積もりには使えません。

開発はElectricSQLの中で2025年初めに始まり、[RC1の告知ブログ](https://tanstack.com/blog/tanstack-db-1.0-rc1-going-all-in-on-oracles)によれば、ElectricSQLは8月にNeonに買収され、その後もNeonが開発を支えています。現在の主要メンテナはKyle Mathews氏、Sam Willis氏、Kevin De Porre氏の3人です。TanStackファミリーの中では、取得の[TanStack Queryとは？React Queryとの違い・v5の使い方と既定値の落とし穴](/tech/details/10307/)、表描画の[TanStack Tableとは：v9の導入コードとヘッドレス設計・AG Gridとの選び分け](/tech/details/19067/)と並ぶ、データ層の部品という位置にあります。

### 0.9.2から1.0.0-rc.1までの版の動き

0.9.2から1.0 RCまでの主な公開版と変更点を、次の表に整理します。日付はnpmレジストリの公開時刻（UTC）で、[レジストリのパッケージ情報](https://registry.npmjs.org/@tanstack/db)の`time`で確かめられます。0.10.0はCHANGELOGに項目がありますが、npmには公開されていません。

| 版            | 公開日        | 主な変更                               |
| ------------ | ---------- | ---------------------------------- |
| 0.9.2        | 2026-09-14 | 比較の起点                              |
| 0.11.0       | 2026-09-30 | SQLite永続化のnetwork-first初期描画        |
| 0.12.0       | 2026-10-05 | 複合条件のjoin、`begin({ immediate })`削除 |
| 0.13.0       | 2026-10-10 | IndexedDBコレクションをコアに同梱              |
| 0.15.0       | 2026-10-15 | `findOne`の件数を固定                    |
| 1.0.0-rc.1   | 2026-10-29 | 非推奨APIの削除、演算子の明示インポート化             |
| 1.0.0-rc.1.4 | 2026-11-06 | 2026-11-07時点の`latest`              |

状態の表記は資料によって違います。RC1のブログは「the API is powerful, production-ready, and stable」と書く一方、[GitHubのREADME](https://github.com/TanStack/db)には今も「Tanstack DB is currently in BETA.」が残っています。RCは正式版の前の段階です。採用するなら版を`1.0.0-rc.1.4`のように固定し、正式版までの差分をCHANGELOGで追ってください。利用は伸びていて、[npmのダウンロード統計](https://api.npmjs.org/downloads/point/2026-10-30:2026-11-05/@tanstack/db)では、2026年10月30日〜11月5日の`@tanstack/db`が1,762,855回でした。`@tanstack/react-query`の82,427,046回と比べると、まだ約47分の1です。

## TanStack QueryとTanStack DBの違いと使い分け

### Queryを置き換えずに拡張する役割分担

公式Overviewは「It extends TanStack Query with collections, live queries and optimistic mutations」と書いており、DBはQueryの上に乗る層です。[0.1の告知ブログ](https://tanstack.com/blog/tanstack-db-0.1-the-embedded-client-database-for-tanstack-query)は、Queryが「how do I fetch?」を、DBが「how do I keep everything coherent and lightning-fast once it’s here?」を受け持つと分けています。接続点は`queryCollectionOptions`で、既存の`queryKey`と`queryFn`をそのまま渡せます。コレクション単位で少しずつ移せるので、全面移行は要りません。

| 観点        | TanStack Query      | TanStack DB                 |
| --------- | ------------------- | --------------------------- |
| 持つ単位      | クエリキーごとのレスポンス       | キーで正規化した行                   |
| 絞り込み・結合   | 取得側か`select`で書く     | ライブクエリ（where・join・groupBy）  |
| 楽観的更新     | UIへの仮表示、またはキャッシュ更新  | コレクションへの書き込みで自動適用・失敗時ロールバック |
| npm（11/7） | react-query 5.107.1 | react-db 1.0.0-rc.1.4       |

### Queryの作法がそのまま通らない箇所

Queryのオプションをすべて引き継げるわけではありません。[Query Collectionのdocs](https://tanstack.com/db/latest/docs/collections/query-collection)は「`placeholderData` is intentionally unsupported.」としています。プレースホルダは観測側の一時的な表示であり、全コンポーネントが共有する行にすべきでない、という理由です。`select`も、レスポンスから行の配列を取り出す用途に意味が変わっています。Queryの`select`を移す際は、レスポンスから行配列を返す処理になっているか確認してください。移しただけで変換が二重に実行されるわけではありません。

もう一つの違いがRCで加わりました。0.9系までは、`onUpdate`などのハンドラが終わると自動でrefetchが走っていましたが、RCではこれが無くなりました。詳しくは次の章の実測で示します。

### DBを重ねる価値がある画面の条件

重ねる価値があるのは、1回取ったデータを絞り込みや結合で何通りにも見せる画面や、楽観的更新のキャッシュ書き換えで不具合が出ている画面です。画面ごとにエンドポイントが1本で完結し、取得した形のまま表示しているならQueryだけで足ります。[Zustandとは？読み方・使い方とv5の注意点【5.0.16対応】](/tech/details/7615/)のようなUI状態のストアとは役割が重ならないので、併用して問題ありません。

## 1.0 RCでの導入とコレクション定義

### インストールとパッケージの版の組み合わせ

Reactでの最小構成は次の3つです。`@tanstack/react-db`はコアの`@tanstack/db`を再エクスポートします。peerDependenciesはReact 18以上です。

```
npm install @tanstack/react-db@1.0.0-rc.1.4 @tanstack/query-db-collection@1.5.1 @tanstack/query-core
```

版の組み合わせには注意が要ります。`@tanstack/query-db-collection`と`@tanstack/offline-transactions`は、[RCへの移行ガイド](https://tanstack.com/db/latest/docs/guides/migrate-to-1-0-rc)が「accidentally released as 1.0 before the RC」と認めているとおり、先に1.0が出ていました。そのため今も1.x系のまま更新されています（11月7日時点で1.5.1と1.2.0）。どちらも`@tanstack/db@^1.0.0-rc.0`をpeerに求め、Query Collectionは`@tanstack/query-core` 5.90.15以上も要求します。0.9.2のまま、アダプタだけを上げることはできません。

### DbClientとcollectionOptionsの最小構成

RCの公式Quick Startは、コレクションの定義を`collectionOptions`という記述子に分け、`DbClient`が実体を持つ形です。リクエストごとに`DbClient`を分けられるので、SSRでもこの形が前提になります。次のコードは`@tanstack/react-db` 1.0.0-rc.1.4とTypeScript 7.0.2で型チェックが通ることを確認しました。

```
import { DbClient, DbProvider, collectionOptions, eq, useDbClient, useLiveQuery } from '@tanstack/react-db'
import { QueryClient } from '@tanstack/query-core'
import { queryCollectionOptions } from '@tanstack/query-db-collection'

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

// ブラウザ用。SSRではリクエストごとに生成する。
const dbClient = new DbClient({ queryClient: new QueryClient() })

const todoCollection = collectionOptions('todos', (client) =>
  queryCollectionOptions({
    id: 'todos',
    queryKey: ['todos'],
    queryClient: client.requireDependency<QueryClient>('queryClient'),
    queryFn: async (): Promise<Array<Todo>> => {
      const res = await fetch('/api/todos')
      if (!res.ok) throw new Error(`GET /api/todos failed: ${res.status}`)
      return res.json()
    },
    getKey: (item) => item.id,
    onUpdate: async ({ transaction, collection }) => {
      const { original, modified } = transaction.mutations[0]
      const res = await fetch(`/api/todos/${original.id}`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(modified),
      })
      if (!res.ok) throw new Error(`PUT failed: ${res.status}`)
      await collection.utils.refetch()
    },
  })
)

function Todos({ done }: { done: boolean }) {
  const todos = useDbClient().collection(todoCollection)
  const { data, isLoadingError, isSyncError } = useLiveQuery({
    query: (q) => q.from({ todo: todoCollection }).where(({ todo }) => eq(todo.completed, done)),
  })
  if (isLoadingError) return <p>読み込みに失敗しました</p>
  return (
    <>
      {isSyncError && <p>最新でない可能性があります</p>}
      <ul>
        {data.map((t) => (
          <li key={t.id} onClick={() => todos.update(t.id, (d) => { d.completed = !d.completed })}>{t.text}</li>
        ))}
      </ul>
    </>
  )
}

export const App = () => (
  <DbProvider client={dbClient}><Todos done={false} /></DbProvider>
)
```

押さえどころは3点です。`queryFn`に戻り値の型を付けないと、行の型が推論できず`todo.completed`が型エラーになります。`fetch`は4xxや5xxでも例外を投げないので、`res.ok`を見て自分でthrowしないとロールバックが働きません。そして`onUpdate`の最後の`await collection.utils.refetch()`は、RCでは必須です。

### syncModeによる読み込み範囲の指定

既定の`eager`はコレクション全体を先に読み込みます。公式Overviewは1万行未満の静的なデータ向けとしています。`on-demand`はクエリが求めた分だけ読み込み、5万行を超えるデータや検索画面に向きます。Overviewは`progressive`も挙げていますが、1.0.0-rc.1.4の型定義でも`SyncMode`は`eager`と`on-demand`の2値で、progressiveは[ElectricSQLとは？Postgres同期エンジンの仕組み・導入手順と2026年の変化](/tech/details/7220/)のElectric Collectionだけが持つ方式です。on-demandでは、絞り込みごとにコレクションを作ってはいけません。docsは「Do not create a collection for each `where`, `orderBy`, or `limit`」と明記しています。

## 0.9系から1.0 RCへ移るときの書き換え箇所

### ハンドラの自動refetch廃止による値の巻き戻り

影響がいちばん大きいのはここです。移行ガイドは、ハンドラが再取得も確定データの書き込みもしない場合「its optimistic changes revert to the previous synced rows when the transaction settles, even if the server accepted the mutation」と書いています。同じハンドラを0.9.2とRCで動かし、メモリ上の擬似サーバーで確かめました（Node.js 26.5.0）。

| 構成                                         | 更新直後 | 確定後の画面    | サーバー |
| ------------------------------------------ | ---- | --------- | ---- |
| 0.9.2＋query-db-collection 1.2.15、refetchなし | true | true      | true |
| 1.0.0-rc.1.4＋1.5.1、refetchなし               | true | **false** | true |
| 1.0.0-rc.1.4＋1.5.1、`refetch()`あり           | true | true      | true |

RCでrefetchを書き忘れると、エラーも警告も出ないまま画面だけが古い値に戻ります。版を上げたら、まずすべての`onInsert`・`onUpdate`・`onDelete`を確認してください。再取得を避けたいなら、サーバーが返した確定データを`writeUpdate`などで書き込みます。Electric Collectionでは、`{ txid }`を返す書き方をやめ、ハンドラの中で`await collection.utils.awaitTxId(txid)`を呼びます。

### useLiveQueryの依存配列廃止とqueryKey

Reactの`useLiveQuery`・`useLiveSuspenseQuery`・`useLiveInfiniteQuery`は依存配列を受け付けなくなりました。TypeScript 7.0.2で`useLiveQuery((q) => ..., [s])`を型チェックすると、`TS2554: Expected 1 arguments, but got 2.`になります。構造化したクエリなら、クエリが参照している値から識別子を自動で導くので、配列を外すだけで済みます。`.fn.where`のような関数で書く条件は中身を解析できないため、`queryKey`に参照する値を入れて渡す必要があります。無ければ`UnhashableQueryIRError`になります。

### 行の状態とエラーを表すAPIの改名

名前だけでなく、真偽の向きが逆になったものもあります。移行ガイドの対応表のうち、アプリのコードに出やすいものを抜き出しました。

| 0.9.2まで                           | 1.0 RC                                     |
| --------------------------------- | ------------------------------------------ |
| `row.$synced`                     | `!row.$hasPendingWrites`                   |
| `transaction.isPersisted.promise` | `transaction.when('settled')`              |
| フックの`isError`                     | `isLoadingError`・`isCrashed`・`isSyncError` |
| 初回ロード失敗・同期停止の再試行                  | `reload()`                                 |
| Query Collectionの`utils.isError`  | `collection.health`                        |

手元のRCでは、更新が確定する前の行は`$hasPendingWrites`が`true`、確定後は`false`で、`$synced`は`undefined`でした。エラーの扱いも変わっています。一度表示できたデータは、その後に通信が失敗しても`status: 'ready'`のまま残り、問題は`health`に入ります。このため「エラーなら一覧を消す」画面は、`isSyncError`で「最新でない可能性がある」と知らせる形に作り直すことになります。

### include()とgroupKeys()の明示インポート

RCでは、使う演算子だけをバンドルに入れる設計に変わりました。[@tanstack/dbのCHANGELOG](https://github.com/TanStack/db/blob/main/packages/db/CHANGELOG.md)は、Query Collection・絞り込み付きライブクエリ1本・Reactの`useLiveQuery`から成るアプリで、gzip後に約8kB小さくなるとしています。その代わり、`select`の中に子クエリを直接書くと「A subquery in select() needs include(), toArray(), or materialize().」で、集約関数の無い`groupBy`は「groupBy() without an aggregate needs groupKeys()」で止まります。どちらも手元で再現しました。`count()`などの集約を伴う`groupBy`は書き換え不要です。

## ライブクエリの記法と落とし穴

### whereでJavaScript演算子を使ったときの実行時エラー

`where`は行ごとに呼ばれる関数ではなく、クエリを組み立てる宣言です。`!todo.completed`や`todo.s === s`のような素のJavaScript式は受け付けません。困るのは型チェックを通ってしまうことで、TypeScript 7.0.2でも`tsc`はエラーを出さず、RCの実行時に次の例外で止まりました。

```
QueryBuilderError: Invalid where() expression: Expected a query expression, but received a boolean.
This usually happens when using JavaScript's comparison operators (===, !==, <, >, etc.) directly.
```

条件は`eq`・`gt`・`gte`・`lt`・`lte`・`like`・`ilike`・`inArray`・`and`・`or`・`not`・`isNull`・`isUndefined`などの式関数で組みます。`not(todo.completed)`で絞った結果は、`update`を呼んだ直後に件数が1から0へ変わりました。結果は確定を待たず、楽観的状態のまま追従します。

### null比較に適用されるSQL準拠の三値論理

比較の挙動はJavaScriptではなくSQLに合わせてあります。[Live Queriesのdocs](https://tanstack.com/db/latest/docs/guides/live-queries)は、nullやundefinedとの比較は「evaluates to `UNKNOWN`, so the row is not matched」と書いています。`score`がnullの行を2つ含むコレクションで試すと、`eq(t.score, null)`は0件、`isNull(t.score)`は2件でした。`eq`にnullを渡しても警告は出ず、結果が空になるだけです。欠損値を拾うときは`isNull`か`isUndefined`を使います。

## IndexedDB保存とオフライン対応の選択肢

### 0.13.0でコアに入ったIndexedDBコレクション

IndexedDBコレクションは、ブラウザ内で保持するデータを永続化する選択肢です。0.13.0で`indexedDBCollectionOptions`と`createIndexedDB`が`@tanstack/db`に入り、追加のパッケージ無しで使えます。[IndexedDB Collectionのdocs](https://tanstack.com/db/latest/docs/collections/indexed-db-collection)によれば、保存した変更は`BroadcastChannel`で同じオリジンの他のタブにも届きます。

```
import { createCollection, createIndexedDB, indexedDBCollectionOptions } from '@tanstack/db'

const db = await createIndexedDB({ name: 'my-app', version: 1, stores: ['todos'] })
const todos = createCollection(
  indexedDBCollectionOptions<{ id: string; text: string; at: Date }>({
    db,
    name: 'todos',
    getKey: (todo) => todo.id,
  })
)
await todos.preload()
await todos.insert({ id: 'a', text: '下書き', at: new Date() }).when('settled')
```

Node.jsで`fake-indexeddb`を使って確かめたところ、データベースを開き直したあとも行は復元され、`Date`型は`Date`のまま戻りました。localStorageと違い、JSONを経由しないためです。関数のように構造化複製できない値を入れると`SerializationError`で失敗します。ただしdocsは「IndexedDB Collections load their entire object store into memory」としており、ストアの全行がメモリに載ります。容量の上限やブラウザによる削除の条件は[IndexedDBのデメリットと容量上限｜localStorage・Cookieとの違いと使い分け](/tech/details/9666/)で整理しています。

### SQLite永続化とオフライン取引パッケージの使い分け

データが大きい場合や、サーバー同期するコレクションをそのまま再起動後も残したい場合は、[SQLite Persistence](https://tanstack.com/db/latest/docs/guides/sqlite-persistence)の`persistedCollectionOptions`を重ねます。ブラウザ（OPFS）・Node.js・React Native・Expo・Capacitor・Tauri・Electron・Cloudflare Durable Objectsの8つの実行環境向けにパッケージがあり、ブラウザ版はOPFSとsecure contextが前提です。`syncMode: 'on-demand'`と組み合わせると、保存した全行ではなくクエリが求める行だけをコレクションに読み込みます。オフライン中の書き込みを預かるのは[Offline Transactions](https://tanstack.com/db/latest/docs/guides/offline-transactions)の`@tanstack/offline-transactions`（1.2.0）で、Webでは先にIndexedDBを試し、使えなければlocalStorageに未送信の操作を積みます。各試行で渡される`idempotencyKey`を、アプリの送信処理で`Idempotency-Key`ヘッダーなどに設定してください。サーバー側でも同じキーの操作を重複実行しない実装が要ります。

| 手段                             | 保存先                    | 向く用途               |
| ------------------------------ | ---------------------- | ------------------ |
| localStorageCollectionOptions  | localStorage           | 設定値・表示状態           |
| indexedDBCollectionOptions     | IndexedDB              | ブラウザが持ち主の中規模データ    |
| persistedCollectionOptions     | SQLite                 | 同期コレクションの永続化・大量データ |
| @tanstack/offline-transactions | IndexedDB→localStorage | オフライン中の書き込み        |

RC1のブログは、SkylightがReact Nativeの家族カレンダーアプリでDBのオフライン機能を使っている例を挙げています。モバイルアプリでオフライン同期まで含めて設計するなら、端末側の保存とサーバー側の冪等処理を一緒に決める必要があります。弊社の[Flutter / React Native開発](/service/apps/cross%5Fplatform/)でも、この組み合わせからご相談いただけます。

## 導入を見送るべき条件

使わない方がよい場面ははっきりしています。第一に、版を固定して正式版まで追いかける体制が取れないプロジェクトです。0.9.2からRCまでの約7週間で、ハンドラの挙動、フックの引数、エラーの型が変わりました。第二に、画面ごとのエンドポイントで取得が完結し、取得した形のまま表示している構成です。この場合はQueryだけで足り、DBは層を1つ増やすだけになります。第三に、全件を手元に置く前提が合わないデータで、eagerやIndexedDBコレクションのまま数十万行を載せる設計です。

エンドポイントの増殖や楽観的更新の不整合に実際に困っているなら、読み取りの1画面からDBに寄せ、書き込みは既存のAPI呼び出しのまま`utils.refetch()`で待つ構成が安全な入口です。[TanStack Startとは？1.0安定版の変更点と使い方・SEO設定・Bun/Dockerデプロイ【1.169】](/tech/details/10179/)や[TanStack Routerとは？型安全ルーティングの特徴・導入手順とReact Routerとの違い](/tech/details/9913/)と組む場合は、SSRでのデータ受け渡しにRCの`DbClient`の`dehydrate()`と`hydrate()`を使います。

## よくある質問

### TanStack DBはTanStack Queryの置き換えですか？

置き換えではありません。公式Overviewは「extends TanStack Query」と書いており、取得はQuery、取得したデータの正規化・ライブクエリ・楽観的更新はDBが受け持ちます。`queryCollectionOptions`で既存の`queryFn`を使い回せるので、コレクション単位で一部から導入できます。

### TanStack DBでIndexedDBにデータを保存できますか？

保存できます。0.13.0から`@tanstack/db`に`indexedDBCollectionOptions`が入り、再読み込み後も行が復元されます。ストアの全行をメモリに読み込む方式です。大量データで全件の読み込みを避けるには、SQLite永続化の`persistedCollectionOptions`に`syncMode: 'on-demand'`を組み合わせます。

### Reactでブラウザ内のデータベースとして使えますか？

クエリ部分はデータベースに近い書き方ができますが、TanStack DB自体はストレージエンジンではなく、行をメモリに持つクライアントストアです。再起動後も残すには、IndexedDBコレクションかSQLite永続化を組み合わせます。SQLを直接実行したい用途とは違います。

### localStorageに保存するコレクションはどんな用途向けですか？

公式docsは「small amounts of local-only state」としており、ユーザー設定や表示状態のような小さなデータ向けです。localStorageは文字列しか保存できず、容量もオリジンごとに5MiB程度なので、業務データの行を貯める用途にはIndexedDBコレクションを選びます。

### TanStack DBは本番環境で使えますか？

2026年10月29日のRC1のブログは本番利用できる段階だとしていますが、版は1.0.0-rc.1.4でまだ正式版ではなく、READMEにはBETA表記が残っています。使うなら版を固定し、正式版までのCHANGELOGを読んで更新する運用を前提にしてください。Prisma StudioやUnkeyのダッシュボードが採用例として挙がっています。

## 関連記事

- [TanStack Queryとは？React Queryとの違い・v5の使い方と既定値の落とし穴](/tech/details/10307/)
- [ElectricSQLとは？Postgres同期エンジンの仕組み・導入手順と2026年の変化](/tech/details/7220/)
- [IndexedDBのデメリットと容量上限｜localStorage・Cookieとの違いと使い分け](/tech/details/9666/)
- [TanStack Startとは？1.0安定版の変更点と使い方・SEO設定・Bun/Dockerデプロイ【1.169】](/tech/details/10179/)
- [Zustandとは？読み方・使い方とv5の注意点【5.0.16対応】](/tech/details/7615/)

---

出典: [TanStack DBとは？TanStack Queryとの違い・使い方と1.0 RCの変更点](<https://www.issoh.co.jp/tech/details/8738/>)（株式会社一創）
