> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/trailbaseio/trailbase/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Common questions and answers about TrailBase

## General

<Accordion title="What is TrailBase?">
  TrailBase is an open-source, single-executable Firebase alternative built on Rust, SQLite, and Wasmtime. It provides type-safe REST APIs, realtime subscriptions, authentication, WebAssembly runtime, geospatial support, and an admin UI - all in a single binary with sub-millisecond latencies.
</Accordion>

<Accordion title="Why should I use TrailBase instead of Firebase or Supabase?">
  TrailBase offers several advantages:

  * **Single executable**: No complex deployments or microservices to manage
  * **Sub-millisecond latencies**: Fast enough to eliminate the need for dedicated caches
  * **SQLite-based**: Predictable performance with no network latency to database
  * **Open source with copyleft license**: Free to use with OSL-3.0
  * **Built-in WebAssembly runtime**: Extend functionality with custom server-side logic
  * **Geospatial support**: First-class support for geometric/geospatial data and querying
  * **Easy self-hosting**: Deploy anywhere without worrying about dependencies

  See our [comparisons page](/resources/comparisons) for detailed feature comparisons.
</Accordion>

<Accordion title="What does 'single-executable' mean?">
  TrailBase compiles into a single binary file with no external dependencies. You simply download the executable for your platform (Linux, macOS, or Windows) and run it - no need to install databases, runtimes, or deal with shared-library version conflicts.
</Accordion>

<Accordion title="Is TrailBase production-ready?">
  TrailBase is currently in **alpha** status. While it's being actively developed and used in real projects, the API may still change and you should expect some rough edges. We're working toward a stable 1.0 release.

  For production use:

  * Test thoroughly in your specific use case
  * Be prepared to handle potential breaking changes
  * Join our community to stay updated on releases
  * Consider the alpha status when planning mission-critical deployments
</Accordion>

## Installation & Deployment

<Accordion title="How do I install TrailBase?">
  TrailBase can be installed in multiple ways:

  **Quick install (Linux & macOS):**

  ```sh theme={null}
  curl -sSL https://trailbase.io/install.sh | bash
  ```

  **Quick install (Windows):**

  ```powershell theme={null}
  iwr https://trailbase.io/install.ps1 | iex
  ```

  **Using Docker:**

  ```sh theme={null}
  alias trail='mkdir -p traildepot && docker run -p 4000:4000 -e ADDRESS=0.0.0.0:4000 --mount type=bind,source="$PWD"/traildepot,target=/app/traildepot trailbase/trailbase /app/trail'
  ```

  **Manual download:**
  Download pre-built binaries from [GitHub Releases](https://github.com/trailbaseio/trailbase/releases/).

  See our [installation guide](/getting-started/install) for more details.
</Accordion>

<Accordion title="What are the system requirements?">
  Minimal requirements:

  * **Operating System**: Linux (x64, arm64), macOS (x64, arm64), or Windows (x64)
  * **Memory**: 512MB RAM minimum, 1GB+ recommended
  * **Disk**: 50MB for the binary, plus storage for your data
  * **Architecture**: x86\_64 or aarch64 (arm64)

  No additional dependencies or runtimes are required.
</Accordion>

<Accordion title="Can I deploy TrailBase to cloud platforms?">
  Yes! TrailBase can be deployed to any platform that supports Docker or native executables:

  * **Cloud VMs**: AWS EC2, Google Compute Engine, DigitalOcean Droplets, etc.
  * **Container platforms**: Kubernetes, Docker Swarm, ECS, Cloud Run
  * **Platform-as-a-Service**: Fly.io, Railway, Render
  * **On-premises**: Any Linux, macOS, or Windows server

  See our deployment guides for specific platforms.
</Accordion>

## Features & Capabilities

<Accordion title="Does TrailBase support realtime data synchronization?">
  Yes! TrailBase provides realtime change subscriptions through:

  * **Server-Sent Events (SSE)**: Default realtime protocol
  * **WebSockets**: Available when compiled with the "ws" feature
  * **Filtered subscriptions**: Subscribe only to changes matching specific criteria
  * **Record-level granularity**: Track changes to specific tables or views

  All official client libraries support realtime subscriptions.
</Accordion>

<Accordion title="What authentication methods are supported?">
  TrailBase supports multiple authentication methods:

  * **Email/Password**: Traditional credential-based auth with email verification
  * **OAuth providers**: Google, GitHub, Discord, GitLab, Microsoft, Twitch, Yandex, and Apple
  * **OIDC**: Custom OpenID Connect providers
  * **PKCE flow**: For mobile and desktop applications
  * **Session management**: JWT-based authentication with refresh tokens

  Password hashing supports both Argon2 and bcrypt algorithms.
</Accordion>

<Accordion title="Can I use my own custom logic with TrailBase?">
  Absolutely! TrailBase includes a WebAssembly runtime that allows you to:

  * Write custom HTTP endpoints
  * Implement background jobs
  * Create custom SQLite extension functions
  * Use JavaScript, TypeScript, or Rust for guest code

  See our [WASM documentation](/customize/wasm) for examples and guides.
</Accordion>

<Accordion title="Does TrailBase support geospatial data?">
  Yes! TrailBase has first-class support for geometric/geospatial data:

  * **GeoJSON support**: APIs automatically recognize geometry columns and work with GeoJSON
  * **Spatial queries**: Filter using `@within`, `@intersects`, and `@contains` operators
  * **LiteGIS extension**: In-house GEOS SQLite extension for spatial operations
  * **WKB/WKT formats**: Internal storage in Well Known Binary, queries in Well Known Text
  * **Spatial indexing**: Create indexes to accelerate geometric relationship queries

  This feature was introduced in v0.24.0.
</Accordion>

<Accordion title="Can I use TrailBase with multiple databases?">
  Yes! TrailBase supports multi-DB setups:

  * Each Record API can be backed by tables/views in independent databases
  * Helps with physical isolation and locking bottleneck avoidance
  * Config-driven database lifecycle management
  * Per-database file upload and migration management
  * SQLite `JOIN`s can cross database boundaries

  Note: `FOREIGN KEY`s and `TRIGGER`s cannot cross DB boundaries due to SQLite limitations.
</Accordion>

## Data & APIs

<Accordion title="What database does TrailBase use?">
  TrailBase uses **SQLite** as its embedded database. SQLite is:

  * The most widely deployed database engine in the world
  * ACID-compliant with full transaction support
  * Extremely fast for read-heavy workloads
  * Serverless and requires no configuration
  * Highly reliable with extensive testing

  TrailBase includes custom SQLite extensions for enhanced functionality.
</Accordion>

<Accordion title="Are the APIs automatically generated?">
  Yes! TrailBase automatically generates type-safe REST APIs from your database schema:

  * Create, Read, Update, Delete operations
  * List with filtering, sorting, and pagination
  * Configurable access control rules
  * JSON schema validation
  * OpenAPI specification output

  You can configure APIs through the admin UI or config files.
</Accordion>

<Accordion title="How do I handle file uploads?">
  TrailBase has built-in file handling:

  * Define `BLOB` columns in your tables
  * APIs automatically handle multipart/form-data uploads
  * Files are stored in the filesystem with references in the database
  * Support for single and multiple file columns
  * Image preview in admin UI
  * Per-database file lifecycle management
</Accordion>

<Accordion title="Can I use SQL views with TrailBase?">
  Yes! TrailBase supports creating Record APIs backed by SQL views:

  * All CRUD operations work with views (where applicable)
  * Complex joins and aggregations
  * Foreign key expansion support
  * Computed columns with type inference
  * Same access control as table-backed APIs

  Views must have a unique primary key or define one using `GROUP BY`.
</Accordion>

## Development & Customization

<Accordion title="Do I need to learn Rust to use TrailBase?">
  No! TrailBase is designed to be used without Rust knowledge:

  * Admin UI for visual configuration
  * SQL for schema definition
  * Standard REST APIs for client applications
  * WebAssembly for custom logic (JavaScript, TypeScript, or Rust)

  You only need Rust if you want to modify TrailBase itself or build custom extensions.
</Accordion>

<Accordion title="What client libraries are available?">
  TrailBase provides official client libraries for:

  * **JavaScript/TypeScript**: npm package `trailbase`
  * **Dart/Flutter**: pub.dev package `trailbase`
  * **Rust**: crates.io package `trailbase-client`
  * **C#/.NET**: NuGet package `TrailBase`
  * **Swift**: Available in the repository
  * **Kotlin**: Maven package `trailbase-client`
  * **Go**: Available in the repository
  * **Python**: PyPI package `trailbase`

  All clients are dual-licensed under Apache-2.0.
</Accordion>

<Accordion title="Can I migrate my schema with TrailBase?">
  Yes! TrailBase includes schema migration support:

  * Place SQL migration files in `traildepot/migrations/`
  * Migrations are automatically applied on startup
  * Reload migrations with `SIGHUP` signal (no restart needed)
  * Per-database migration directories in multi-DB setups
  * Admin UI provides SQL editor for quick changes (not recommended for production)

  Migrations use a versioning system to track applied changes.
</Accordion>

<Accordion title="Is there an admin interface?">
  Yes! TrailBase includes a comprehensive admin UI accessible at `/_/admin/`:

  * Visual database schema editor
  * Data browser and editor
  * Record API configuration
  * User management
  * OAuth provider setup
  * SQL query editor
  * Logs and analytics
  * Schema visualization (ERD)
  * Access from any browser - mobile responsive
</Accordion>

## Performance & Scaling

<Accordion title="How fast is TrailBase?">
  TrailBase delivers **sub-millisecond latencies** for most operations:

  * p50 latencies often under 0.5ms
  * p99 latencies typically under 5ms
  * No network latency to database
  * Fast enough to eliminate need for dedicated caches

  See our [benchmarks page](/resources/benchmarks) for detailed performance data.
</Accordion>

<Accordion title="How does TrailBase scale?">
  TrailBase scales well for many use cases:

  * **Vertical scaling**: SQLite performs excellently on modern hardware
  * **Read-heavy workloads**: Multiple concurrent readers with no contention
  * **Single-writer model**: SQLite's write serialization is the main scaling constraint
  * **Multi-DB support**: Distribute writes across independent databases
  * **Efficient resource usage**: Low memory footprint and CPU overhead

  For very high write-throughput requirements, consider sharding or a distributed database.
</Accordion>

<Accordion title="What are the limitations of SQLite?">
  SQLite has some constraints to be aware of:

  * **Single writer**: Only one write transaction at a time per database
  * **File-based**: Database is a single file (use multi-DB for isolation)
  * **Size limits**: Practical limit around 140TB (far more than most need)
  * **Concurrent writes**: Write transactions are serialized

  For most applications, these limitations are not problematic. TrailBase's sub-millisecond performance and multi-DB support help mitigate these constraints.
</Accordion>

## Security & Licensing

<Accordion title="What license is TrailBase released under?">
  TrailBase is licensed under **OSL-3.0** (Open Software License 3.0):

  * Open source and free to use
  * Copyleft license ensuring modifications are shared
  * Your application code is NOT affected by copyleft
  * Only modifications to TrailBase itself must be released
  * Client libraries are dual-licensed under Apache-2.0

  See our [license page](/resources/license) for more details.
</Accordion>

<Accordion title="How do I report security vulnerabilities?">
  Security issues should be reported privately to: **[security@trailbase.io](mailto:security@trailbase.io)**

  Please do NOT open public GitHub issues for security vulnerabilities. Include:

  * Commit version where the issue exists
  * Proof of concept
  * Steps to reproduce
  * Recommended fixes (if any)

  See our [SECURITY.md](https://github.com/trailbaseio/trailbase/blob/main/SECURITY.md) for the full policy.
</Accordion>

<Accordion title="Is my data secure with TrailBase?">
  TrailBase includes several security features:

  * **Password hashing**: Argon2 or bcrypt algorithms
  * **JWT authentication**: Secure token-based auth
  * **Access control**: Row-level security rules per API
  * **CORS support**: Configurable cross-origin policies
  * **Rate limiting**: Protection against brute force and abuse
  * **HTTPS support**: TLS encryption for data in transit

  Always follow security best practices and keep TrailBase updated.
</Accordion>

## Community & Support

<Accordion title="How do I get help with TrailBase?">
  Several support options are available:

  * **Documentation**: [trailbase.io](https://trailbase.io)
  * **GitHub Issues**: [Bug reports and feature requests](https://github.com/trailbaseio/trailbase/issues)
  * **GitHub Discussions**: Community Q\&A and discussions
  * **Discord**: Join the TrailBase Discord community
  * **Email**: For security issues only: [security@trailbase.io](mailto:security@trailbase.io)

  See our [support page](/resources/support) for more details.
</Accordion>

<Accordion title="How can I contribute to TrailBase?">
  Contributions are very welcome! You can:

  * Report bugs and suggest features on GitHub
  * Submit pull requests with fixes or improvements
  * Improve documentation
  * Help answer questions in the community
  * Share your TrailBase projects and examples

  For anything beyond bug fixes, please discuss your proposal first to ensure it aligns with the project roadmap. See our [contributing page](/resources/contributing) for details.
</Accordion>

<Accordion title="Is there a roadmap for future features?">
  Yes! See our [roadmap page](/resources/roadmap) for upcoming features and development plans. TrailBase is actively developed with regular releases.
</Accordion>

## Migration & Integration

<Accordion title="Can I migrate from Firebase to TrailBase?">
  Yes, but migration requires planning:

  * **Database**: Export Firebase data and import into SQLite
  * **Authentication**: TrailBase supports Auth0 user imports (can be extended)
  * **APIs**: You'll need to map Firebase collections to TrailBase Record APIs
  * **Realtime**: Both support realtime subscriptions with similar concepts
  * **Functions**: Migrate Cloud Functions to WASM components

  The migration complexity depends on how much Firebase-specific functionality you use.
</Accordion>

<Accordion title="Can I export my data from TrailBase?">
  Absolutely! TrailBase avoids lock-in:

  * Your data is stored in standard SQLite format
  * Use any SQLite tool to access the database directly
  * Export via SQL queries or SQLite `.dump`
  * REST APIs for programmatic export
  * Standalone SQLite extensions available separately

  TrailBase is designed to make horizontal mobility easy.
</Accordion>

<Accordion title="Can I use TrailBase with my existing frontend framework?">
  Yes! TrailBase works with any frontend framework:

  * React, Vue, Angular, Svelte, Solid, etc.
  * Flutter and React Native for mobile
  * Desktop frameworks (Electron, Tauri, etc.)
  * Server-side rendering (Next.js, Nuxt, SvelteKit, etc.)

  TrailBase provides standard REST APIs and WebSocket/SSE support that work with any HTTP client.
</Accordion>