Implement DSN-based database connection

The DSN-based connection configuration is closer to what PHP does with PDO
objects under the hood and this allows the use of more scenarios such as socket
connections and databases out-of-the-box without user_backend_sql_raw
having to provide configuration parameters for each option.

Author: Alexey Abel

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Addded
+
+* DSN-based database connection mechanism. This enables support for socket-based database connections and also connections to Firebird, MS SQL, Oracle DB, ODBC, DB2, SQLite, Informix and IBM databases - basically whatever the [PHP PDO-driver](https://www.php.net/manual/en/pdo.drivers.php) supports. But PostgreSQL remains the only tested database and MySQL/MariaDB to some degree. The other databaes should "just work", but this has not been tested.
+* `dsn` configuration key
+
+### Removed
+
+* configuration keys `db_type`, `db_host`, `db_port`, `db_name`, `mariadb_charset`. These settings must now be included in the DSN string. See [README.md](README.md) on how to do this.
+
 ## [1.5.1] - 2024-05-01
 
 ### Fixed

README.md

@@ -22,7 +22,11 @@ Argon2id. Because the various formats are recognized on-the-fly your db can can
 have differing hash string formats at the same time, which eases migration to
 newer formats.
 
-This app supports PostgreSQL and MariaDB/MySQL.
+This app primarily supports PostgreSQL and MariaDB/MySQL but the underlying PHP
+[mechanism](https://www.php.net/manual/en/pdo.drivers.php) also supports
+Firebird, MS SQL, Oracle DB, ODBC, DB2, SQLite, Informix and IBM databases. By
+using an appropriate DSN you should be able to connect to these databases. This
+has not been tested, though.
 
 See [CHANGELOG.md](CHANGELOG.md) for changes in newer versions. This app follows
 semantic versioning and there should not be any breaking changes unless the
@@ -45,7 +49,7 @@ This app has no user interface. All configuration is done via Nextcloud's system
    //'db_type' => 'postgresql',
    //'db_host' => 'localhost',
    //'db_port' => '5432',
-   'db_name' => 'theNameOfYourUserDatabase',
+   'db_name' => 'theNameOfYourDbUser',
    'db_user' => 'yourDatabaseUser',
    'db_password' => 'thePasswordForTheDatabaseUser',
    //'db_password_file' => '/var/secrets/fileContainingThePasswordForTheDatabaseUser',
@@ -70,28 +74,26 @@ There are three types of configuration parameters:
 
 ### 1. Database
 
-that *User Backend SQL Raw* will connect to.
-
-| key                | value                                                                                                                    | default value |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------- |
-| `db_type`          | `postgresql` or `mariadb`                                                                                                | `postgresql`  |
-| `db_host`          | your db host such as `localhost` or `db.example.com` or (only for PostgreSQL) path to socket, e.g. `/var/run/postgresql` | `localhost`   |
-| `db_port`          | your db port                                                                                                             | `5432`        |
-| `db_name`          | your db name                                                                                                             |               |
-| `db_user`          | your db user                                                                                                             |               |
-| `db_password`      | your db password                                                                                                         |               |
-| `db_password_file` | path to file containing the db password                                                                                  |               |
-| `mariadb_charset`  | the charset for mariadb connections                                                                                      | `utf8mb4`     |
-
-* Values without a default value are mandatory, except that
-  * only one of `db_password` or `db_passowrd_file` must be set.
-* Only the first line of the file specified by `db_passowrd_file` is read.
+that *User Backend SQL Raw* will connect to. There are two mutually exclusive ways to configure the database connection:
+1. PostgreSQL-like
+  * Set `dsn` (containing user and password) and CAN specify `db_user` and (`db_password` or `db_password_file`). Values in DSN have priority.
+2. MySQL-like
+  * Set `dsn` (not containing user and password) and MUST specify `db_user` and (`db_password` or `db_password_file`).
+
+* `dsn`: check how to construct DSNs for [PostgreSQL](https://www.php.net/manual/en/ref.pdo-pgsql.connection.php) and [MySQL](https://www.php.net/manual/en/ref.pdo-mysql.connection.php) Examples:
+  * connect to PostgreSQL via a socket with ident authentication which requires no user or password at all: `pgsql:host=/var/run/postgresql;dbname=theNameOfYourUserDb`
+  * connect to PostgreSQL via TCP and user/password authentication: `pgsql:host=localhost;port=5432;dbname=theNameOfYourUserDb;user=theNameOfYourDbUser;password=thePasswordForTheDbUser`
+  * connect to MySQL via socket which requires no user or password at all: `mysql:unix_socket=/var/run/mysql/mysql.sock;dbname=theNameOfYourUserDb`
+  * connect to MySQL via TCP and user/password authentication: `mysql:host=localhost;port=3306;dbname=testdb` and then also set `db_user` and (`db_password` or `db_password_file`)
+* `db_user`: Needs only be set for "MySQL-type" databases and is the database user that will be used to connect to the database.
+* `db_password`: Needs only be set for "MySQL-type" databases and is the password for the user that will be used to connect to the database.
+* `db_password_file`: Can be set to read the password from a file. Has higher priority than `db_password`, but lower priority than password in DSN. So, for PostgreSQL-like database connections, don't specify the password in the DSN because it would override this. For MySQL-like connections, this one will have priority.
+  * Only the first line of the file specified by `db_password_file` is read.
   * Not more than 100 characters of the first line are read.
-  * Whitespace-like characters are [stripped](https://www.php.net/manual/en/function.trim.php) from
+  * Whitespace-like characters are [trimmed](https://www.php.net/manual/en/function.trim.php) from
     the beginning and end of the read password.
-* If you specify a socket as `db_host` (only for PostgreSQL), you need to put
-  dummy values for the mandatory values, although they are not required for the
-  socket connection. This will be fixed in a future release.
+
+For other databases check their [PDO driver documentation pages](https://www.php.net/manual/en/pdo.drivers.php) which in-turn link to their respective DSN references.
 
 ### 2. SQL Queries
 

appinfo/info.xml

@@ -14,7 +14,7 @@ In contrast to the app *SQL user backend*, you write the SQL queries yourself. Y
 The app uses prepared statements and is written to be secure by default to prevent SQL injections. It understands the most popular standards for password hash formats: MD5-CRYPT, SHA256-CRYPT, SHA512-CRYPT, BCrypt and the state-of-the-art Argon2i and Argon2id. Because the various formats are recognized on-the-fly your db can can have differing hash string formats at the same time, which eases migration to newer formats.
 
 This app supports PostgreSQL and MariaDB/MySQL.]]></description>
-    <version>1.5.1</version>
+    <version>2.0.0</version>
     <licence>agpl</licence>
     <author mail="dev@abelonline.de" >Alexey Abel</author>
     <namespace>UserBackendSqlRaw</namespace>

composer.json

@@ -24,10 +24,10 @@
 		}
 	},
 	"require": {
-		"php": ">=7.0"
+		"php": ">=8.0"
 	},
 	"require-dev": {
-		"php": ">=7.3",
+		"php": ">=8.0",
 		"phpunit/phpunit": "^9"
 	}
 }

lib/AppInfo/Application.php

@@ -21,6 +21,7 @@
 
 namespace OCA\UserBackendSqlRaw\AppInfo;
 
+use OCA\UserBackendSqlRaw\Db;
 use OCP\AppFramework\Bootstrap\IBootContext;
 use OCP\AppFramework\Bootstrap\IBootstrap;
 use OCP\AppFramework\Bootstrap\IRegistrationContext;
@@ -49,10 +50,9 @@ public function register(IRegistrationContext $context): void
          * Nextcloud's dependency injection is partly explained in:
          * https://docs.nextcloud.com/server/latest/developer_manual/basics/dependency_injection.html#how-to-deal-with-interface-and-primitive-type-parameters
          */
-        $context->registerService('OCA\UserBackendSqlRaw\Db', function (ContainerInterface $container) {
-            /** @var \OCA\UserBackendSqlRaw\Config $config */
-            $config = $container->get('OCA\UserBackendSqlRaw\Config');
-            return $container->get('OCA\UserBackendSqlRaw\Dbs\\' . ucfirst($config->getDbType()));
+        $context->registerService(OCA\UserBackendSqlRaw\Db::class, function (ContainerInterface $container) {
+            // TODO: can be simplified/removed probably
+            return new OCA\UserBackendSqlRaw\Db();
         });
     }
 

lib/Config.php

@@ -26,25 +26,14 @@
 
 class Config
 {
-
-    const DEFAULT_DB_TYPE = 'postgresql';
-    const DEFAULT_DB_HOST = 'localhost';
-    const DEFAULT_POSTGRESQL_PORT = '5432';
-    const DEFAULT_MARIADB_PORT = '3306';
-    const DEFAULT_MARIADB_CHARSET = 'utf8mb4';
     const DEFAULT_HASH_ALGORITHM_FOR_NEW_PASSWORDS = 'bcrypt';
-
     const MAXIMUM_ALLOWED_PASSWORD_LENGTH = 100;
 
     const CONFIG_KEY = 'user_backend_sql_raw';
-    const CONFIG_KEY_DB_TYPE = 'db_type';
-    const CONFIG_KEY_DB_HOST = 'db_host';
-    const CONFIG_KEY_DB_PORT = 'db_port';
-    const CONFIG_KEY_DB_NAME = 'db_name';
+    const CONFIG_KEY_DSN = 'dsn';
     const CONFIG_KEY_DB_USER = 'db_user';
     const CONFIG_KEY_DB_PASSWORD = 'db_password';
     const CONFIG_KEY_DB_PASSWORD_FILE = 'db_password_file';
-    const CONFIG_KEY_MARIADB_CHARSET = 'mariadb_charset';
     const CONFIG_KEY_HASH_ALGORITHM_FOR_NEW_PASSWORDS = 'hash_algorithm_for_new_passwords';
 
     const CONFIG_KEY_QUERIES = 'queries';
@@ -81,64 +70,43 @@ public function __construct(LoggerInterface $logger, IConfig $nextCloudConfigura
                 . self::CONFIG_KEY . ' which should contain the configuration '
                 . 'for the app user_backend_sql_raw.');
         }
-    }
-
-    /**
-     * @return string db type to connect to
-     */
-    public function getDbType()
-    {
-        $dbTypeFromConfig = $this->getConfigValueOrDefaultValue(self::CONFIG_KEY_DB_TYPE
-            , self::DEFAULT_DB_TYPE);
-
-        $normalizedDbType = $this->normalize($dbTypeFromConfig);
-
-        if (!$this->dbTypeIsSupported($normalizedDbType)) {
-            throw new \UnexpectedValueException('The config key '
-                . self::CONFIG_KEY_DB_TYPE . ' is set to ' . $dbTypeFromConfig . '. This '
-                . 'value is invalid. Only postgresql and mariadb are supported.');
-        }
-
-        return $normalizedDbType;
-    }
 
-    /**
-     * @return string db host to connect to
-     */
-    public function getDbHost()
-    {
-        return $this->getConfigValueOrDefaultValue(self::CONFIG_KEY_DB_HOST
-            , self::DEFAULT_DB_HOST);
+        $this->warnAboutObsoleteConfigKeys();
     }
 
-    /**
-     * @return int db port to connect to
-     */
-    public function getDbPort()
+    public function warnAboutObsoleteConfigKeys()
     {
-
-        $defaultPortForCurrentDb = ($this->getDbType() === 'mariadb')
-        ? self::DEFAULT_MARIADB_PORT
-        : self::DEFAULT_POSTGRESQL_PORT;
-
-        return $this->getConfigValueOrDefaultValue(self::CONFIG_KEY_DB_PORT
-            , $defaultPortForCurrentDb);
+        $obsolete_keys = array("db_type", "db_host", "db_port", "db_name", "mariadb_charset");
+        foreach ($obsolete_keys as $key) {
+            // not using getConfigValueOrFalse() here, because we want to also catch empty strings
+            if (array_key_exists(key: $key, array:$this->appConfiguration)) {
+                $this->logger->warning("The configuration key '{$key}' is obsolete since "
+                    . "version 2.0.0. It has no effect and can be removed.");
+            }
+        }
     }
 
     /**
-     * @return string db name to connect to
+     * @return string dsn to use for db connection
+     * @throws \UnexpectedValueException
      */
-    public function getDbName()
+    public function getDsn()
     {
-        return $this->getConfigValueOrThrowException(self::CONFIG_KEY_DB_NAME);
+        return $this->getConfigValueOrThrowException(self::CONFIG_KEY_DSN);
     }
 
     /**
      * @return string db user to connect as
      */
     public function getDbUser()
     {
-        return $this->getConfigValueOrThrowException(self::CONFIG_KEY_DB_USER);
+        return $this->getConfigValueOrFalse(self::CONFIG_KEY_DB_USER);
+    }
+
+    // Used instead of getDbPassword() when only needs to check if `db_password`
+    // and not `db_password_file` or password in DSN is set.
+    public function dbPasswordInConfigIsSet() : bool {
+        return $this->getConfigValueOrFalse(self::CONFIG_KEY_DB_PASSWORD) !== false;
     }
 
     /**
@@ -147,24 +115,17 @@ public function getDbUser()
      */
     public function getDbPassword()
     {
-
         $password = $this->getConfigValueOrFalse(self::CONFIG_KEY_DB_PASSWORD);
         $passwordFilePath = $this->getConfigValueOrFalse(self::CONFIG_KEY_DB_PASSWORD_FILE);
 
         $passwordIsSet = $password !== false;
         $passwordFileIsSet = $passwordFilePath !== false;
 
-        if ($passwordIsSet === $passwordFileIsSet) { // expression is a "not XOR"
-            throw new \UnexpectedValueException('Exactly one of ' . self::CONFIG_KEY_DB_PASSWORD . ' or ' . self::CONFIG_KEY_DB_PASSWORD_FILE . ' must be set (not be empty) in the config.');
-        }
-
-        if ($passwordIsSet) {
-            $this->logger->debug("Will use db password specified directly in config.php.");
-            return $password;
-        }
-
+        // Password from file (db_password_file) has higher priority than password from config (db_password).
         if ($passwordFileIsSet) {
-            $this->logger->debug("Will use db password stored in file " . $passwordFilePath) . ".";
+            $this->logger->debug("Will read db password stored in file " . $passwordFilePath)
+            . ". Password from config file will not be considered. Password from DSN still has "
+            ."priority.";
             $error_message_prefix = "Specified db password file with path {$passwordFilePath}";
 
             if (!file_exists($passwordFilePath)) {
@@ -189,17 +150,19 @@ public function getDbPassword()
             fclose($file);
             $this->logger->debug("Successfully read db password from file " . $passwordFilePath) . ".";
             return trim($first_line);
+        } elseif ($passwordIsSet) {
+            $this->logger->debug("Will read db password specified in config.php. Password from file"
+            ." was not specified. Password from DSN still has priority.");
+            return $password;
+        } else {
+            return false;
         }
 
-    }
+        // Priority of password in the DSN over both passwords read here is
+        // implemented in the PDO implementation of PHP. It will simply ignore
+        // the password given as a parameter during PDO object creation and use
+        // the one from the DSN, if the DSN contains it.
 
-    /**
-     * @return string charset for mariadb connection
-     */
-    public function getMariadbCharset()
-    {
-        return $this->getConfigValueOrDefaultValue(self::CONFIG_KEY_MARIADB_CHARSET
-            , self::DEFAULT_MARIADB_CHARSET);
     }
 
     /**
@@ -219,23 +182,6 @@ public function getHashAlgorithmForNewPasswords()
                 . 'to ' . $hashAlgorithmFromConfig . '. This value is invalid. Only '
                 . 'md5, sha256, sha512, bcrypt, argon2i and argon2id are supported.');
         }
-
-        if ($normalizedHashAlgorithm === 'argon2i'
-            && version_compare(PHP_VERSION, '7.2.0', '<')) {
-            throw new \UnexpectedValueException(
-                'You specified Argon2i as the hash algorithm for new '
-                . 'passwords. Argon2i is only available in PHP version 7.2.0 and'
-                . ' higher, but your PHP version is ' . PHP_VERSION . '.');
-        }
-
-        if ($normalizedHashAlgorithm === 'argon2id'
-            && version_compare(PHP_VERSION, '7.3.0', '<')) {
-            throw new \UnexpectedValueException(
-                'You specified Argon2id as the hash algorithm for new '
-                . 'passwords. Argon2id is only available in PHP version 7.3.0 and'
-                . ' higher, but your PHP version is ' . PHP_VERSION . '.');
-        }
-
         return $normalizedHashAlgorithm;
     }
 
@@ -289,6 +235,8 @@ public function getQueryCreateUser()
         return $this->getQueryStringOrFalse(self::CONFIG_KEY_CREATE_USER);
     }
 
+
+
     /**
      * Tries to read a config value and throws an exception if it is not set.
      * This is used for config keys that are mandatory.
@@ -364,16 +312,6 @@ private function getQueryStringOrFalse($configKey)
         return $this->getValueOrFalse($queryArray[$configKey] ?? false);
     }
 
-    /**
-     * @param $dbType string db descriptor to check
-     * @return bool whether the db is supported
-     */
-    private function dbTypeIsSupported($dbType)
-    {
-        return $dbType === 'postgresql'
-            || $dbType === 'mariadb';
-    }
-
     /**
      * Checks whether hash algorithm is supported for writing.
      * @param $hashAlgorithm string hash algorithm descriptor to check
@@ -400,4 +338,5 @@ private function normalize($string)
     {
         return strtolower(preg_replace("/[-_]/", "", $string));
     }
+
 }