mirror of
https://github.com/element-hq/synapse.git
synced 2026-10-23 19:33:44 +00:00
deploy: c1b9922498
This commit is contained in:
richvdh committed
1 parent
c9d08384f3
commit
c380a43a42
67 files changed
+495
-70
No files matched your search
+86
-1
@@ -101,7 +101,7 @@
|
||||
|
||||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||||
<div class="sidebar-scrollbox">
|
||||
<ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrading/index.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><div>Pluggable Modules</div></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></Line truncated
|
||||
<ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html">Configuring a Turn Server</a></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrading/index.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="url_previews.html">URL Previews</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><div>Pluggable Modules</div></li><li><ol class="section"><li class="chapter-item expanded "><div>Third Party Rules</div></li><li class="chapter-item expanded "><a href="spam_checker.html">Spam Checker</a></li><li class="chapter-item expanded "><a href="presence_router_module.html">Presence Router</a></li><li class="chapter-item expanded "><div>Media Storage Providers</div></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="admin_api/delete_group.html">Delete Group</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/purge_room.html">Purge Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></Line truncated
|
||||
</div>
|
||||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||||
</nav>
|
||||
@@ -11380,6 +11380,91 @@ logged to OpenTracing's logs.</li>
|
||||
<h2 id="configuring-jaeger"><a class="header" href="#configuring-jaeger">Configuring Jaeger</a></h2>
|
||||
<p>Sampling strategies can be set as in this document:
|
||||
<a href="https://www.jaegertracing.io/docs/latest/sampling/">https://www.jaegertracing.io/docs/latest/sampling/</a>.</p>
|
||||
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="synapse-database-schema-files"><a class="header" href="#synapse-database-schema-files">Synapse database schema files</a></h1>
|
||||
<p>Synapse's database schema is stored in the <code>synapse.storage.schema</code> module.</p>
|
||||
<h2 id="logical-databases"><a class="header" href="#logical-databases">Logical databases</a></h2>
|
||||
<p>Synapse supports splitting its datastore across multiple physical databases (which can
|
||||
be useful for large installations), and the schema files are therefore split according
|
||||
to the logical database they apply to.</p>
|
||||
<p>At the time of writing, the following "logical" databases are supported:</p>
|
||||
<ul>
|
||||
<li><code>state</code> - used to store Matrix room state (more specifically, <code>state_groups</code>,
|
||||
their relationships and contents).</li>
|
||||
<li><code>main</code> - stores everything else.</li>
|
||||
</ul>
|
||||
<p>Additionally, the <code>common</code> directory contains schema files for tables which must be
|
||||
present on <em>all</em> physical databases.</p>
|
||||
<h2 id="synapse-schema-versions"><a class="header" href="#synapse-schema-versions">Synapse schema versions</a></h2>
|
||||
<p>Synapse manages its database schema via "schema versions". These are mainly used to
|
||||
help avoid confusion if the Synapse codebase is rolled back after the database is
|
||||
updated. They work as follows:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<p>The Synapse codebase defines a constant <code>synapse.storage.schema.SCHEMA_VERSION</code>
|
||||
which represents the expectations made about the database by that version. For
|
||||
example, as of Synapse v1.36, this is <code>59</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>The database stores a "compatibility version" in
|
||||
<code>schema_compat_version.compat_version</code> which defines the <code>SCHEMA_VERSION</code> of the
|
||||
oldest version of Synapse which will work with the database. On startup, if
|
||||
<code>compat_version</code> is found to be newer than <code>SCHEMA_VERSION</code>, Synapse will refuse to
|
||||
start.</p>
|
||||
<p>Synapse automatically updates this field from
|
||||
<code>synapse.storage.schema.SCHEMA_COMPAT_VERSION</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Whenever a backwards-incompatible change is made to the database format (normally
|
||||
via a <code>delta</code> file), <code>synapse.storage.schema.SCHEMA_COMPAT_VERSION</code> is also updated
|
||||
so that administrators can not accidentally roll back to a too-old version of Synapse.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Generally, the goal is to maintain compatibility with at least one or two previous
|
||||
releases of Synapse, so any substantial change tends to require multiple releases and a
|
||||
bit of forward-planning to get right.</p>
|
||||
<p>As a worked example: we want to remove the <code>room_stats_historical</code> table. Here is how it
|
||||
might pan out.</p>
|
||||
<ol>
|
||||
<li>
|
||||
<p>Replace any code that <em>reads</em> from <code>room_stats_historical</code> with alternative
|
||||
implementations, but keep writing to it in case of rollback to an earlier version.
|
||||
Also, increase <code>synapse.storage.schema.SCHEMA_VERSION</code>. In this
|
||||
instance, there is no existing code which reads from <code>room_stats_historical</code>, so
|
||||
our starting point is:</p>
|
||||
<p>v1.36.0: <code>SCHEMA_VERSION=59</code>, <code>SCHEMA_COMPAT_VERSION=59</code></p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Next (say in Synapse v1.37.0): remove the code that <em>writes</em> to
|
||||
<code>room_stats_historical</code>, but don’t yet remove the table in case of rollback to
|
||||
v1.36.0. Again, we increase <code>synapse.storage.schema.SCHEMA_VERSION</code>, but
|
||||
because we have not broken compatibility with v1.36, we do not yet update
|
||||
<code>SCHEMA_COMPAT_VERSION</code>. We now have:</p>
|
||||
<p>v1.37.0: <code>SCHEMA_VERSION=60</code>, <code>SCHEMA_COMPAT_VERSION=59</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Later (say in Synapse v1.38.0): we can remove the table altogether. This will
|
||||
break compatibility with v1.36.0, so we must update <code>SCHEMA_COMPAT_VERSION</code> accordingly.
|
||||
There is no need to update <code>synapse.storage.schema.SCHEMA_VERSION</code>, since there is no
|
||||
change to the Synapse codebase here. So we end up with:</p>
|
||||
<p>v1.38.0: <code>SCHEMA_VERSION=60</code>, <code>SCHEMA_COMPAT_VERSION=60</code>.</p>
|
||||
</li>
|
||||
</ol>
|
||||
<p>If in doubt about whether to update <code>SCHEMA_VERSION</code> or not, it is generally best to
|
||||
lean towards doing so.</p>
|
||||
<h2 id="full-schema-dumps"><a class="header" href="#full-schema-dumps">Full schema dumps</a></h2>
|
||||
<p>In the <code>full_schemas</code> directories, only the most recently-numbered snapshot is used
|
||||
(<code>54</code> at the time of writing). Older snapshots (eg, <code>16</code>) are present for historical
|
||||
reference only.</p>
|
||||
<h3 id="building-full-schema-dumps"><a class="header" href="#building-full-schema-dumps">Building full schema dumps</a></h3>
|
||||
<p>If you want to recreate these schemas, they need to be made from a database that
|
||||
has had all background updates run.</p>
|
||||
<p>To do so, use <code>scripts-dev/make_full_schema.sh</code>. This will produce new
|
||||
<code>full.sql.postgres</code> and <code>full.sql.sqlite</code> files.</p>
|
||||
<p>Ensure postgres is installed, then run:</p>
|
||||
<pre><code>./scripts-dev/make_full_schema.sh -p postgres_username -o output_dir/
|
||||
</code></pre>
|
||||
<p>NB at the time of writing, this script predates the split into separate <code>state</code>/<code>main</code>
|
||||
databases so will require updates to handle that correctly.</p>
|
||||
<div id="chapter_begin" style="break-before: page; page-break-before: always;"></div><h1 id="log-contexts"><a class="header" href="#log-contexts">Log Contexts</a></h1>
|
||||
<p>To help track the processing of individual requests, synapse uses a
|
||||
'<code>log context</code>' to track which request it is handling at any given
|
||||
|
||||
Reference in new issue
Block a user