DOCSEARCHbyAlgolia
Submit Docs

Instant Documentation

repository·main·Indexed 27 days ago

https://github.com/instantdb/instant

A backend-as-a-service for AI-coded and modern web applications featuring real-time, multiplayer, and offline-capable data synchronization via InstaQL. Includes documentation for the @instantdb/admin SDK, @instantdb/core vanilla JS SDK, @instantdb/components, @instantdb/expo-sqlite for React Native, the instant-cli, and the Instant MCP server for LLM integration.

Tokens
156.4K
Snippets
454
Records
804
Agent score
94%

What's inside Instant

  1. Overview of Instant

    main

    Instant is a real-time database designed to provide a modern alternative to Firebase and Supabase. It aims to eliminate the 'schlep' of traditional three-tier architectures (client, server, database) by providing a reactive database directly on the client.

    Key features include:

    • Reactive Queries: Fetch data directly from the client without managing manual stores, selectors, or endpoints.
    • Optimistic Updates: Transactions apply changes locally immediately, providing a fast UX while syncing with the server.
    • Offline Mode: Built-in support for local persistence.
    • Relational Data: Unlike Firebase, Instant supports relational data structures.
    • Multi-tenancy: High-performance architecture that allows for rapid database provisioning (<10ms).

  2. Overview of Instant core features

    main

    Instant provides a real-time, relational, and multi-tenant backend designed for high-performance and AI-driven development. Key features include:

    • Sync Engine: Provides multiplayer, offline mode, and optimistic updates by default. Developers use db.useQuery for real-time relational queries and db.transact for making changes that work offline.
    • Unlimited Apps: Uses a multi-tenant architecture on top of Postgres, allowing for many isolated projects without the overhead of dedicated VMs.
    • Integrated Services:
      • File Storage: Files are treated as rows in your database, allowing for relational links and CASCADE delete rules.
      • Auth: Built-in support for Magic Codes, OAuth, and Guest Auth.
      • Presence: For sharing cursors, typing indicators, or 'who's online' status.
      • Streams: For sharing durable data streams.

  4. Understand the Client SDK Architecture

    main

    The Instant Client SDK is composed of several layers that enable reactive, offline-capable data fetching:

    • InstaQL: The ergonomic query language used by developers.
    • Datalog Engine: Converts InstaQL into logic-based queries.
    • Triple Store: An immutable data structure that stores data as [entity, attribute, value] tuples, allowing the client to evaluate queries locally.
    • Pending Queue: Tracks local mutations before they are acknowledged by the server. This enables optimistic UI updates and automatic 'undo' if a server transaction fails.
    • IndexedDB: Used for persistent caching of data on the client.
    • Reactor: The central state machine that coordinates the flow between IndexedDB, the server (via WebSockets), and the local Triple Store.

  5. Understanding Triple Stores and Graph Data

    main

    InstantDB utilizes a Triple Store architecture to represent data as a graph. A 'triple' is a list of three items representing a relationship:

    [id, attribute, value]

    Examples:

    • Attributes: [1, 'name', 'Joe'] (User with ID 1 has the name 'Joe')
    • References: [3, 'owner', 1] (Task with ID 3 has an 'owner' reference to User with ID 1)

    This structure allows for highly flexible, schema-optional data modeling and efficient graph traversal without the overhead of complex SQL joins.

  6. Understand Datalog Data Structures and Querying

    main

    Datalog is a logic-based query language that uses 'triples' instead of traditional SQL tables.

    Data Representation: Triples

    Instead of rows in multiple tables, data is stored in a single triple table. Each triple consists of an id, an attribute, and a value.

    Example triple representing a movie title:

    [200, 'movie/title', 'The Terminator']

    Querying via Pattern Matching

    Datalog uses pattern matching to find data. A pattern is an array that can contain specific values or variables.

    • Variables: Indicated by a string starting with a question mark (e.g., "?id"). Variables act as placeholders that can match any value.
    • Attributes: Strings representing the property being queried (e.g., "movie/year").

    To find all movies released in 1987, you would use the pattern: ["?id", "movie/year", 1987]. The engine matches this against triples and binds the value of ?id to the corresponding ID in the triple.

  7. Understand the Backend Architecture

    main

    The Instant backend is designed for reactive queries and multi-tenant resource fairness using a Clojure-based architecture:

    • Query Store: Tracks which users have made which queries to enable reactivity.
    • Topics: A mechanism to describe the specific parts of the database index a query cares about. This prevents unnecessary re-runs of queries.
    • Invalidator: Monitors the Postgres Write-Ahead Log (WAL) to generate 'topics' from transactions. It matches transaction topics against query topics to identify stale data.
    • Grouped Queues: Ensures that transactions within a single app are processed serially (to maintain order) while allowing parallel processing across different apps (to ensure fairness and prevent one app from hogging resources).
    • Session Manager: The main coordinator that handles WebSocket connections, manages reactive queries, runs permissions (using Google's CEL), and routes requests to other services.

  8. Understand Instant architecture and InstaQL

    main

    Instant uses a relational query language called InstaQL, which is inspired by GraphQL. It allows you to request data in a nested structure representing relationships.

    Core Architecture Components:

    • Storage: Data is stored as triples in a multi-tenant Postgres database.
    • Sync Server: A Clojure-based server that manages communication with Postgres and implements the query engine.
    • Query Engine: Understands InstaQL and Datalog.
    • Reactivity: Uses Postgres' Write-Ahead Log (WAL) to detect changes and invalidate relevant queries.
    • Client-side: A client-side triple store that persists a cache to IndexedDB (Web) or AsyncStorage (React Native).
    • Permissions: Powered by Google's CEL library.

  9. Explore InstantDB Documentation Topics

    main

    The InstantDB documentation provides detailed guides for various aspects of the platform. Key topics include:

    • Core Integration: Initializing Instant in your app and modeling data with schemas.
    • Data Operations: Writing data using InstaML and reading data using InstaQL.
    • Backend & Admin: Using the Admin SDK for server-side operations.
    • Authentication: Implementing magic codes, OAuth, Clerk, or custom auth, and managing users.
    • Real-time Features: Adding ephemeral features like presence, cursors, and activity.
    • Tooling & Storage: Using the Instant CLI for schema management and using Instant for file storage and serving.

  10. Conceptual Overview: Graph-Based Data Architecture

    main

    InstantDB is inspired by the architecture of tools like Figma, Linear, and Notion, which treat application data as a graph rather than traditional relational tables. Instead of manually writing complex functions to join data for a specific UI screen (e.g., fetching a team, its tasks, and the task owners), you can use a graph-based query language to declare the nested structure you need. This approach enables features like:

    • Optimistic Updates: Using a mutation system that works identically on the client (Local DB) and server.
    • Multiplayer/Collaboration: Using a triple-store approach to minimize conflicts (e.g., two users changing different properties of the same object simultaneously).
    • Offline-Mode: Backing the Local DB with IndexedDB for persistence and offline capabilities.
    • Live Queries: Using a replication-based system where the client acts as a node that subscribes to data changes.

  11. Understand the Instant Architecture and Design Philosophy

    main

    Instant is designed as a graph-based successor to Firebase, specifically built to solve the complexities of building 'delightful' applications (like Figma, Linear, or Notion).

    Key features provided out-of-the-box include:

    • Optimistic Updates: Changes are applied instantly to the UI, with built-in support for queuing, ordering, undo, and canceling dependent mutations.
    • Multiplayer: Real-time collaboration where all active sessions see changes immediately.
    • Offline-Mode: Support for spotty connections and reduced read latency by using local durable storage (like IndexedDB) to hydrate the store.
    • Relational Queries: Unlike document stores (e.g., Firebase), Instant supports complex relations and graph-based queries.
    • Advanced Permissions: A scalable permission system designed for complex rules, moving beyond simple boolean expressions or basic Row-Level Security.

  12. Conceptual Overview: Database in the Browser

    main

    This document outlines a specification for a 'database in the browser' abstraction. The goal is to provide a developer experience that combines the ease of use and reactivity of Firebase with the query strength of SQL (like Supabase/Postgres) and the powerful permission models used in large-scale systems.

    Key pillars of this vision include:

    • Client-side Database: A local, powerful query engine (similar to datascript) that supports reactive queries and automatic optimistic updates.
    • Real-time Reactivity: The server manages subscriptions so that all relevant clients are notified automatically when data changes.
    • Composable Permissions: Using a real programming language to define entity-level access rules (e.g., IAllowIfAdmin()) rather than limited rule languages.
    • Offline & Conflict Resolution: Built-in support for offline writes and reconcilers to handle server conflicts.
    • Data Piping: A DSL to express data dependencies (e.g., db |> Redis) to automatically sync data to external services like search indexes or caches.