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は、正規化したコレクションにデータを入れ、そこへライブクエリを投げる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の告知ブログによれば、ElectricSQLは8月にNeonに買収され、その後もNeonが開発を支えています。現在の主要メンテナはKyle Mathews氏、Sam Willis氏、Kevin De Porre氏の3人です。TanStackファミリーの中では、取得のTanStack Queryとは?React Queryとの違い・v5の使い方と既定値の落とし穴、表描画のTanStack Tableとは:v9の導入コードとヘッドレス設計・AG Gridとの選び分けと並ぶ、データ層の部品という位置にあります。
0.9.2から1.0.0-rc.1までの版の動き
0.9.2から1.0 RCまでの主な公開版と変更点を、次の表に整理します。日付はnpmレジストリの公開時刻(UTC)で、レジストリのパッケージ情報の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には今も「Tanstack DB is currently in BETA.」が残っています。RCは正式版の前の段階です。採用するなら版を1.0.0-rc.1.4のように固定し、正式版までの差分をCHANGELOGで追ってください。利用は伸びていて、npmのダウンロード統計では、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の告知ブログは、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は「placeholderData is intentionally unsupported.」としています。プレースホルダは観測側の一時的な表示であり、全コンポーネントが共有する行にすべきでない、という理由です。selectも、レスポンスから行の配列を取り出す用途に意味が変わっています。Queryのselectを移す際は、レスポンスから行配列を返す処理になっているか確認してください。移しただけで変換が二重に実行されるわけではありません。
もう一つの違いがRCで加わりました。0.9系までは、onUpdateなどのハンドラが終わると自動でrefetchが走っていましたが、RCではこれが無くなりました。詳しくは次の章の実測で示します。
DBを重ねる価値がある画面の条件
重ねる価値があるのは、1回取ったデータを絞り込みや結合で何通りにも見せる画面や、楽観的更新のキャッシュ書き換えで不具合が出ている画面です。画面ごとにエンドポイントが1本で完結し、取得した形のまま表示しているならQueryだけで足ります。Zustandとは?読み方・使い方とv5の注意点【5.0.16対応】のようなUI状態のストアとは役割が重ならないので、併用して問題ありません。
1.0 RCでの導入とコレクション定義
インストールとパッケージの版の組み合わせ
Reactでの最小構成は次の3つです。@tanstack/react-dbはコアの@tanstack/dbを再エクスポートします。peerDependenciesはReact 18以上です。
npm install @tanstack/[email protected] @tanstack/[email protected] @tanstack/query-core
版の組み合わせには注意が要ります。@tanstack/query-db-collectionと@tanstack/offline-transactionsは、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年の変化の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は、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は、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によれば、保存した変更は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との違いと使い分けで整理しています。
SQLite永続化とオフライン取引パッケージの使い分け
データが大きい場合や、サーバー同期するコレクションをそのまま再起動後も残したい場合は、SQLite PersistenceのpersistedCollectionOptionsを重ねます。ブラウザ(OPFS)・Node.js・React Native・Expo・Capacitor・Tauri・Electron・Cloudflare Durable Objectsの8つの実行環境向けにパッケージがあり、ブラウザ版はOPFSとsecure contextが前提です。syncMode: 'on-demand'と組み合わせると、保存した全行ではなくクエリが求める行だけをコレクションに読み込みます。オフライン中の書き込みを預かるのは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開発でも、この組み合わせからご相談いただけます。
導入を見送るべき条件
使わない方がよい場面ははっきりしています。第一に、版を固定して正式版まで追いかける体制が取れないプロジェクトです。0.9.2からRCまでの約7週間で、ハンドラの挙動、フックの引数、エラーの型が変わりました。第二に、画面ごとのエンドポイントで取得が完結し、取得した形のまま表示している構成です。この場合はQueryだけで足り、DBは層を1つ増やすだけになります。第三に、全件を手元に置く前提が合わないデータで、eagerやIndexedDBコレクションのまま数十万行を載せる設計です。
エンドポイントの増殖や楽観的更新の不整合に実際に困っているなら、読み取りの1画面からDBに寄せ、書き込みは既存のAPI呼び出しのままutils.refetch()で待つ構成が安全な入口です。TanStack Startとは?1.0安定版の変更点と使い方・SEO設定・Bun/Dockerデプロイ【1.169】やTanStack Routerとは?型安全ルーティングの特徴・導入手順とReact Routerとの違いと組む場合は、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のダッシュボードが採用例として挙がっています。