Documentation for databases

docs/en/020_Installation/040_Database_Setup/000_SQLite.md

@@ -1,3 +1,16 @@
-SQLite requires very little setup. By default the database will be created at the root of The Arsse's program directory (e.g. `/usr/share/arsse/arsse.db`), but this can be changed with the [`dbSQLite3File` setting](/en/Configuring_The_Arsse#page_dbSQLite3File). 
+# About
 
-Regardless of the location chosen, The Arsse **must** be able to both read from and write to the database file, as well as create files in the directory containing it. This is because SQLite also creates a write-ahead log file and a shared-memory file during operation. 
+<dl>
+    <dt>Supported since</dt>
+        <dd>0.1.0</dd>
+    <dt>dbDriver identifier</dt>
+        <dd>sqlite3</dd>
+    <dt>Minimum version</dt>
+        <dd>3.8.3</dd>
+    <dt>Configuration</dt>
+        <dd><a href="/en/Configuring_The_Arsse#page_Database-settings">General</a>, <a href="/en/Configuring_The_Arsse#page_Database-settings-specific-to-SQLite-3">Specific</a></dd>
+</dl>
+
+SQLite requires very little set-up. By default the database will be created at the root of The Arsse's program directory (e.g. `/usr/share/arsse/arsse.db`), but this can be changed with the [`dbSQLite3File` setting](/en/Configuring_The_Arsse#page_dbSQLite3File). 
+
+Regardless of the location chosen, The Arsse **must** be able to both read from and write to the database file, as well as create files in its directory. This is because SQLite also creates a write-ahead log file and a shared-memory file during operation.

docs/en/020_Installation/040_Database_Setup/010_PostgreSQL.md

@@ -0,0 +1,37 @@
+# About
+
+<dl>
+    <dt>Supported since</dt>
+        <dd>0.6.0</dd>
+    <dt>dbDriver identifier</dt>
+        <dd>postgresql</dd>
+    <dt>Minimum version</dt>
+        <dd>10</dd>
+    <dt>Configuration</dt>
+        <dd><a href="/en/Configuring_The_Arsse#page_Database-settings">General</a>, <a href="/en/Configuring_The_Arsse#page_Database-settings-specific-to-PostgreSQL">Specific</a></dd>
+</dl>
+
+If for whatever reason an SQLite database does not suit your configuration, PostgreSQL is the best alternative. It is functionally equivalent to SQLite in every way.
+
+# Set-up
+
+In order to use a PostgreSQL database for The Arsse, the database must already exist. The procedure for doing for creating a database can differ between systems, but a typical Linux procedure is as follows:
+
+```sh
+sudo -u postgres psql -c "CREATE USER arsseuser WITH PASSWORD 'super secret password'"
+sudo -u postgres psql -c "CREATE DATABASE arssedb WITH OWNER arsseuser"
+```
+
+Tha Arsse must then be configured to use the create database. A suitable [configuration file](/en/Configuring_The_Arsse) might look like this:
+
+```php
+<?php
+return [
+    'dbDriver'         => "postgresql",
+    'dbPostgreSQLUser' => "arsseuser",
+    'dbPostgreSQLPass' => "super secret password",
+    'dbPostgreSQLDb'   => "arssedb",
+];
+```
+
+Numerous alternate configurations are possible; the above is merely the simplest.

docs/en/020_Installation/040_Database_Setup/020_MySQL.md

@@ -0,0 +1,40 @@
+# About
+
+<dl>
+    <dt>Supported since</dt>
+        <dd>0.6.0</dd>
+    <dt>dbDriver identifier</dt>
+        <dd>mysql</dd>
+    <dt>Minimum version</dt>
+        <dd>8.0.7</dd>
+    <dt>Configuration</dt>
+        <dd><a href="/en/Configuring_The_Arsse#page_Database-settings">General</a>, <a href="/en/Configuring_The_Arsse#page_Database-settings-specific-to-MySQL">Specific</a></dd>
+</dl>
+
+While MySQL can be used as a database for The Arsse, this is **not recommended** due to MySQL's technical limitations. It is fully functional, but may fail with some newsfeeds where other database systems do not. Additionally, it is important before upgrading from one version of The Arsse to the next to back up your database: a failure in a database upgrade can corrupt your database much more easily than when using alternative database systems.
+
+Please note that MariaDB cannot be used in place of MySQL as it lacks features of MySQL 8 which The Arsse requires.
+
+# Set-up
+
+In order to use a MySQL database for The Arsse, the database must already exist. The procedure for doing for creating a database can differ between systems, but a typical Linux procedure is as follows:
+
+```sh
+sudo mysql -e "CREATE USER 'arsseuser'@'localhost' IDENTIFIED BY 'super secret password'"
+sudo mysql -e "CREATE DATABASE arssedb"
+sudo mysql -e "GRANT ALL ON arssedb.* TO 'arsseuser'@'localhost'"
+```
+
+Tha Arsse must then be configured to use the create database. A suitable [configuration file](/en/Configuring_The_Arsse) might look like this:
+
+```php
+<?php
+return [
+    'dbDriver'    => "mysql",
+    'dbMySQLUser' => "arsseuser",
+    'dbMySQLPass' => "super secret password",
+    'dbMySQLDb'   => "arssedb",
+];
+```
+
+Numerous alternate configurations are possible; the above is merely the simplest.

docs/en/020_Installation/040_Database_Setup/index.md

@@ -8,6 +8,4 @@ All of the above are supported both via their PDO driver extensions as well as t
 
 Functionally there is no reason to prefer either SQLite or PostgreSQL over the other. SQLite is significantly simpler to set up in most cases, requiring only read and write access to a containing directory in order to function; PostgreSQL may perform better than SQLite when serving hundreds of users or more, though this has not been tested.
 
-MySQL, on the other hand, is **not recommended** due to its relatively constrained index prefix limits which may cause some newsfeeds which would otherwise work to be rejected. If using MySQL, special care should also be taken when performing schema upgrades, as errors during the process can leave the database in a half-upgraded state which The Arsse cannot itself recover from.
-
-Note that MariaDB is not compatible with The Arsse: its support for common table expressions is, as of this writing, not sufficient for our needs.
+MySQL, on the other hand, is **not recommended** due to various technical limitations.