Revise Evolu migrations documentation for clarity

Author: steida

apps/web/src/app/(docs)/docs/migrations/page.mdx

@@ -3,101 +3,65 @@ export const metadata = {
   description: "How to handle migrations in Evolu apps.",
 };
 
-<Warn>
-  This doc is from an earlier version of Evolu. While some concepts still apply,
-  others may have changed — double-check with the latest source or tests.
-</Warn>
-
-<Warn>
-  This is still valid except that the outdated version can't accept new data
-  anymore, as it uses the Evolu schema for validation.
-</Warn>
-
 # Migrations
 
-Traditional server-based databases are versioned and updated using migration scripts. However, this approach isn't practical for local-first databases that replicate across devices. Evolu apps must be capable of handling both existing data and data created in the future—even by newer app versions.
-
-That means even an outdated version of an Evolu app needs to work seamlessly with data generated by a more recent version. Fortunately, Evolu handles this automatically with just two simple rules.
+Traditional centralized databases are versioned and updated using migration scripts. However, this approach isn't practical for local-first databases. Migration scripts can be slow when processing large amounts of local data, and if a migration fails, there's no centralized database to fix—each failed instance would need to be repaired individually.
 
-<Note>
-  Evolu embraces a schemaless design, similar to [best
-  practices](https://graphql.org/learn/best-practices/#versioning), but with a
-  few key improvements. Since Evolu relay is completely generic—it has no
-  knowledge of any specific Evolu app schemas—and the database is local, we can
-  do more. Evolu can automatically filter rows with nullable columns and narrow
-  their types, so developers don't have to manually handle nullable values in
-  their code.
-</Note>
+For these reasons, Evolu embraces a version-less append-only schema—the same pattern as [GraphQL schema design](https://graphql.org/learn/schema-design/). Facebook adopted this pattern to maintain a single endpoint for countless clients, including those that had not been updated for years. Evolu applies this principle to local-first databases, ensuring compatibility across all versions.
 
 ## Append only schema
 
-The first and most important rule is the append-only schema.
-
-Once an app is released, the existing database schema must remain unchanged. That means:
+Once an Evolu app is released, the existing database schema must remain unchanged. That means:
 
 - **No renaming tables**
 - **No renaming columns**
 - **No changing column types**
 
-Why? Because there's always a chance that some data has already been created using the old structure. Changing it would break compatibility.
-
-Instead, the solution is simple: just stop using outdated tables or columns in new mutations. They can remain in the schema for backward compatibility, and that's perfectly fine.
+This is important because there's always a chance that some data has already been created using the previous schema. Changing it would break compatibility.
 
-## Nullability
-
-While we _can_ and _should_ define non-nullable column types—enforced during mutations—all columns (except for `id`) are treated as nullable in queries.
-
-Why? Because Evolu apps must handle all data gracefully, regardless of when or where it was created.
+Instead of migrations, simply add new tables and columns to the existing schema. Newer app code must keep already existing tables and columns in the schema (don't delete them) and continue using them when receiving data from previous app versions. For example, if you replace a string `address` column with an `addressId` column (because we have a new address table), the app should use `addressId` when present, and fall back to `address` when it's not.
 
-Take this example: you replace an `address` column with a new `addressId` column (as a foreign key). What happens when an outdated app receives data using the new structure? It doesn't know what to do with `addressId`—it has no logic for it yet.
+This append-only approach raises an important question: if new tables and columns can be added over time and obsolete ones can stop being used at all, how should Evolu apps handle that? The answer is another [GraphQL schema design](https://graphql.org/learn/schema-design/) pattern—nullability.
 
-The app should still store the data but simply ignore fields it doesn't understand until it's updated. That's exactly how Evolu works.
+## Nullability
 
-Evolu updates the underlying SQLite database on the fly. By treating all columns as nullable in queries, it ensures developers explicitly filter and work only with the data their app version can safely handle.
+To understand how Evolu handles nullability, let's look at a simple schema:
 
-Take a look at this schema, mutation, and query.
+```ts {{ title: 'schema.ts' }}
+const TodoId = id("Todo");
 
-```ts {{ title: 'Basic Evolu schema and create mutation' }}
-const TodoTable = {
-  id: TodoId,
-  // The title is not nullable.
-  title: NonEmptyString1000,
+const Schema = {
+  todo: {
+    id: TodoId,
+    title: NonEmptyString100,
+    isCompleted: nullOr(SqliteBoolean),
+  },
 };
+```
 
-// Mutations enforce required columns.
-evolu.insert("todo", { title });
+In this schema, `id` and `title` columns are not nullable, while `isCompleted` is nullable (it may have been added later, or it's just not required when a new todo is inserted).
 
-// But in queries, all columns (except for `id`) are nullable
-// until we explicitly filter and narrow them.
-const allTodos = evolu.createQuery((db) =>
+However, even though `title` is not nullable—which is enforced in mutations—Evolu treats it as nullable when writing queries. This forces developers to explicitly define the shape they want.
+
+```ts {{ title: 'query.ts' }}
+// Evolu uses Kysely for type-safe SQL (https://kysely.dev/).
+const todosQuery = evolu.createQuery((db) =>
   db
+    // Type-safe SQL: try autocomplete for table and column names.
     .selectFrom("todo")
-    .selectAll()
-    // Filter null value and ensure non-null type.
+    .select(["id", "title", "isCompleted"])
+    // Soft delete: filter out deleted rows.
+    .where("isDeleted", "is not", sqliteTrue)
+    // Like with GraphQL, all columns except id are nullable in queries
+    // (even if defined without nullOr in the schema) to allow schema
+    // evolution without migrations. Filter nulls with where + $narrowType.
     .where("title", "is not", null)
     .$narrowType<{ title: kysely.NotNull }>()
+    // Columns createdAt, updatedAt, isDeleted are auto-added to all tables.
     .orderBy("createdAt"),
 );
 ```
 
-Now, what if we decide we no longer want to use the `title` column?
-
-We simply stop using it in new mutations and mark it as nullable. But since there's a chance the column has already been used in existing data, we **must still support it in queries**.
-
-This means the app should continue to query the `title` column but treat it as optional. Older versions of the app may still rely on it, and newer versions should gracefully ignore it unless needed.
-
-In short: make it nullable, stop writing to it, but keep reading from it—for compatibility.
-
-```ts
-type TitleOrContent =
-  | { _tag: "title"; value: NonEmptyString1000 }
-  | { _tag: "content"; value: RichTextMax10k };
-```
-
-Such a DSL for ad-hoc migrations isn't available yet—but thanks to the flexibility of [Kysely](https://kysely.dev/) and SQLite, it's absolutely possible. We plan to build it soon.
-
-### One last question
-
-Since `RichTextMax10k` can be a JSON object, should we version it?
+This approach ensures data integrity even when CRDT messages arrive out of order. For example, a message deleting a todo might arrive before the message creating it. By explicitly filtering for the shape the current app expects, only valid rows—or rows the current version of the app can handle—are selected from the database.
 
-**Yes.** While it's possible to version via the column name (e.g., `content2`, `content3`), `RichTextMax10k` might be reused in multiple places across the database schema. In that case, it's better to include the versioning _inside_ the `RichTextMax10k` type itself, making the structure more explicit and future-proof.
+Just like schemas, queries must be append-only as well. If we stop querying obsolete columns or tables, older data using those columns will suddenly disappear from the results.