DOCSEARCHbyAlgolia
Submit Docs

TrailBase Documentation

repository·main·Indexed 26 days ago

https://github.com/trailbaseio/trailbase

An open, sub-millisecond, single-executable Firebase alternative built with Rust, Wasmtime, and SQLite. It features type-safe REST and realtime APIs, a built-in WebAssembly runtime, authentication, geospatial capabilities, and an integrated Admin UI. TrailBase provides first-party client libraries for JavaScript/TypeScript, Dart/Flutter, Rust, C#/.Net, Swift, Kotlin, Go, and Python.

Tokens
40.5K
Snippets
109
Records
314
Agent score
90%

What's inside TrailBase

  2. Overview of TrailBase Auth UI WASM Component

    main

    The TrailBase Auth UI is a standalone WebAssembly (WASM) component used for authentication interfaces. It has been unbundled from the core TrailBase engine to allow for easier customization, better composability via a plugin-like system, and to reduce overhead for users who do not require the default UI.

    Developers can build their own custom Auth UIs either client-side or server-side.

  3. Overview of the TrailBase Client

    main
    The TrailBase Client is the first-party library used to connect web applications and headless environments (such as Node.js or Deno) to a TrailBase instance. TrailBase itself is a single-executable Firebase alternative featuring type-safe APIs, a built-in WebAssembly runtime, real-time capabilities, authentication, and an admin UI, built using Rust, SQLite, and Wasmtime.

  4. Compare TrailBase with PocketBase and Supabase

    main

    TrailBase is positioned as a middle ground between Supabase and PocketBase:

    • Supabase: Known for versatility and principled architecture.
    • PocketBase: Known for being a single-executable, SQLite-based, easy-to-use offering.
    • TrailBase: Aims to combine the flexibility and architecture of Supabase with the low-overhead and ease of use found in PocketBase.

  5. Understand TrailBase scaling and performance

    main

    TrailBase is built on SQLite, providing high concurrency and sub-millisecond response times.

    • Scaling Strategy: It supports 'multi-reader, single-writer' horizontal scaling via read replication. For massive scale, vertical scaling is often sufficient for tens or hundreds of thousands of concurrent users.
    • Write Performance: It is suitable for most workloads unless you require hundreds of thousands of latency-critical, consistent writes per second.
    • Disaster Recovery: You can achieve disaster recovery and fail-over using tools like LiteStream to maintain eventually consistent copies of your data.
    • Modularity: TrailBase is designed to be modular, allowing you to replace or extend components (like adding a document store or queuing system) as your scale requirements change.

  6. License Information: Open Software License v. 3.0 (OSL-3.0)

    main

    TrailBase is licensed under the Open Software License version 3.0 (OSL-3.0).

    Key Terms for Users and Developers:

    • Permissions: You are granted a worldwide, royalty-free, non-exclusive, sublicensable license to reproduce, translate, adapt, modify, distribute, perform, and display the Original Work.
    • Derivative Works: You may create derivative works, but any copies of the Original Work or Derivative Works that you distribute or communicate to the public must also be licensed under the Open Software License.
    • External Deployment: If you deploy the work in a way that allows others to use it (e.g., as a network application), this is considered a distribution under the license terms.
    • Attribution: You must retain all copyright, patent, or trademark notices from the original source code. You must also include a prominent notice in your derivative works stating that you have modified the original work.
    • Patent License: The license includes a grant of patent rights from the licensor for patent claims embodied in the Original Work.
    • No Endorsement: You cannot use the names of the Licensor, contributors, or their trademarks to endorse or promote products derived from the work without express permission.
    • Disclaimer: The work is provided on an "AS IS" basis without any warranties of any kind.

  7. Use the TrailBase Client for Flutter and Dart

    main
    The TrailBase Client is the first-party library designed to connect Flutter or Dart applications to a TrailBase backend. TrailBase provides a sub-millisecond, single-executable Firebase alternative with type-safe APIs, a built-in WebAssembly runtime, real-time capabilities, authentication, and an admin UI.

  8. Compare TrailBase performance benchmarks

    main

    TrailBase performance is evaluated against alternatives like SupaBase, PocketBase, and vanilla SQLite. Key performance characteristics include:

    • Insertion Speed: TrailBase is significantly faster than competitors for high-volume inserts (e.g., 100k records), outperforming Payload, SupaBase, and PocketBase in benchmarked scenarios.
    • Resource Utilization: TrailBase maintains a low footprint, typically consuming between 90MB and 150MB of memory (RSS) and utilizing 4 to 5 CPUs, making it suitable for small VPS environments. This is significantly lower than SupaBase's multi-service architecture.
    • Latency: TrailBase offers sub-millisecond read latencies, comparable to Redis, but functions as primary data rather than a cache. This can simplify stacks by eliminating the need for separate caching layers.
    • Runtime Performance: While JS/TS execution via the WASM runtime is comparable to JIT-less engines (like Goja), guest languages that compile to WASM (like Rust) see massive performance gains (up to ~135x speed-up).

  10. Build and deploy TypeScript WASM components

    main

    To turn a TypeScript endpoint into a .wasm component that TrailBase can load:

    1. Build the JavaScript library using npx vite build.
    2. Componentize the output using jco: npx jco componentize dist/index.js -w node_modules/trailbase-wasm/wit -o dist/component.wasm.
    3. Copy the resulting component.wasm into the <traildepot>/wasm/ directory.
    # Build a JavaScript library from our TypeScript endpoint:
npx vite build

# Build the WASM component:
npx jco componentize dist/index.js -w node_modules/trailbase-wasm/wit -o dist/component.wasm

# Copy it to our <traildepot>/wasm
mkdir -p <traildepot>/wasm
cp dist/component.wasm <traildepot>/wasm/

  11. Implement relations in TrailBase

    main

    TrailBase handles relations using standard SQL patterns. All relations are modeled as edges (tuples of parent id, child id).

    • 1:1 and 1:M relations: These are typically denormalized by placing the foreign key directly in the child record (primary key, foreign key). This allows for built-in SQL features like ON DELETE or ON UPDATE cascading.
    • N:M (Many-to-Many) relations: These require a separate "bridge" table containing (foreign key, foreign key) edge records to manage the cardinality.

    While some databases (like PocketBase) use JSON arrays for relations, TrailBase follows SQL best practices by using foreign keys and bridge tables to ensure compatibility with SQLite's relational engine and referential integrity.