From 1f6e3db09ee738d49579d13925d04c8ffe0a5a4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hmer?= Date: Fri, 21 Jun 2024 12:31:25 +0200 Subject: [PATCH] Document natural sorting and the DATABASE_EMULATE_NATURAL_SORT option --- .env | 2 +- docs/configuration.md | 3 +++ docs/installation/choosing_database.md | 26 ++++++++++++++++++++++++++ 3 files changed, 30 insertions(+), 1 deletion(-) diff --git a/.env b/.env index b35b17f5..cf39b10d 100644 --- a/.env +++ b/.env @@ -24,7 +24,7 @@ DATABASE_MYSQL_USE_SSL_CA=0 DATABASE_MYSQL_SSL_VERIFY_CERT=1 # Emulate natural sorting of strings even on databases that do not support it (like SQLite, MySQL or MariaDB < 10.7) -# This can be slow on big databases +# This can be slow on big databases and might have some problems and quirks, so use it with caution DATABASE_EMULATE_NATURAL_SORT=0 ################################################################################### diff --git a/docs/configuration.md b/docs/configuration.md index 8990e9a7..c0daa407 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -40,6 +40,9 @@ options listed, see `.env` file for the full list of possible env variables. * `DATABASE_MYSQL_USE_SSL_CA`: If this value is set to `1` or `true` and a MySQL connection is used, then the connection is encrypted by SSL/TLS and the server certificate is verified against the system CA certificates or the CA certificate bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept all certificates. +* `DATABASE_EMULATE_NATURAL_SORT` (default 0): If set to 1, Part-DB will emulate natural sorting, even if the database + does not support it natively. However this is much slower than the native sorting, and contain bugs or quirks, so use + it only, if you have to. * `DEFAULT_LANG`: The default language to use server-wide (when no language is explicitly specified by a user or via language chooser). Must be something like `en`, `de`, `fr`, etc. * `DEFAULT_TIMEZONE`: The default timezone to use globally, when a user has no timezone specified. Must be something diff --git a/docs/installation/choosing_database.md b/docs/installation/choosing_database.md index 2f9002bc..69dc810e 100644 --- a/docs/installation/choosing_database.md +++ b/docs/installation/choosing_database.md @@ -154,3 +154,29 @@ If you want to use a unix socket for the connection instead of a TCP connnection ```shell DATABASE_URL="postgresql://db_user:db_password@localhost/db_name?serverVersion=12.19&charset=utf8&unix_socket=/var/run/postgresql/.s.PGSQL.5432" ``` + + +## Natural Sorting + +Natural sorting is the sorting of strings in a way that numbers are sorted by their numerical value, not by their ASCII value. + +For example in the classical binary sorting the string `DIP-4`, `DIP-8`, `DIP-16`, `DIP-28` would be sorted as following: + +* `DIP-16` +* `DIP-28` +* `DIP-4` +* `DIP-8` + +In natural sorting, it would be sorted as: + +* `DIP-4` +* `DIP-8` +* `DIP-16` +* `DIP-28` + +Part-DB can sort names in part tables and tree views naturally. PostgreSQL and MariaDB 10.7+ support natural sorting natively, +and it is automatically used if available. + +For SQLite and MySQL < 10.7 it has to be emulated if wanted, which is pretty slow. Therefore it has to be explicity enabled by setting the +`DATABASE_EMULATE_NATURAL_SORT` environment variable to `1`. If it is 0 the classical binary sorting is used, on these databases. The emulations +might have some quirks and issues, so it is recommended to use a database which supports natural sorting natively, if you want to use it.