Update shared SQL database page for PostgreSQL-only live sync

en/collaborative-work/sqldatabase/README.md

@@ -4,27 +4,31 @@
 
 # Shared SQL Database
 
+JabRef uses [PostgreSQL](https://www.postgresql.org/) as the database system for shared databases. Support for MySQL/MariaDB and Oracle was removed due to high maintenance effort.
+
 ## Usage
 
-To use this feature you have to connect to a remote database. To do so you have to open **File** in the menu bar and then click the **Connect to shared database** item. The **Connect to shared database** dialog will open and you will have to fill in the shared's database connection settings. Then, you have to fill out the remaining fields with the according information. If you like you can save your password by clicking the **Remember password?** checkbox.
+To use this feature you have to connect to a remote database. To do so you have to open **File** in the menu bar and then click **Shared database** and **Connect to shared database**. The **Connect to shared database** dialog will open. The quickest way to fill it in is to paste the connection URL of your database (as shown by your hosting provider, e.g. `postgres://user:password@host:5432/database?sslmode=require`, a JDBC URL, the keyword form `host=… port=… dbname=… user=… password=…`, or even the whole `psql 'postgres://…'` command line) into the **Connection URL** field: host, port, database, user, and password are filled in automatically. Alternatively, enter these details by hand. If you like you can save your password by ticking the **Remember password** checkbox; it is then kept in your operating system's credential store (keychain). The checkbox is unavailable if no credential store can be reached.
+
+Settings that are rarely needed (SSL and a custom JDBC URL for the *expert mode*) are found in the collapsible **Advanced** section. When a pasted URL contains parameters JabRef has no dedicated field for (such as `sslmode=require`), expert mode is switched on and the parameters are kept in the custom JDBC URL, so the connection is made exactly as the URL says.
+
+If the database was already used by an older version of JabRef, its content is migrated to the new table structure automatically when the first client connects. The old tables are kept untouched, so older JabRef versions can still be used with them.
 
 ### SSL configuration
 
-Since version 5.0 JabRef supports secure SSL connection to the database. For PostgreSQL make sure the server supports SSL and you have correctly setup the [certificates](https://www.postgresql.org/docs/current/static/ssl-tcp.html). Then [convert the client certificates](https://jdbc.postgresql.org/documentation/ssl/#configuring-the-client) into a java readable format and import them into a (custom) keystore. For MySQL the procedure is similar. [Setting up MySQL with SSL](https://dev.mysql.com/doc/refman/8.0/en/using-encrypted-connections.html) and converting the certificates for the java keystore. However, it has only been tested with PostgreSQL. Once the certificates are imported into the keystore, specify the path to the keystore file in the connection dialog and the password for accessing the keystore.
+Tick **Use SSL** in the **Advanced** section to require an encrypted connection. Like `psql`, this does not verify the server's certificate, so managed PostgreSQL providers with their own certificate authorities work out of the box; a pasted URL with `sslmode=require` ticks the box for you. If you want the server certificate verified, use the expert mode with a JDBC URL such as `jdbc:postgresql://host:5432/database?sslmode=verify-full&sslrootcert=/path/to/ca.pem`; a pasted URL with `sslmode=verify-full` sets this up automatically.
 
 ![Screenshot of Connect to shared database dialog](../../.gitbook/assets/open-shared-database-dialog.png)
 
 After connecting to your shared database, your main window should look like this:
 
 ![Screenshot of JabRef with an open shared database](../../.gitbook/assets/open-shared-databse-screenshot.png)
 
-JabRef will automatically detect your changes and push them to the shared side. JabRef will also constantly check if there is a newer version available. If you experience connection issues, you can pull changes from your shared database via the icon in the icon bar. If a newer version is available, JabRef will try to automatically merge the new version and your local copy. If this fails, the **Update refused** dialog will show up. You will then have to manually merge using the **Update refused** dialog. The dialog helps you by pointing out the differences, you then will have to choose if you want to keep your local version or update to the shared version. Confirm your merge by clicking on **Merge entries**.
+JabRef will automatically detect your changes and push them to the shared side. Changes made by other users arrive automatically as well: JabRef listens for change notifications from the database, so edits, new groups, and changed library settings show up in all connected JabRef instances without any manual action. If a newer version is available, JabRef will try to automatically merge the new version and your local copy. If this fails, the **Update refused** dialog will show up. You will then have to manually merge using the **Update refused** dialog. The dialog helps you by pointing out the differences, you then will have to choose if you want to keep your local version or update to the shared version. Confirm your merge by clicking on **Merge entries**.
 
 ![Screenshot of Update refused dialog](../../.gitbook/assets/update-refused-merge-dialog.png)
 
-The **Update refused** dialog can also take a different form, if the BibEntry you currently work on has been deleted on the shared side. You can choose to keep the BibEntry in the database by clicking **Keep** or update to the shared side and click **Close**.
-
-![Screenshot of Update refused dialog due to a deleted entry](../../.gitbook/assets/update-refused-deleted-entry-dialog.png)
+If somebody else deletes entries, they disappear from your library as well and a notification tells you how many were deleted on the shared side. If you were still working on one of them, use **Undo** to get it back: it is inserted into the shared database again.
 
 If you experience a problem with your connection to your shared database, the **Connection lost** dialog will show up. You can choose to **Reconnect**, **Work offline** or **Close database**. Most of the time simply reconnecting will fix this problem, if that's not the case you will have to choose between **Work offline** or **Close database**. Pick **Work offline** if you want to make sure your changes are saved. If you think there is nothing to save just pick **Close database**. If you choose to work offline, JabRef will convert the shared database to a local .bib database. Since you are no longer working online, but instead on a local database, you will have to import your work via copy and paste into the shared database. However before you import it into the shared database, make sure to check if changes happened during your offline time. Otherwise you might override someone else's work.