Add tutorial for increasing transaction db page size.

content/tutorials/manage-the-rippled-server/sqlitepagesize.md

@@ -0,0 +1,61 @@
+# Transaction DB (SQLite) page size issue
+rippled stores a copy of its transaction history in a SQLite database. Earlier versions of rippled configured this database to have a capacity of roughly 2TB. For most rippled operators, this is plenty. However, full transactional history back to ledger 32570 is likely to exceed this value. This document describes steps to detect and correct this problem if it arises.
+
+## Detection
+
+### Pro-active
+For proactive detection, make sure to upgrade to [version with PR2635 https://github.com/ripple/rippled/pull/2635] and look for messages that occur at least every 2 minutes in the debug log file similar to as follows:
+
+```Transaction DB pathname: /opt/rippled/transaction.db; SQLite page size: 1024 bytes; Free pages: 247483646; Free space: 253423253504 bytes; Note that this does not take into account available disk space.```
+
+ The numeric values in that sample log entry will vary based upon your own environment. Once the free space falls below 524288000 bytes (500MB), then rippled will halt. To avoid unexpected outage, fix the problem before free space gets below that threshold.
+
+### Reactive
+
+As mentioned, if capacity is exceeded, then rippled service will be disrupted. It will either crash repeatedly or fail gracefully, depending on the version of rippled.
+ 
+For versions of rippled previous to [version with PR2635 https://github.com/ripple/rippled/pull/2635], rippled will crash repeatedly with errors in the debug log file resembling as follows:
+
+```Terminating thread doJob: AcquisitionDone: unhandled N4soci18sqlite3_soci_errorE 'sqlite3_statement_backend::loadOne: database or disk is full while executing "INSERT INTO [...]```
+
+For more recent versions, rippled will halt gracefully with the following message in the debug log:
+
+```Free SQLite space for transaction db is less than 512MB. To fix this, rippled must be executed with the vacuum <sqlitetmpdir> parameter before restarting. Note that this activity can take multiple days, depending on database size.```
+
+## Fix
+
+To fix this issue, make sure to have rippled on at least  [version with PR2635 https://github.com/ripple/rippled/pull/2635]
+
+Note that if the `Transaction DB page size` in the log file entry described above is already at 4096 or higher, then this process does not need to be performed. There should be adequate space in SQLite for the Transaction DB.
+
+The process for fixing this involves rippled changing the page size used by SQLite for the transaction database. More information about the internals of SQLite can be found at: https://www.sqlite.org/fileformat.html
+There is no need to directly modify any data files. Instead, rippled should be used to perform this activity according to steps in this document. To prepare, do the following:
+1. Upgrade rippled to a minimum version [described above]
+2. Create a directory writable by the `rippled` user on a filesystem with at least as much free space as the size of the transaction database. The file name is listed in a debug log file entry above. To get the most recent file size, shut down rippled and perform the following command based on the example transaction db pathname:
+```ls -l /opt/rippled/transaction.db```
+This may require adding space to an existing filesystem, or creating a new filesytem. In either case, follow processes suitable for your operating system. The space will be used temporarily by rippled, and can be removed after the process completes. Existing directories such as `/tmp` or `/var/tmp` are suitable for this insofar as their filesystems contain adequate free space.
+
+Once prepared, use the following steps based on rippled running on Linux with the binary RPM installation:
+
+1. If rippled is still running, stop it:
+```sudo systemctl stop rippled```
+2. The process may take a long time, depending on the size of the Transaction database. With free space of 500MB or less, the duration will likely take more than 2 full days. Therefore, the rippled process shuld be run in a terminal session that will not stop once the user logs out. The `screen` command on Linux is suitable for this.
+```screen```
+3. Become the rippled user:
+```sudo su - rippled```
+4. Execute rippled appropriately including the name of the directory described above:
+```/opt/ripple/bin/rippled -q --vacuum <temporarydir>```
+The following  will appear immediately:
+```VACUUM beginning. page_size: 1024```
+5. The following message will appear as the process finishes:
+```VACUUM finished. page_size: 4096```
+
+Usage of the `screen` command is documented widely on the Internet. However, the following steps should be sufficient for this process. To detach from the screen session but still keep rippled running within it, press <CTRL-a d\>
+That will return you to the original terminal session from which you launched `screen`. To return to the `screen` session, type:
+```screen -x -r```
+Once rippled finishes the `vacuum` process, `exit` the screen session.
+
+Restart rippled:
+```sudo systemctl start rippled```
+
+The periodic debug log entry described near the beginning of this document will now show page size of 4096 and significantly more free pages and free SQLite space.