From e97a7a34da9e9712e11e42c0466b5193af0f2f7d Mon Sep 17 00:00:00 2001 From: richvdh Date: Tue, 25 Jan 2022 14:11:45 +0000 Subject: deploy: fc8598bc87d5bcc7e8526492f309e73c8dcff3f6 --- develop/development/database_schema.html | 41 ++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'develop/development/database_schema.html') diff --git a/develop/development/database_schema.html b/develop/development/database_schema.html index bf9ebc0566..024e37eb1f 100644 --- a/develop/development/database_schema.html +++ b/develop/development/database_schema.html @@ -267,6 +267,47 @@ has had all background updates run.

NB at the time of writing, this script predates the split into separate state/main databases so will require updates to handle that correctly.

+

Delta files

+

Delta files define the steps required to upgrade the database from an earlier version. +They can be written as either a file containing a series of SQL statements, or a Python +module.

+

Synapse remembers which delta files it has applied to a database (they are stored in the +applied_schema_deltas table) and will not re-apply them (even if a given file is +subsequently updated).

+

Delta files should be placed in a directory named synapse/storage/schema/<database>/delta/<version>/. +They are applied in alphanumeric order, so by convention the first two characters +of the filename should be an integer such as 01, to put the file in the right order.

+

SQL delta files

+

These should be named *.sql, or — for changes which should only be applied for a +given database engine — *.sql.posgres or *.sql.sqlite. For example, a delta which +adds a new column to the foo table might be called 01add_bar_to_foo.sql.

+

Note that our SQL parser is a bit simple - it understands comments (-- and /*...*/), +but complex statements which require a ; in the middle of them (such as CREATE TRIGGER) are beyond it and you'll have to use a Python delta file.

+

Python delta files

+

For more flexibility, a delta file can take the form of a python module. These should +be named *.py. Note that database-engine-specific modules are not supported here – +instead you can write if isinstance(database_engine, PostgresEngine) or similar.

+

A Python delta module should define either or both of the following functions:

+
import synapse.config.homeserver
+import synapse.storage.engines
+import synapse.storage.types
+
+
+def run_create(
+    cur: synapse.storage.types.Cursor,
+    database_engine: synapse.storage.engines.BaseDatabaseEngine,
+) -> None:
+    """Called whenever an existing or new database is to be upgraded"""
+    ...
+
+def run_upgrade(
+    cur: synapse.storage.types.Cursor,
+    database_engine: synapse.storage.engines.BaseDatabaseEngine,
+    config: synapse.config.homeserver.HomeServerConfig,
+) -> None:
+    """Called whenever an existing database is to be upgraded."""
+    ...
+

Boolean columns

Boolean columns require special treatment, since SQLite treats booleans the same as integers.

-- cgit 1.5.1