TanStack DB In 15 Minutes! ORM or State Manager?

Tanstack DB: Collections, Queries, and State Management

Key Concepts:

• Tanstack DB: A state management model based on synced collections and live SQL-style queries. It is not an ORM.
• Collections: In-memory or persistent data stores that hold data with a defined schema (using Zod in the example). Can be backed by various sources (in-memory, local storage, Tanstack Query, ElectricSQL).
• Queries: SQL-style queries performed on collections, enabling filtering, joining, and selecting data.
• Live Queries: Queries that automatically update when the underlying data in the collections changes.
• ElectricSQL: A system that monitors a PostgreSQL database and sends events to clients when changes occur, enabling real-time updates.
• Pub/Sub: Publish-subscribe mechanism for real-time data updates.

1. Introduction to Tanstack DB

• Tanstack DB is presented as a novel approach to state management, distinct from traditional ORMs like Prisma or Drizzle.
• It centers around the concepts of synced collections and live SQL-style queries.
• Collections can be backed by various data sources, including databases via APIs, or directly through ElectricSQL for PostgreSQL.
• The video focuses on demonstrating collections and queries using a DIY approach for fundamental understanding.

2. Practical Demonstration with Create Start App

• The demonstration utilizes create start app with a built-in DB demo.
• The app is named "my chat app" and configured to include Tanstack DB.
• The demo showcases a simple chat system to illustrate the core concepts.

3. Collections: Structure and Types

• The messages collection is defined in DB/collections/index.ts.
• It holds messages with a schema defined using Zod, including id, text, and user fields.
• Different collection types are explained:
  • Local Only Collection: Data is held in memory.
  • Local Storage Collection: Data is synced to and from local storage.
  • Tanstack Query Collection: Data is fetched from Tanstack Query and stored in the collection, allowing for continuous refetching.
  • ElectricSQL Collection: Connects to an ElectricSQL instance, which monitors a PostgreSQL database for changes and pushes updates to the UI in real-time.

4. Implementing Real-time Updates with useStreamConnection Hook

• The useStreamConnection hook in hooks/ establishes a stream connection to a chat API (demo db chat API).
• It uses use effect to fetch data from the API endpoint as a stream of JSON payloads separated by returns.
• The incoming stream is decoded, split into chunks, and inserted into the messages collection using collection.insert().
• Sending new messages involves posting to the same API endpoint with the message text and user information.

5. Live Queries with useLiveQuery Hook

• The useLiveQuery hook from Tanstack ReactDB is used to subscribe to queries on the messages collection.
• The hook takes a function that defines the query, similar to a SQL statement.
• The example demonstrates selecting all messages from the messages collection.
• The video emphasizes that Tanstack DB core is framework-agnostic, with implementations like Tanstack ReactDB providing framework-specific hooks.

6. Server-Side Collections and Pub/Sub

• The DB chat API.ts file in routes/ defines the server route for the chat API.
• The server also uses a Tanstack DB collection to manage messages.
• The get method returns a readable stream of messages.
• The post method adds new messages to the server-side collection.
• The server uses collection.subscribeChanges() to implement a pub/sub mechanism, notifying clients of any changes to the messages collection.
• The server sends all existing messages to the client upon connection and then sends any new messages as they are added to the collection.
• The video mentions the possibility of camping on events like onInsert, onUpdate, and onDelete to update a local file or connect to databases.

7. Querying and Filtering Data

• The use messages hook utilizes useLiveQuery to fetch messages from the collection.
• The query is defined using a function that takes a query builder as an argument.
• The example demonstrates selecting all messages from the messages collection.
• The video mentions the ability to use multiple collections, merge them, filter data, and perform joins.

8. Building a Search Panel

• A use search hook is created to implement a search feature.
• The hook takes a search term as input and returns a filtered list of messages.
• A where clause is used to filter messages based on a case-insensitive "like" comparison of the message text with the search term.
• The Ilike function is imported from Tanstack DB.
• A ChatSearch component is created to display the search input and the filtered messages.
• The search functionality is integrated into the DB chat page.
• The video highlights the importance of adding dependencies to the useLiveQuery hook to ensure that the query is re-executed when the dependencies change.

9. Tanstack DB as a New State Management Paradigm

• The video positions Tanstack DB as a new category of state management, distinct from existing approaches like:
  • Native React state management (useState, useReducer, useEffect, useMemo)
  • Unidirectional state management (Redux, Zustand)
  • Bidirectional state management (MobX)
  • Event-based state management
  • Atomic-based state management (Jotai, Legend State)
• Tanstack DB offers a client-side database approach with live queries, providing a new way to manage data and ensure consistency between the client and server.

10. ElectricSQL Integration

• The video demonstrates the integration of Tanstack DB with ElectricSQL for real-time data synchronization with a PostgreSQL database.
• A React to-do example is used to showcase the ElectricSQL integration.
• The example uses a Docker instance to run Trailblaze, PostgreSQL, and ElectricSQL.
• The video compares ElectricSQL with Trailblaze and traditional polling with Tanstack Query.
• The demonstration shows that changes made to the database are automatically reflected in the UI in real-time, even across multiple browser windows.

11. Conclusion

• Tanstack DB offers a powerful and flexible approach to state management, combining the benefits of a client-side database with live queries and real-time data synchronization.
• It provides a new paradigm for managing data and ensuring consistency between the client and server.
• The integration with ElectricSQL enables real-time data synchronization with a PostgreSQL database, making it a viable alternative to Firebase or Convex.