Initial public release of Warp.

Repo-Sync-Origin: warpdotdev/warp-internal@12af1d983b
2026-04-28 08:43:33 -05:00
commit 0dbd3d567a
4982 changed files with 1431549 additions and 0 deletions
@@ -0,0 +1,60 @@
+# How to perform migrations
+
+## How do migrations work?
+A sqlite database is one single file on the user's computer, and instead of being a separate process, it's a set of C functions
+that are bundled in our app. When the warp app starts, we upgrade the schema to the latest version in a transaction.
+Since we don't control the machine, we need to be super careful about the migrations that we ship.
+
+TODO: C.I. and remediation of failed migrations
+
+## Step 1: One-time setup
+Make sure you have run `/script/bootstrap` at least once before. That installs our fork of
+`diesel_cli`. Our fork is an old version that [bundles](https://github.com/warpdotdev/diesel/blob/b2c58897c39c519a946314bd5b63765d3af56204/diesel_cli/Cargo.toml#L54)
+SQLite in with the `diesel_cli`. We use these version of Diesel and SQLite instead of relying on
+the versions on our machines. So do not follow the official Diesel CLI installation instructions.
+
+Additionally, the `sqlite3` binary is useful in development. The one on your Macbook is ok, but
+likely will be missing some basic language features. You can grab the latest binary from the
+official website https://www.sqlite.org/download.html. Note that we use SQL language features that
+are not available on old versions of sqlite. Note that you'll have to approve it to be run in your mac system preferences.
+
+## Step 2: Write the migration
+```
+diesel migration generate <descriptive name of your migration>
+```
+This will create a new folder with an up.sql and down.sql.
+
+## Step 3: Run the migration + generate the schema
+```
+cd <warp-internal repo>
+diesel migration run --database-url="/Users/$USER/Library/Application Support/dev.warp.Warp-Local/warp.sqlite"
+```
+This will run the migration on the same warp that runs when you run the app locally. This automatically generates or updates the `app/src/persistence/schema.rs`. We do not make manual edits to `schema.rs`.
+
+You can also print the schema from a database that already has the migration with:
+```
+diesel print-schema --database-url="/Users/$USER/Library/Application Support/dev.warp.Warp-Local/warp.sqlite"
+```
+
+## Reverting/redo-ing migrations
+As you are writing features and changing branches, you'll want to undo migrations to fix your database and make it compatible with older code. Redo-ing can also be helpful as you are iterating on your schema.
+```
+diesel migration revert --database-url="/Users/$USER/Library/Application Support/dev.warp.Warp-Local/warp.sqlite"
+diesel migration redo --database-url="/Users/$USER/Library/Application Support/dev.warp.Warp-Local/warp.sqlite"
+```
+
+# Schema style
+- We use `id` for integer primary keys. If there's something more special about the primary key, consider a more descriptive name.
+- Plural table names, singular for structs in the rust model code.
+- If there's a table `foos` and a table `bars`, and `bars` has a column with a foreign key that references `foos.id`, name it `foo_id`.
+
+# The `schema.patch` file
+The `app/src/persistence/schema.patch` is manually updated by us. This file lets us make manual
+changes on top of the auto-generated `schema.rs` file produced by `diesel_cli`.
+
+To create the `schema.patch` file, we:
+1. Run the diesel migrations
+1. Manually edit `schema.rs`
+1. Run `git diff -U6 > app/src/persistence/schema.patch`.
+
+You can read more about this patch file in the official [Diesel documentation](https://diesel.rs/guides/configuring-diesel-cli.html#the-patch_file-field).