+
+
+
+ })
+
+
+
+
+
+
+
+ );
+}
+
+function adjustScaleColor(
+ dark: boolean,
+ scales: { [key: string]: ScaleOptions<"linear"> },
+) {
+ for (const axis of Object.keys(scales)) {
+ const scale = scales[axis];
+
+ scale.ticks = {
+ ...scales[axis].ticks,
+ color: dark ? "white" : undefined,
+ };
+
+ scale.title = {
+ ...scale.title,
+ color: dark ? "white" : undefined,
+ };
+ }
+
+ return scales;
+}
+
+interface BarChartWithErrorsProps {
+ data: ChartData<"barWithErrorBars">;
+ yTickFormatter?: (
+ value: number | string,
+ index: number,
+ ticks: Tick[],
+ ) => string;
+}
+
+export function BarChartWithErrors(props: BarChartWithErrorsProps) {
+ const darkMode = createDarkMode();
+
+ let ref: HTMLCanvasElement | undefined;
+ let chart: Chart | undefined;
+
+ createEffect(() => {
+ chart?.destroy();
+
+ const scaleIds = props.data.datasets.map((e) => e.yAxisID ?? "y");
+ const yScaleStyle = {
+ ticks: {
+ color: darkMode() ? "white" : undefined,
+ display: true,
+ callback: props.yTickFormatter,
+ },
+ grid: {
+ display: true,
+ lineWidth: 0,
+ tickWidth: 0.5,
+ tickLength: 2,
+ tickColor: darkMode() ? "white" : "black",
+ },
+ };
+
+ chart = new Chart<"barWithErrorBars">(ref!, {
+ type: BarWithErrorBarsController.id,
+ data: props.data,
+ options: {
+ scales: {
+ x: {
+ ticks: {
+ color: darkMode() ? "white" : undefined,
+ },
+ },
+ ...Object.fromEntries(scaleIds.map((id) => [id, yScaleStyle])),
+ },
+ maintainAspectRatio: false,
+ plugins: {
+ // Defers rendering and animation until on screen.
+ deferred: {
+ yOffset: "30%", // defer until 50% of the canvas height are inside the viewport
+ delay: 200, // delay of 500 ms after the canvas is considered inside the viewport
+ },
+ colors: {
+ enabled: true,
+ forceOverride: false,
+ },
+ legend: {
+ position: "bottom",
+ labels: {
+ color: darkMode() ? "white" : undefined,
+ },
+ },
+ },
+ },
+ });
+ });
+
+ onCleanup(() => chart?.destroy());
+
+ return (
+
+
+
+ );
+}
diff --git a/docs/src/components/LineChart.tsx b/docs/src/components/LineChart.tsx
new file mode 100644
index 0000000..6254db8
--- /dev/null
+++ b/docs/src/components/LineChart.tsx
@@ -0,0 +1,85 @@
+import { onCleanup, createEffect } from "solid-js";
+import { Chart, type ChartData, type ScaleOptions } from "chart.js/auto";
+import ChartDeferred from "chartjs-plugin-deferred";
+
+import { createDarkMode } from "@/lib/darkmode";
+
+Chart.register(ChartDeferred);
+
+interface LineChartProps {
+ data: ChartData<"line">;
+ scales?: { [key: string]: ScaleOptions<"linear"> };
+}
+
+export function LineChart(props: LineChartProps) {
+ const darkMode = createDarkMode();
+
+ let ref: HTMLCanvasElement | undefined;
+ let chart: Chart | undefined;
+
+ createEffect(() => {
+ chart?.destroy();
+
+ chart = new Chart(ref!, {
+ type: "line",
+ data: props.data,
+ options: {
+ scales: adjustScaleColor(darkMode(), {
+ ...props.scales,
+ }),
+ maintainAspectRatio: false,
+ plugins: {
+ // Defers rendering and animation until on screen.
+ deferred: {
+ yOffset: "30%", // defer until 50% of the canvas height are inside the viewport
+ delay: 200, // delay of 500 ms after the canvas is considered inside the viewport
+ },
+ colors: {
+ enabled: true,
+ forceOverride: false,
+ },
+ legend: {
+ position: "bottom",
+ labels: {
+ color: darkMode() ? "white" : undefined,
+ },
+ },
+ },
+ interaction: {
+ mode: "nearest",
+ axis: "x",
+ intersect: false,
+ },
+ },
+ });
+ });
+
+ onCleanup(() => chart?.destroy());
+
+ return (
+
+
+
+ );
+}
+
+function adjustScaleColor(
+ dark: boolean,
+ scales: { [key: string]: ScaleOptions<"linear"> },
+) {
+ for (const axis of Object.keys(scales)) {
+ const scale = scales[axis];
+
+ scale.ticks = {
+ ...scales[axis].ticks,
+ color: dark ? "white" : undefined,
+ };
+
+ scale.title = {
+ ...scale.title,
+ color: dark ? "white" : undefined,
+ };
+ }
+
+ return scales;
+}
diff --git a/docs/src/content/config.ts b/docs/src/content/config.ts
new file mode 100644
index 0000000..a4eec59
--- /dev/null
+++ b/docs/src/content/config.ts
@@ -0,0 +1,6 @@
+import { defineCollection } from "astro:content";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+ docs: defineCollection({ schema: docsSchema() }),
+};
diff --git a/docs/src/content/docs/_roadmap.md b/docs/src/content/docs/_roadmap.md
new file mode 100644
index 0000000..2e860c1
--- /dev/null
+++ b/docs/src/content/docs/_roadmap.md
@@ -0,0 +1,21 @@
+Over time, we would like to make TrailBase the best application base it can be.
+Tell us what's missing, what could be better, and what smells.
+Independently, we're very open to contributions, just talk to us first so we
+can figure out how any feature will fit into the overall picture and minimize
+friction.
+For context, some larger features we have on our Roadmap:
+
+- Realtime/notification APIs for subscribing to data changes.
+- S3 buckets and other cloud storage. The backend already supports it but it isn't wired up.
+- Support more Social/OAuth providers.
+- More configurable authentication, more customizable auth UI, and multi-factor.
+- Service-accounts for authenticating and authorizing backends not end-users.
+- Custom scheduled operations. Also enabling more time series use-cases.
+- Many SQLite databases: imagine a separate database by tenant or user.
+- Maybe integrate an ES6 JavaScript runtime or similar.
+- Streamline code-generation, the bindings life-cycle, and first-party
+ support for more languages.
+- Geo-spatial extensions and Geo-Ip for logs.
+- Maybe TLS termination and proxy capabilities.
+- Consider a GraphQL layer to address fan-out and integrate external
+ resources.
diff --git a/docs/src/content/docs/comparison/pocketbase.mdx b/docs/src/content/docs/comparison/pocketbase.mdx
new file mode 100644
index 0000000..093fac7
--- /dev/null
+++ b/docs/src/content/docs/comparison/pocketbase.mdx
@@ -0,0 +1,96 @@
+---
+title: PocketBase
+description: Comparing TrailBase & PocketBase.
+---
+
+Firstly, PocketBase is amazing! It based the trail for single-file, SQLite
+application bases, is incredibly easy-to-use, and a polished experience. Gani,
+the person behind it, is a mad scientist.
+
+At the surface-level there are a lot of similarities between PocketBase and
+TrailBase. In this comparison, we'll dive a little deeper and have a closer
+look at the technical as well as philosophical differences between the two.
+
+### Goals & Aspirations
+
+TrailBase was born out of admiration for PocketBase trying to move the needle
+in a few areas:
+
+- Less abstraction, embracing standards (SQL[^1], JWT, UUID), and untethered access
+ to SQLite/libsql[^2] including features such as recursive CTEs, virtual tables
+ and vector search.
+ The goal is to not get in your way and avoid lock-in by bespoke solutions
+ making it easier adopt TrailBase either fully or as piece-meal as well as
+ getting rid of it based on your product needs.
+- Be just as easy to self-host and be even easier to manage a fleet of
+ deployments across integration tests, development, and production by separating
+ data, configuration, and secrets.
+- Super-powers through SQLite extensions (regex, GIS, ...) including your own [^3].
+- Be lightweight enough to rival plain SQLite performance at least for
+ higher-level languages.
+- Be simple and flexible enough to be an attractive alternative to plain SQLite
+ for serving **and** data analysis use-cases.
+
+### Differences
+
+It's worth noting that PocketBase and TrailBase have a lot in common: they are
+both single-file, static binaries providing data APIs, authentication and file
+storage on top of SQLite.
+That said and for the sake of this article, let's look at some of the
+differences and extra features that PocketBase provides:
+
+- TrailBase does not yet provide realtime APIs allowing clients to subscribe to
+ data changes.
+- PocketBase lets you register custom endpoints in
+ [ES5 JavaScript](https://pocketbase.io/docs/js-overview/).
+- PocketBase can also be used as a Go framework, i.e. instead of using the
+ binary release one can build a custom binary with custom endpoints.
+
+Likewise, TrailBase has a few nifty tricks up its sleeve:
+
+- Language independent type-safety via JSON Schemas with strict typing
+ being enforced all the way down to the database level[^4].
+- First-class access to all of SQLite/libsql's features and capabilities.
+- A simple auth UI.
+- Stateless JWT auth-tokens for simple, hermetic authentication in other
+ backends.
+- Efficient and stable cursor-based pagination.
+- An admin UI that "works" on small screens and mobile :)
+
+### Language & Performance
+
+Another difference is that PocketBase and TrailBase are written in Go and Rust,
+respectively, which may matter to you especially when modifying either or using
+them as "frameworks".
+
+Beyond personal preferences, both languages are speedy options in practice.
+That said, Rust's lack of a runtime and lower FFI overhead should make it the
+more performant choice.
+To our own surprise, we found a significant gap. TrailBase is roughly 3.5x to
+7x faster, in our [simplistic micro-benchmarks](/reference/benchmarks)
+depending on the use-case.
+Not to toot our own horn, this is mostly thanks to combining a very low
+overhead language, one of the fastest HTTP servers, and incredibly quick
+SQLite/libsql.
+
+
+
+---
+
+[^1]: Maybe more in line with SupaBase's philosophy. We suspect that PocketBase
+ relies on schema metadata by construction requiring alterations to be
+ mediated through PocketBase APIs to stay in sync.
+
+[^2]: We believe that SQL a ubiquitous evergreen technology, which in of itself
+ is already a high-level abstraction for efficient, unified cross-database
+ access.
+ Even higher-level abstractions, such as ORMs, often look nice for simple
+ examples but quickly fall flat for more complex ones. They're certainly
+ bespoke, non-transferable knowledge, and increase vendor lock-in.
+
+[^3]:
+ All extensions can be built into a small, standalone shared library and
+ imported by vanilla SQLite avoiding vendor lock-in.
+
+[^4]: SQLite is not strictly typed by default. Instead column types merely a
+ type affinity for value conversions.
diff --git a/docs/src/content/docs/comparison/supabase.mdx b/docs/src/content/docs/comparison/supabase.mdx
new file mode 100644
index 0000000..702cf71
--- /dev/null
+++ b/docs/src/content/docs/comparison/supabase.mdx
@@ -0,0 +1,44 @@
+---
+title: SupaBase
+description: Comparing TrailBase & SupaBase.
+---
+
+Both SupaBase and Postgres are amazing. Comparing either to TrailBase and
+SQLite, respectively, is challenging given how different they are
+architecturally.
+
+For one, both Postgres and SupaBase are heck of a lot more modular. "Rule 34" of
+the database world: if you can think of it, there's a Postgres extension for it.
+And SupaBase doesn't an excellent job at making all that flexibility available
+without getting in the way and giving you untethered access while further
+expanding upon it.
+In many ways, TrailBase is trying to evnetually do the same for SQLite:
+combining PocketBase's simplicity with SupaBase's layering.
+
+One foundational difference is that Postgres itself is a multi-user,
+client-server architecture already.
+Extending it by building a layered services around it, like SupaBase did,
+feels very natural.
+However, SQLite is neither a multi-user system nor a server. Hence, extending
+it by embedding it into a monolith, like PocketBase did, feels fairly natural
+as well.
+There are ups and downs to either approach. The layered service approach, for
+example, allows for isolated failure domains and scaling of individual
+components [^1]. The monolith, on the other hand, with its lesser need for modularity
+can have fewer interaction points, fewer moving parts making it fundamentally
+simpler, cheaper, and
+[lower overhead (10+x performance difference)](/reference/benchmarks).
+
+Ultimately, the biggest difference is that SupaBase is a polished product with
+a lot of mileage under its belt. Our simpler architecture will hopefully let us
+get there but for now SupaBase is our north star.
+
+
+
+---
+
+[^1]:
+ For example, in our performance testing we've found that PostgREST,
+ SupaBase's RESTful API layer in front of Postgres, is relatively resource
+ hungry. This might not be an issue since one can simply scale by pointing
+ many independent instances at the same database instance.
diff --git a/docs/src/content/docs/contact.mdx b/docs/src/content/docs/contact.mdx
new file mode 100644
index 0000000..732c7fe
--- /dev/null
+++ b/docs/src/content/docs/contact.mdx
@@ -0,0 +1,11 @@
+---
+title: Contact
+template: splash
+---
+
+
+ Sebastian
+ contact [at] trailbase.io
+
+ 8047 Zurich, Switzerland
+
diff --git a/docs/src/content/docs/documentation/APIs/query_apis.mdx b/docs/src/content/docs/documentation/APIs/query_apis.mdx
new file mode 100644
index 0000000..1c9446e
--- /dev/null
+++ b/docs/src/content/docs/documentation/APIs/query_apis.mdx
@@ -0,0 +1,56 @@
+---
+title: Query APIs
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+Query APIs are a more free-form and type-unsafe way of exposing data using
+virtual tables based on user inputs and stored procedures. Please make sure to
+take a look at [record APIs](/documentation/apis/record_apis) first. Views and
+generated columns may be a better fit for transforming data if no explicit user
+input is required.
+
+
+
+## Example
+
+Using migrations and sqlean's `define` we can define a table query with unbound
+inputs (see placeholder $1):
+
+```sql
+CREATE VIRTUAL TABLE
+ _is_editor
+USING
+ define((SELECT EXISTS (SELECT * FROM editors WHERE user = $1) AS is_editor));
+```
+
+Subsequently, an API can be configured to query the newly created `VIRTUAL
+TABLE`, also binding URL query parameters as inputs to above placeholders.
+
+```proto
+query_apis: [
+ {
+ name: "is_editor"
+ virtual_table_name: "_is_editor"
+ params: [
+ {
+ name: "user"
+ type: BLOB
+ }
+ ]
+ acl: WORLD
+ }
+]
+```
+
+Finally, we can query the API, e.g. using curl:
+
+```bash
+curl -g 'localhost:4000/api/query/v1/is_editor?user=+ `POST /api/v1/records/
+ `GET /api/v1/records/
+ `PATCH /api/v1/records/
+ `DELETE /api/v1/records/
+ `GET /api/v1/records/
+ `GET /api/v1/records/
+
+
+## Flows & UI
+
+TrailBase currently implements the following auth flows:
+
+- Email + password based user registration and email verification.
+- User registration using social OAuth providers (Google, ...)
+- Login & logout.
+- Change & reset password.
+- Change email.
+- User deletion.
+- Avatar management.
+
+Besides the flows above, TrailBase also ships with a set of simple UIs to
+support the above flows. By default it's accessible via the route:
+`
+
+
+
+
+
+
+
+
+ #### Live Demo
+
+ Total time for 100k insertions
+ + + TrailBase adds minimal overhead compared to in-process SQLite and + beats other excellent choices: + + +
+
+
+
+
+
+
+
+
+
+
+
+ Blazingly fast thanks to its constituents:
+
+ * Rust: one of the lowest overhead languages,
+ * Axum: one of the fastest HTTP servers,
+ * SQLite/Libsql: one of the fastest full-SQL databases.
+
+ TrailBase is [6-7x faster than PocketBase and 15x faster than SupaBase
+ needing only a fraction of the footprint](/reference/benchmarks), allowing
+ you to serve millions of customers from a tiny box.
+
+
+
+ TrailBase is a small, single file, static binary that is incredibly easy
+ to deploy **consistently** across integration testing, development, pre-prod,
+ and production environments including edge.
+ Architecturally, TrailBase aims to be a simple, thin abstraction around
+ standards helping full or piece-meal adoption and avoiding lock-in.
+
+ A simple architecture, both in your dependencies and your own App, will
+ let you move faster, more confidently and pivot when necessary.
+
+
+
+ TrailBase ships with a builtin admin dashboard UI, see demo above, that
+ lets you quickly configure your instance and visually explore your data.
+ Following TrailBase's mantra of not getting in your way, the UI is
+ entirely optional letting you fall back to a purely config &
+ migration-based setup for integration tests or managing an entire fleet
+ of deployments.
+
+
+
+ TrailBase comes with an authentication system and UI built-in supporting
+ both password-based and Social/OAuth (Google, Discord, ...) sign-ups.
+
+ TrailBase authentication system follows standards and best-practices
+ combining short-lived, stateless JSON web tokens with long-lived stateful
+ refresh tokens letting you easily and efficiently authenticate your users
+ from any of your other back-ends relying on safe, asymmetric cryptography.
+
+
+
+ Provide access to your tables and views through fast, flexible and
+ **type-safe** restful CRUD APIs.
+ Authorize users based on ACLs and SQL access rules letting you
+ easily build higher-level access management or moderation facilities
+ like groups or capabilities.
+
+
+
+ Straightforward integration with any stack thanks to thin abstractions,
+ reliance on standards, and JSON Schema for type-safety allowing type-safe
+ bindings for virtually any language.
+
+ Clients as well as code-generation examples for TypeScript and
+ Dart/Flutter are provided out of the box.
+
+
+
+
+
+
+import Roadmap from "./_roadmap.md";
+
+
+
+
+
+
+
+{/* Hero page footer */}
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/src/content/docs/license.mdx b/docs/src/content/docs/license.mdx
new file mode 100644
index 0000000..3d6f5f6
--- /dev/null
+++ b/docs/src/content/docs/license.mdx
@@ -0,0 +1,108 @@
+---
+title: Functional Source License, Version 1.1, Apache 2.0 Future License
+template: splash
+---
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2024 Sebastian Jeltsch
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+ that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+ using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
diff --git a/docs/src/content/docs/reference/_benchmarks/benchmarks.tsx b/docs/src/content/docs/reference/_benchmarks/benchmarks.tsx
new file mode 100644
index 0000000..7b9621d
--- /dev/null
+++ b/docs/src/content/docs/reference/_benchmarks/benchmarks.tsx
@@ -0,0 +1,378 @@
+import { type ChartData, type ChartDataset, type Tick } from "chart.js/auto";
+
+import { BarChart } from "@/components/BarChart.tsx";
+import { LineChart } from "@/components/LineChart.tsx";
+
+import { data as supabaseUtilization } from "./supabase_utilization";
+import { data as pocketbaseUtilization } from "./pocketbase_utilization";
+import { data as trailbaseUtilization } from "./trailbase_utilization";
+
+const colors = {
+ supabase: "rgb(62, 207, 142)",
+ pocketbase0: "rgb(230, 128, 30)",
+ pocketbase1: "rgb(238, 175, 72)",
+ trailbase0: "rgb(0, 115, 170)",
+ trailbase1: "rgb(71, 161, 205)",
+ trailbase2: "rgb(146, 209, 242)",
+ drizzle: "rgb(249, 39, 100)",
+};
+
+function transformTimeTicks(factor: number = 0.5) {
+ return (_value: number | string, index: number): string | undefined => {
+ if (index % 10 === 0) {
+ // WARN: These are estimate time due to how we measure: periodic
+ // polling every 0.5s using `top` or `docker stats`, which themselves
+ // have sampling intervals. The actual value shouldn't matter that
+ // much, since we measure the actual duration in-situ. We do this
+ // transformation only to make the time scale more intuitive than
+ // just "time at sample X".
+ return `~${index * factor}s`;
+ }
+ };
+}
+
+const durations100k = [
+ {
+ label: "SupaBase",
+ data: [151],
+ backgroundColor: colors.supabase,
+ },
+ {
+ label: "PocketBase TS",
+ data: [67.721],
+ backgroundColor: colors.pocketbase0,
+ },
+ // {
+ // label: "PocketBase Dart (AOT)",
+ // data: [62.8136],
+ // },
+ {
+ label: "PocketBase Dart (JIT)",
+ data: [61.687],
+ backgroundColor: colors.pocketbase1,
+ },
+ {
+ label: "TrailBase TS",
+ data: [16.742],
+ backgroundColor: colors.trailbase0,
+ },
+ // {
+ // label: "TrailBase Dart (AOT)",
+ // data: [11.1],
+ // },
+ {
+ // label: "TrailBase Dart (JIT)",
+ label: "TrailBase Dart",
+ data: [9.4247],
+ backgroundColor: colors.trailbase1,
+ },
+ // {
+ // label: "TrailBase Dart (JIT + PGO)",
+ // data: [10.05],
+ // },
+ // {
+ // label: "TrailBase Dart (INT PK)",
+ // data: [8.5249],
+ // backgroundColor: colors.trailbase2,
+ // },
+ {
+ label: "In-process SQLite (Drizzle)",
+ data: [8.803],
+ backgroundColor: colors.drizzle,
+ },
+];
+
+export function Duration100kInsertsChart() {
+ const data: ChartData<"bar"> = {
+ labels: ["Time [s] (lower is better)"],
+ datasets: durations100k as ChartDataset<"bar">[],
+ };
+
+ return
+
+ Contact
+
+
+ License
+
+
+
+
+
+The graph shows the overall time it takes to insert 100k messages into a mock
+"chat-room" table setup. Less time is better.
+
+Unsurprisingly, in-process SQLite is the quickest [^2].
+All other setups add additional table look-ups for access checking, IPC
+overhead[^3], and layers of features on top.
+Maybe think of this data point as an upper bound to how fast SQLite could go
+and the cost a project would pay by adopting any of the systems over in-process
+SQLite.
+
+The data suggests that depending on your setup (client, data, hardware)
+TrailBase can insert 100k records 9 to 16 times faster than SupaBase[^4] and
+roughly 6 to 7 times faster than PocketBase [^1].
+The fact that our TS/node.js benchmark is slower than the Dart one, suggests a
+client-side bottleneck that could be overcome by tuning the setup or trying
+other JS runtimes with lower overhead HTTP clients.
+
+Total time of inserting a large batch of data tells only part of the story,
+let's have a quick look at resource consumption to get an intuition for
+provisioning or footprint requirements:
+
+_TrailBase & PocketBase Utilization_
+
+
+
+
+
+
+The graph shows the CPU utilization and memory consumption (RSS) of both
+PocketBase and TrailBase. They look fairly similar apart from TrailBase
+finishing earlier. They both load roughly 3 CPUs with PocketBase's CPU
+consumption being slightly more variable [^5].
+The little bump after the TrailBase run is likely due to SQLite check-pointing.
+
+Both only consume about 140MB of memory at full tilt, which makes them a great
+choice for running on a tiny VPS or a toaster.
+
+SupaBase is a bit more involved due to it's
+[layered architecture](https://supabase.com/docs/guides/getting-started/architecture)
+including a dozen separate services that provide a ton of extra functionality:
+
+_SupaBase Memory Usage_
+
+
+
+
+
+
+Looking at SupaBase's memory usage, it increased from from roughly 6GB at rest to
+7GB fully loaded.
+This means that out of the box, SupaBase has roughly 50 times the memory
+footprint of either PocketBase or TrailBase.
+In all fairness, there's a lot of extra functionality and it might be possible
+to further optimize the setup by shedding some less critical services, e.g.
+removing "supabase-analytics" may safe ~40% of memory. That said, we don't know
+how feasible this is in practice.
+
+_SupaBase CPU utilization_
+
+
+
+
+
+
+Looking at the CPU usage You can see how the CPU usage jumps up to roughly 9
+cores (the benchmark ran on a machine with 8 physical cores and 16 threads:
+7840U). Most of the CPUs seem to be consumed by "supabase-rest" with postgres
+itself hovering at only ~0.7.
+
+## Latency and Read Performance
+
+In this chapter we'll take a closer look at latency distributions. To keep
+things manageable we'll focus on PocketBase and TrailBase, which are
+architecturally simpler and more comparable.
+
+Reads were on average 3.5 faster with TrailBase and insertions 6x as discussed
+above.
+
+
+
+
+
+
+Looking at the latency distributions we can see that the spread is well
+contained for TrailBase. For PocketBase, read latencies are also generally well
+contained and predictable.
+However, insert latencies show a more significant "long tail" with their p90
+being roughly 5x longer than therr p50.
+Slower insertions can take north of 100ms. There may or may not be a connection
+to the variability in CPU utilization we've seen above.
+
+## Final Words
+
+We're very happy to confirm that TrailBase is quick. The significant
+performance gap we observed might just be a consequence of how much overhead
+matters given how quick SQLite itself is.
+Yet, it challenges our intuition. With the numbers fresh of the press, prudence is
+of the essence. We'd like to re-emphasize how important it is to run your own
+tests with your specific setup and workloads.
+In any case, we hope this was interesting nonetheless and let us know if you
+see anything that can or should be improved.
+The benchmarks are available on [GitHub](https://github.com/trailbaseio/trailbase-benchmark).
+
+
+
+---
+
+[^1]:
+ Trying to give PocketBase the best chance, the binary was built with the
+ latest go compiler (v1.23.1 at the time of writing), `CGO_ENABLED=1` (which
+ according to PB's own documentation will use a faster C-based SQLite
+ driver) and `GOAMD64=v4` (for less portable but more aggressive CPU
+ optimizations).
+ We found this setup to be roughly 20% faster than the static, pre-built
+ binary release.
+
+[^2]:
+ Our setup with drizzle and node.js is certainly not the fastest possible.
+ For example, we could drop down to using raw SQLite in C or another
+ low-level language.
+ That said, drizzle is a great popular choice which mostly serves as a
+ point-of-reference and sanity check.
+
+[^3]:
+ The actual magnitude on IPC overhead will depend on the communication cost.
+ For the benchmarks at hand we're using a loopback network device.
+
+[^4]:
+ The SupaBase benchmark setup skips row-level access checks. Technically,
+ this is in its favor from a performance standpoint, however looking at the
+ overall load on its constituents with PG being only a sliver, it probably
+ would not make much of an overall difference nor would PG17's vectorization,
+ which has been released since the benchmarks were run. That said, these
+ claims deserve re-validation.
+
+[^5]:
+ We're unsure as to what causes these 1-core swings.
+ Runtime-effects, such as garbage collection, may have an effect, however we
+ would have expected these to show on shorter time-scales.
+ This could also indicate a contention or thrashing issue 🤷.
diff --git a/docs/src/content/docs/reference/faq.mdx b/docs/src/content/docs/reference/faq.mdx
new file mode 100644
index 0000000..c5748b7
--- /dev/null
+++ b/docs/src/content/docs/reference/faq.mdx
@@ -0,0 +1,107 @@
+---
+title: FAQ
+description: Frequently Asked Questions
+---
+
+## How is TrailBase different from PocketBase, SupaBase or other application bases?
+
+Naturally there's a lot of overlap but let's start by saying that
+we're also huge fans of SupaBase and PocketBase.
+The former is incredibly versatile, while the latter is incredibly easy and
+cheap to use.
+As far as we can tell, PocketBase pioneered the notion of a single-file,
+SQLite-based, FireBase-like server.
+
+TrailBase is an attempt at combining the flexibility and principled
+architecture of SupaBase with the ease and low-overhead of PocketBase.
+We owe a great debt of gratitude to both ❤️.
+
+Let's address the elephant in the room: other more established solutions are
+more polished, may have more extensive feature sets in many areas, and have
+seen a lot more mileage.
+TrailBase is committed to catch up and challenge the status quo following our
+[principles](/getting-started/philosophy) and in many ways, TrailBase is
+already incredibly easy to deploy and [blazingly fast](/reference/benchmarks).
+
+We also offer some slightly more detailed comparisons to both
+[PocketBase](/comparison/pocketbase) and [SupaBase](/comparison/supabase).
+
+## Is TrailBase ready for production use?
+
+TrailBase has not seen a lot of mileage yet and there's probably plenty of
+sharp edges, which will take some time to smooth over.
+That said, it's also incredibly simple, easy to get on, and easy to get off.
+We're welcoming any brave soul who would like to be an early adopter.
+If you're curious and patient, we're ready to help you get off the ground in
+return for your honest feedback 🙏.
+You can take a look at the preliminary
+[productionization](/documentation/production).
+
+## Scale, performance and reliability
+
+As my product grows, will TrailBase scale with me or will I hit a wall?
+Firstly, congratulations! The "success"-problem is a great problem to have 🎉.
+
+Short, hand-wavy answer: you'll face all the same issues as with other
+solutions but you probably will be fine 😶🌫️ .
+
+Long answer: TrailBase currently only scales vertically, however it's incredibly
+fast. Besides, there's an inherent beauty to vertical scaling [^1] and modern
+servers can get you very very far.
+You can absolutely support tens of thousands or even hundreds thousands of
+concurrent users with a single database.
+With TrailBase simple deployment, it may also be an option to shard your users
+or tenants across multiple databases. In the future, TrailBase would also like
+to support multi-database setups out-of-the-box to further improve concurrency.
+
+Keep in mind that other databases, like MySQL or Postgres, aren't a silver bullet either.
+If you're reaching massive levels of scale, more specialized solutions will
+become more and more attractive such as non-relational document stores,
+columnar OLAP stores for analytic workloads, ...
+
+TrailBase explicitly tries to avoid tight coupling locking you in. At the end
+of the day, you're using very plain SQLite, letting you adopt and drop
+TrailBase when it makes sense.
+Similarly, the stateless auth flow makes it easy to split out your logic and
+data while continuing to use TrailBase.
+
+Besides pure scale and performance, many more horizontal solutions provide
+additional benefits such as disaster-recovery/fail-over or improved edge read
+latency.
+Fortunately, both can be achieved with SQLite as well using solutions like
+[LiteStream](https://litestream.io/) keeping eventually consistent copies of
+your data.
+
+## Can we add Features to TrailBase?
+
+Yes! First take a look at our coarse [roadmap](/reference/roadmap), maybe we're
+already working on it?
+Otherwise, don't hesitate, just open an issue and ask away. We love to hear
+your thoughts.
+Contributions are also very welcome, let's just talk upfront to avoid any
+surprises.
+Especially, in the early days we'll have to see how "things" fit into the
+roadmap.
+For example, having a dark mode for the dashboard would be nice but it's also
+extra work to maintain while the dashboard is still rapidly changing, so it
+becomes a question of when.
+
+## Data Import & Export
+
+Few requirements: `STRICT` table and an auto-incrementing primary key for
+collections but the dashboard will work for any table, view, etc.
+You can simply import and export data with standard SQLite tooling, e.g.:
+
+```shell
+sqlite3 main.db < import.sql
+```
+
+Also check out the [getting started](/getting-started/first-app) guide.
+
+
+
+---
+
+[^1]:
+ Adopting more complex multi-tiered database solutions comes with its own
+ challenges for operations, testing, and developer setups.
diff --git a/docs/src/content/docs/reference/roadmap.mdx b/docs/src/content/docs/reference/roadmap.mdx
new file mode 100644
index 0000000..4587f25
--- /dev/null
+++ b/docs/src/content/docs/reference/roadmap.mdx
@@ -0,0 +1,7 @@
+---
+title: Roadmap
+---
+
+import Roadmap from "../_roadmap.md";
+
+
+
+
+
+
+Authentication is complete. If this does not happen automatically, please close the window.
+ + diff --git a/examples/blog/flutter/web/favicon.png b/examples/blog/flutter/web/favicon.png new file mode 100644 index 0000000..8aaa46a Binary files /dev/null and b/examples/blog/flutter/web/favicon.png differ diff --git a/examples/blog/flutter/web/icons/Icon-192.png b/examples/blog/flutter/web/icons/Icon-192.png new file mode 100644 index 0000000..b749bfe Binary files /dev/null and b/examples/blog/flutter/web/icons/Icon-192.png differ diff --git a/examples/blog/flutter/web/icons/Icon-512.png b/examples/blog/flutter/web/icons/Icon-512.png new file mode 100644 index 0000000..88cfd48 Binary files /dev/null and b/examples/blog/flutter/web/icons/Icon-512.png differ diff --git a/examples/blog/flutter/web/icons/Icon-maskable-192.png b/examples/blog/flutter/web/icons/Icon-maskable-192.png new file mode 100644 index 0000000..eb9b4d7 Binary files /dev/null and b/examples/blog/flutter/web/icons/Icon-maskable-192.png differ diff --git a/examples/blog/flutter/web/icons/Icon-maskable-512.png b/examples/blog/flutter/web/icons/Icon-maskable-512.png new file mode 100644 index 0000000..d69c566 Binary files /dev/null and b/examples/blog/flutter/web/icons/Icon-maskable-512.png differ diff --git a/examples/blog/flutter/web/index.html b/examples/blog/flutter/web/index.html new file mode 100644 index 0000000..f010497 --- /dev/null +++ b/examples/blog/flutter/web/index.html @@ -0,0 +1,38 @@ + + + + +
+ t.trim())}>
+ {(tag) => {tag}}
+
+
+ );
+}
+
+export function ComposeArticleButton() {
+ const profile = useStore($profile);
+
+ return (
+
+
+ );
+}
+
+export function ArticleList() {
+ const client = useStore($client);
+ const [articles] = createResource(client, (client) =>
+ client?.records("articles_view").listPick a unique username:
+ +
+ setUsername(e.currentTarget.value)}
+ />
+
+
+
+
+ {error() !== undefined && (
+ {`${error()}`}
+ )}
+
+
+
+ + {article().title} +
+ +
+
{article().body}
+
+
+
+
+
+ !})
+
+
+
+ {profile()?.profile?.username ?? props.user?.email}
+
+
+
+
diff --git a/examples/blog/web/src/components/general/HamburgerButton.astro b/examples/blog/web/src/components/general/HamburgerButton.astro
new file mode 100644
index 0000000..2079bcd
--- /dev/null
+++ b/examples/blog/web/src/components/general/HamburgerButton.astro
@@ -0,0 +1,32 @@
+---
+import { Icon } from "astro-icon/components";
+
+const style =
+ "size-8 h-auto text-pacamara-secondary transition-all duration-300 hover:text-pacamara-accent dark:text-white dark:hover:text-pacamara-accent";
+---
+
+
+
+
diff --git a/examples/blog/web/src/components/general/Header.astro b/examples/blog/web/src/components/general/Header.astro
new file mode 100644
index 0000000..bfef740
--- /dev/null
+++ b/examples/blog/web/src/components/general/Header.astro
@@ -0,0 +1,37 @@
+---
+import HamburgerButton from "./HamburgerButton.astro";
+import ModeSwitch from "./ModeSwitch.astro";
+import Navigation from "./Navigation.astro";
+
+import { AuthButton } from "@/components/Auth";
+import { ComposeArticleButton } from "@/components/Articles";
+
+const headerStyle =
+ "container mx-auto max-w-screen-xl px-7 py-10 bg-white flex flex-initial flex-row gap-10 items-center justify-between transition-all duration-300 dark:bg-pacamara-dark relative z-20";
+const logoStyle =
+ "font-bold font-pacamara-space text-lg hover:text-pacamara-accent transition-all duration-300 dark:text-white dark:hover:text-pacamara-accent";
+---
+
+
+
+
+ TrailBase
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/examples/blog/web/src/lib/client.ts b/examples/blog/web/src/lib/client.ts
new file mode 100644
index 0000000..220ac84
--- /dev/null
+++ b/examples/blog/web/src/lib/client.ts
@@ -0,0 +1,40 @@
+import { atom, computed, task } from "nanostores";
+import { persistentAtom } from "@nanostores/persistent";
+import { Client, type Tokens, type User } from "trailbase";
+
+export const HOST = import.meta.env.DEV ? "http://localhost:4000" : "";
+
+const $tokens = persistentAtom
+
+
diff --git a/examples/blog/web/src/pages/index.astro b/examples/blog/web/src/pages/index.astro
new file mode 100644
index 0000000..29e7a93
--- /dev/null
+++ b/examples/blog/web/src/pages/index.astro
@@ -0,0 +1,10 @@
+---
+import Base from "@/layouts/Base.astro";
+import { ArticleList } from "@/components/Articles";
+---
+
+Compose
+ + +Hello, {}!
", + user.map_or("World".to_string(), |user| user.email) + )) + .into_response() +} + +#[tokio::main] +async fn main() -> Result<(), BoxError> { + env_logger::init_from_env( + env_logger::Env::new().default_filter_or("info,trailbase_core=debug,refinery_core=warn"), + ); + + let custom_routes: Router