Add various doc updates

They are still very far from complete.
This commit is contained in:
2026-01-25 12:11:34 -06:00
parent 4f37a72d7b
commit 421628d49e
9 changed files with 613 additions and 1 deletions

View File

@@ -0,0 +1,34 @@
Some database tables are owned by diachron and some are owned by the
application.
This also applies to seeders: some are owned by diachron and some by the
application.
The database's structure is managed by migrations written in SQL.
Each migration gets its own file. These files' names should match
`yyyy-mm-dd_ss-description.sql`, eg `2026-01-01_01-users.sql`.
Files are sorted lexicographically by name and applied in order.
Note: in the future we may relax or modify the restriction on migration file
names, but they'll continue to be applied in lexicographical order.
## framework and application migrations
Migrations owned by the framework are kept in a separate directory from those
owned by applications. Pending framework migrations, if any, are applied
before pending application migrations, if any.
diachron will go to some lengths to ensure that framework migrations do not
break applications.
## no downward migrations
diachron does not provide them. "The only way out is through."
When developing locally, you can use the command `develop reset-db`. **NEVER
USE THIS IN PRODUCTION!** Always be sure that you can "get back to where you
were". Being careful when creating migrations and seeders can help, but
dumping and restoring known-good copies of the database can also take you a
long way.