Updated extensions documentation

docs/config.md

@@ -1,122 +1,125 @@
-# Configuration
-
-Ledger's configuration file is found in `config/ledger.toml`.
-It is written in [TOML](https://toml.io/en/) and can be edited in any text editor.
-Any changes you make to the config will be automatically updated without needing to reload or restart the server.
-When checking for the config for a value, it first checks the system properties,
-then the system environment, then the config file and finally it will use the default.
-For more info, read about [Konf](https://github.com/uchuhimo/konf).
-To regenerate the config file, simply delete it.
-
-### Database settings
-
-Found under `[database]`
-
-`queueTimeoutMin` [Default: 5] is the maximum amount of time to wait for the queue to drain when the server stops in minutes
-
-`queueCheckDelaySec` [Default: 10] is the frequency in seconds to notify in console that the queue is not empty when the server stops
-
-`autoPurgeDays` [Default: -1] is the number of days to keep actions in the database. If set to -1, actions will never be purged automatically
-
-`batchSize` [Default: 1000] is the number of actions to insert into the database at once.
-This can be increased to improve performance, but may cause issues with slow databases
-
-`batchDelay` [Default: 10] is the amount of time in ticks to wait between batches if the next batch isn't full.
-This can be increased to improve performance, but may cause issues with slow databases
-
-`location` [Default: Nothing] is the location of the database file when using the default SQLite database or other file based databases like H2.
-The path is relative to the server's root directory. If the path is left out, the database will default to the server's world directory.
-
-`logSQL` [Default: false] will log all SQL queries to the console. This is useful for debugging, but can be very spammy
-
-`updateSchema` [Default: false] will run updates old databases on startup when true. This can take a long time for large databases.
-Current schema updates: Add actions_time index
-
-### Search settings
-
-Found under `[search]`
-
-`pageSize` [Default: 8] controls the number of actions displayed per page
-
-`purgePermissionLevel` [Default: 4] controls the permission level required to run the purge command
-
-`timeZone` [Default: "UTC"] sets the timezone to display timestamps in when hovered. 
-This uses the Java TimeZone format. You can provide offsets ("UTC", "UTC+3"), but the "continent/region" format is preferred. A full list can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-
-`maxRange` [Default: 100] controls the maximum range allowed in rollback / restore
-
-### Message theme
-
-Found under `[color]`
-
-Ledger allows for the customisation of the colors used in the messages sent in game. 
-By default, Ledger uses the blue theme. More themes can be found in the [themes](themes.md) file
-
-### Filters
-
-These allow you to control what is and is not logged
-
-Found under `[actions]`
-
-All listed here are arrays and are formatted like so:
-```toml
-array = []
-blocks = ["minecraft:air", "minecraft:dirt"]
-```
-
-`typeBlacklist` [Default: empty] controls what action types are logged. Hover over the action in a chat message to see the type
-
-`worldBlacklist` [Default: empty] controls in which dimensions events are logged.
-
-`objectBlacklist` [Default: empty] controls which objects are logged. These can be item types, block types or entities
-
-`sourceBlacklist` [Default: empty] controls which sources are logged. Examples are `"lava"`, `"@playerName"` and `"gravity"`. Player names can be specified by prefixing them with `"@"`
-
-## Default Config
-```toml
-[database]
-# The maximum amount of time to wait for the queue to drain when the server stops
-queueTimeoutMin = 5
-# The amount of time between checking if the queue is empty when the server stops
-queueCheckDelaySec = 10
-
-[search]
-# Number of actions to show per page
-pageSize = 8
-# Permission level for purge command
-purgePermissionLevel = 4
-# Time zone to display timestamps in. EX: "UTC", "UTC+1", "America/Los_Angeles"
-timeZone = "UTC"
-
-[color]
-# Colors in hex format
-primary = "#009688"
-primaryVariant = "#52c7b8"
-secondary = "#1e88e5"
-secondaryVariant = "#6ab7ff"
-light = "#c5d6f0"
-
-[actions]
-# Blacklists - blacklisted things will not be logged in the database
-# Example - Prevent all actions with stone or bat as the object from being logged
-# objectBlacklist = [
-#   "minecraft:stone",
-#   "minecraft:bat"
-# ]
-
-# Blacklists action types. Ex: "block-break", "entity-kill"
-typeBlacklist = []
-# Blacklists worlds/dimensions. Ex: "mincraft:the_end", "minecraft:overworld"
-worldBlacklist = []
-# Blacklists objects (Items, Mobs, Blocks). Ex: "minecraft:cobblestone", "minecraft:blaze"
-objectBlacklist = []
-# Blacklists sources. Ex: "lava", "gravity", "fire", "fall", "@playerName"
-sourceBlacklist = []
-
-[networking]
-# This section relates to Ledger's ability to interact with client mods for ease of use
-# Networking is enabled by default but you can disable it here
-
-# Change to true to allow Ledger client mod packets
-networking = true
+# Configuration
+
+Ledger's configuration file is found in `config/ledger.toml`.
+It is written in [TOML](https://toml.io/en/) and can be edited in any text editor.
+Any changes you make to the config will be automatically updated without needing to reload or restart the server.
+When checking for the config for a value, it first checks the system properties,
+then the system environment, then the config file and finally it will use the default.
+For more info, read about [Konf](https://github.com/uchuhimo/konf).
+To regenerate the config file, simply delete it.
+
+### Database settings
+
+Found under `[database]`
+
+`queueTimeoutMin` [Default: 5] is the maximum amount of time to wait for the queue to drain when the server stops in minutes
+
+`queueCheckDelaySec` [Default: 10] is the frequency in seconds to notify in console that the queue is not empty when the server stops
+
+`autoPurgeDays` [Default: -1] is the number of days to keep actions in the database. If set to -1, actions will never be purged automatically
+
+`batchSize` [Default: 1000] is the number of actions to insert into the database at once.
+This can be increased to improve performance, but may cause issues with slow databases
+
+`batchDelay` [Default: 10] is the amount of time in ticks to wait between batches if the next batch isn't full.
+This can be increased to improve performance, but may cause issues with slow databases
+
+`location` [Default: Nothing] is the location of the database file when using the default SQLite database or other file based databases like H2.
+The path is relative to the server's root directory. If the path is left out, the database will default to the server's world directory.
+
+`logSQL` [Default: false] will log all SQL queries to the console. This is useful for debugging, but can be very spammy
+
+`updateSchema` [Default: false] will run updates old databases on startup when true. This can take a long time for large databases.
+Current schema updates: Add actions_time index
+
+### Search settings
+
+Found under `[search]`
+
+`pageSize` [Default: 8] controls the number of actions displayed per page
+
+`purgePermissionLevel` [Default: 4] controls the permission level required to run the purge command
+
+`timeZone` [Default: "UTC"] sets the timezone to display timestamps in when hovered. 
+This uses the Java TimeZone format. You can provide offsets ("UTC", "UTC+3"), but the "continent/region" format is preferred. A full list can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+`maxRange` [Default: 100] controls the maximum range allowed in rollback / restore
+
+### Message theme
+
+Found under `[color]`
+
+Ledger allows for the customisation of the colors used in the messages sent in game. 
+By default, Ledger uses the blue theme. More themes can be found in the [themes](themes.md) file
+
+### Filters
+
+These allow you to control what is and is not logged
+
+Found under `[actions]`
+
+All listed here are arrays and are formatted like so:
+```toml
+array = []
+blocks = ["minecraft:air", "minecraft:dirt"]
+```
+
+`typeBlacklist` [Default: empty] controls what action types are logged. Hover over the action in a chat message to see the type
+
+`worldBlacklist` [Default: empty] controls in which dimensions events are logged.
+
+`objectBlacklist` [Default: empty] controls which objects are logged. These can be item types, block types or entities
+
+`sourceBlacklist` [Default: empty] controls which sources are logged. Examples are `"lava"`, `"@playerName"` and `"gravity"`. Player names can be specified by prefixing them with `"@"`
+
+### Extension config
+Config for [extensions](extensions/extensions.md) should be placed in this file too. See relevant extension for options.
+
+## Default Config
+```toml
+[database]
+# The maximum amount of time to wait for the queue to drain when the server stops
+queueTimeoutMin = 5
+# The amount of time between checking if the queue is empty when the server stops
+queueCheckDelaySec = 10
+
+[search]
+# Number of actions to show per page
+pageSize = 8
+# Permission level for purge command
+purgePermissionLevel = 4
+# Time zone to display timestamps in. EX: "UTC", "UTC+1", "America/Los_Angeles"
+timeZone = "UTC"
+
+[color]
+# Colors in hex format
+primary = "#009688"
+primaryVariant = "#52c7b8"
+secondary = "#1e88e5"
+secondaryVariant = "#6ab7ff"
+light = "#c5d6f0"
+
+[actions]
+# Blacklists - blacklisted things will not be logged in the database
+# Example - Prevent all actions with stone or bat as the object from being logged
+# objectBlacklist = [
+#   "minecraft:stone",
+#   "minecraft:bat"
+# ]
+
+# Blacklists action types. Ex: "block-break", "entity-kill"
+typeBlacklist = []
+# Blacklists worlds/dimensions. Ex: "mincraft:the_end", "minecraft:overworld"
+worldBlacklist = []
+# Blacklists objects (Items, Mobs, Blocks). Ex: "minecraft:cobblestone", "minecraft:blaze"
+objectBlacklist = []
+# Blacklists sources. Ex: "lava", "gravity", "fire", "fall", "@playerName"
+sourceBlacklist = []
+
+[networking]
+# This section relates to Ledger's ability to interact with client mods for ease of use
+# Networking is enabled by default but you can disable it here
+
+# Change to true to allow Ledger client mod packets
+networking = true
 ```

docs/extensions/extensions.md

@@ -1,18 +1,18 @@
-# Extensions
-
-Ledger extensions allow for additional functionality to be added to Ledger via another mod
-
-## Install
-
-1. Install Ledger
-2. Install the extension of your choice in your mods folder
-3. Run your server and adjust the config as needed. The extension should provide information on how to configure it
-
-## Available extensions
-- [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) - Adds support for MySQL and H2
-
-## Features possible via extensions
-
-- Changing the type of database used by Ledger
-- Adding custom commands
+# Extensions
+
+Ledger extensions allow for additional functionality to be added to Ledger via another mod
+
+## Install
+
+1. Install Ledger
+2. Install the extension of your choice in your mods folder
+3. Run your server and adjust the config as needed. The extension should provide information on how to configure it
+
+## Available extensions
+- [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) - Adds support for MySQL, H2, PostgreSQL, SQLite and MariaDB - [See documentation](ledger-databases.md).
+
+## Features possible via extensions
+
+- Changing the type of database used by Ledger
+- Adding custom commands
 - Adding configuration options to the existing [config file](../config.md)

docs/extensions/ledger-databases.md

@@ -0,0 +1,78 @@
+# Ledger Databases 
+Adds support for MySQL, MariaDB, H2, and PostgreSQL databases in Ledger.
+
+# Config
+These settings can be appended to the bottom of the bottom of the [config file](../config.md).
+
+To set these as environment variables, [Konf](https://github.com/uchuhimo/konf) maps `database_extensions` to `DATABASEEXTENSIONS` (drops the underscore), e.g. set `DATABASEEXTENSIONS_PASSWORD=<your_secret>`.
+
+### H2
+
+Add the following to the bottom of your Ledger config file:
+
+```toml
+[database_extensions]
+database = "H2"
+```
+
+### MySQL
+
+Add the following to the bottom of your Ledger config file:
+
+```toml
+[database_extensions]
+database = "MYSQL"
+url = ""
+username = ""
+password = ""
+properties = []
+maxPoolSize = 10
+connectionTimeout = 60000
+```
+
+`url`: Must be URL of database with `/<database_name>` appended. An example URL would be `localhost/ledger`. You can optionally add port information such as `localhost:3000/ledger`
+
+### MariaDB
+
+Add the following to the bottom of your Ledger config file:
+
+```toml
+[database_extensions]
+database = "MARIADB"
+url = ""
+username = ""
+password = ""
+properties = []
+maxPoolSize = 10
+connectionTimeout = 60000
+```
+
+`url`: Must be URL of database with `/<database_name>` appended. An example URL would be `localhost/ledger`. You can optionally add port information such as `localhost:3000/ledger`
+
+### PostgreSQL
+
+```toml
+[database_extensions]
+database = "POSTGRESQL"
+url = ""
+username = ""
+password = ""
+properties = []
+maxPoolSize = 10
+connectionTimeout = 60000
+```
+
+### SQLite
+
+```toml
+[database_extensions]
+database = "SQLITE"
+```
+
+### Connector properties
+
+For some databases, such as MySQL, you can provide properties to the database connector. For each property, add a string entry to the `properties` array.
+
+```toml
+properties = ["useJDBCCompliantTimezoneShift=true", "useLegacyDatetimeCode=false", "serverTimezone=UTC"]
+```