From cfe6336b6e1d07b2cbb7432db87054128286e39b Mon Sep 17 00:00:00 2001 From: Phil Hagelberg Date: Wed, 14 May 2025 13:25:52 +0000 Subject: [PATCH] [chore] Change default database in example config to sqlite, update docs. (#4174) As discussed in Matrix chat. * Change DB in example config to sqlite. * Clarify config settings which only apply to postgres. * Update getting started docs; no need to change example config any more. * In "single board computers" mention SD card corruption risk. ## Checklist Please put an x inside each checkbox to indicate that you've read and followed it: `[ ]` -> `[x]` If this is a documentation change, only the first checkbox must be filled (you can delete the others if you want). - [X] I/we have read the [GoToSocial contribution guidelines](https://codeberg.org/superseriousbusiness/gotosocial/src/branch/main/CONTRIBUTING.md). - [X] I/we have discussed the proposed changes already, either in an issue on the repository, or in the Matrix chat. - [X] I/we have not leveraged AI to create the proposed changes. - [X] I/we have performed a self-review of added code. - [X] I/we have made any necessary changes to documentation. Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4174 Co-authored-by: Phil Hagelberg Co-committed-by: Phil Hagelberg --- docs/configuration/database.md | 24 +++++++++++----------- docs/getting_started/index.md | 2 +- docs/getting_started/installation/metal.md | 2 -- example/config.yaml | 16 +++++++-------- internal/config/defaults.go | 4 ++-- 5 files changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/configuration/database.md b/docs/configuration/database.md index 06b6b4f60..223742753 100644 --- a/docs/configuration/database.md +++ b/docs/configuration/database.md @@ -2,21 +2,21 @@ GoToSocial stores statuses, accounts, etc, in a database. This can be either [SQLite](https://sqlite.org/index.html) or [Postgres](https://www.postgresql.org/). -By default, GoToSocial will use Postgres, but this is easy to change. +By default, GoToSocial will use SQLite, but this is easy to change. ## SQLite SQLite, as the name implies, is the lightest database type that GoToSocial can use. It stores entries in a simple file format, usually in the same directory as the GoToSocial binary itself. SQLite is great for small instances and single-board computers, where a dedicated database would be overkill. -To configure GoToSocial to use SQLite, change `db-type` to `sqlite`. The `address` setting will then be a filename instead of an address, so you will want to change it to `sqlite.db` or something similar. +To use SQLite, keep the default `db-type` as `sqlite`. By default the database will be kept in the same directory as the GoToSocial binary, ie., `./sqlite.db`, but you can change this using `db-address` if you want to keep it somewhere else. In the same directory as the `sqlite.db` file, the SQLite driver will also create files `sqlite.db-wal` and `sqlite.db-shm` for temporary storage. Note that the `:memory:` setting will use an *in-memory database* which will be wiped when your GoToSocial instance stops running. This is for testing only and is absolutely not suitable for running a proper instance, so *don't do this*. ## Postgres -Postgres is a heavier database format, which is useful for larger instances where you need to scale performance, or where you need to run your database on a dedicated machine separate from your GoToSocial instance (or do funky stuff like run a database cluster). +Postgres (aka PostgreSQL) is a heavier database which is useful for larger instances where you need to run your database on a dedicated machine separate from your GoToSocial instance (or do funky stuff like run a database cluster). -You can connect to Postgres using either a Unix socket connection, or via TCP, depending on what you've set as your `db-address` value. +To configure GoToSocial to use Postgres, change `db-type` to `postgres`. The `db-address` setting will then be either a Unix socket connection or a hostname. GoToSocial also supports connecting to Postgres using SSL/TLS over TCP. If you're running Postgres on a different machine from GoToSocial, and connecting to it via an IP address or hostname (as opposed to just running on localhost), then SSL/TLS is **CRUCIAL** to avoid leaking data all over the place! @@ -71,8 +71,8 @@ db-postgres-connection-string: 'postgres://myUser:myPass@localhost/db?search_pat # String. Database type. # Options: ["postgres","sqlite"] -# Default: "postgres" -db-type: "postgres" +# Default: "sqlite" +db-type: "sqlite" # String. Database address or parameters. # @@ -87,29 +87,29 @@ db-type: "postgres" # # Examples: ["localhost","my.db.host","127.0.0.1","192.111.39.110",":memory:", "sqlite.db"] # Default: "" -db-address: "" +db-address: "sqlite.db" -# Int. Port for database connection. +# Int. Port for postgres database connection; ignored for sqlite. # Examples: [5432, 1234, 6969] # Default: 5432 db-port: 5432 -# String. Username for the database connection. +# String. Username for postgres database connection. # Examples: ["mydbuser","postgres","gotosocial"] # Default: "" db-user: "" -# String. Password to use for the database connection +# String. Password to use for postgres database connection. # Examples: ["password123","verysafepassword","postgres"] # Default: "" db-password: "" -# String. Name of the database to use within the provided database type. +# String. Name of the database to use for postgres database connection. # Examples: ["mydb","postgres","gotosocial"] # Default: "gotosocial" db-database: "gotosocial" -# String. Disable, enable, or require SSL/TLS connection to the database. +# String. Disable, enable, or require SSL/TLS connection to postgres. # If "disable" then no TLS connection will be attempted. # If "enable" then TLS will be tried, but the database certificate won't be checked (for self-signed certs). # If "require" then TLS will be required to make a connection, and a valid certificate must be presented. diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 286a2e4fd..e99e069e3 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -55,7 +55,7 @@ For media storage, including [storage of remote media files in the cache](../adm ### Single-board Computers -GoToSocial's light system requirements means that it runs pretty well on decently-specced single-board computers. If running on a single-board computer, you should ensure that GoToSocial is using a USB drive (preferably an SSD) to store its database files and media, not SD card storage, since the latter tends to be too slow to run a database on. +GoToSocial's light system requirements means that it runs pretty well on decently-specced single-board computers. If running on a single-board computer, you should ensure that GoToSocial is using a USB drive (preferably an SSD) to store its database files and media, not SD card storage, since the latter tends to be too slow to run a database on and can easily get corrupted with write-heavy workloads. ### VPS diff --git a/docs/getting_started/installation/metal.md b/docs/getting_started/installation/metal.md index 093f0e678..563522918 100644 --- a/docs/getting_started/installation/metal.md +++ b/docs/getting_started/installation/metal.md @@ -63,8 +63,6 @@ You'll probably need to change the following settings: - Set `host` to whatever hostname you're going to be running the server on (eg., `example.org`). - Set `port` to `443`. -- Set `db-type` to `sqlite`. -- Set `db-address` to `sqlite.db`. - Set `storage-local-base-path` to the storage directory you created above (eg., `/gotosocial/storage`). - Set `letsencrypt-enabled` to `true`. - Set `letsencrypt-cert-dir` to the certificate storage directory you created above (eg., `/gotosocial/storage/certs`). diff --git a/example/config.yaml b/example/config.yaml index ce81da1fe..b8a6599a4 100644 --- a/example/config.yaml +++ b/example/config.yaml @@ -141,8 +141,8 @@ trusted-proxies: # String. Database type. # Options: ["postgres","sqlite"] -# Default: "postgres" -db-type: "postgres" +# Default: "sqlite" +db-type: "sqlite" # String. Database address or parameters. # @@ -157,29 +157,29 @@ db-type: "postgres" # # Examples: ["localhost","my.db.host","127.0.0.1","192.111.39.110",":memory:", "sqlite.db"] # Default: "" -db-address: "" +db-address: "sqlite.db" -# Int. Port for database connection. +# Int. Port for postgres database connection; ignored for sqlite. # Examples: [5432, 1234, 6969] # Default: 5432 db-port: 5432 -# String. Username for the database connection. +# String. Username for postgres database connection. # Examples: ["mydbuser","postgres","gotosocial"] # Default: "" db-user: "" -# String. Password to use for the database connection +# String. Password to use for postgres database connection. # Examples: ["password123","verysafepassword","postgres"] # Default: "" db-password: "" -# String. Name of the database to use within the provided database type. +# String. Name of the database to use for postgres database connection. # Examples: ["mydb","postgres","gotosocial"] # Default: "gotosocial" db-database: "gotosocial" -# String. Disable, enable, or require SSL/TLS connection to the database. +# String. Disable, enable, or require SSL/TLS connection to postgres. # If "disable" then no TLS connection will be attempted. # If "enable" then TLS will be tried, but the database certificate won't be checked (for self-signed certs). # If "require" then TLS will be required to make a connection, and a valid certificate must be presented. diff --git a/internal/config/defaults.go b/internal/config/defaults.go index 81242996d..8ed6ed0ea 100644 --- a/internal/config/defaults.go +++ b/internal/config/defaults.go @@ -41,8 +41,8 @@ var Defaults = Configuration{ Port: 8080, TrustedProxies: []string{"127.0.0.1/32", "::1"}, // localhost - DbType: "postgres", - DbAddress: "", + DbType: "sqlite", + DbAddress: "db.sqlite", DbPort: 5432, DbUser: "", DbPassword: "",