diff --git a/docs/upgrading.md b/docs/upgrading.md
new file mode 100644
index 00000000..14103c8d
--- /dev/null
+++ b/docs/upgrading.md
@@ -0,0 +1,18 @@
+# Upgrading
+
+Tilde Friends can be upgraded simply by running a new executable against an
+existing database.
+
+Tilde Friends writes all data to a `db.sqlite` file, either in
+`~/.local/share/tildefriends/` or in the working directory where it is run,
+depending on the platform and whether each one already exists. Run with
+`tildefriends run -d DB_PATH` to specify the path to the database explicitly.
+
+This file can be copied and moved across machines as needed like any [sqlite3
+database](https://www.sqlite.org/onefile.html).
+
+Schema changes and compatibility breaks have been rare, by design. In general,
+upgrading is not expected to require any manual intervention and likely does
+not involve any automatic migration, either. Downgrading is not well-supported
+but will probably just work excepting rare changes that will be called out in
+the changelog.