[Bug] matomo-console core:update crashes when no database config data is set yet

[osnyx]

What happened?

Since 55b28a4, the config.ini.php is already created before the installer process has been completed. While it contains the database config and credentials after successful installer setup, it just looks lie this after opening the web installer page for the first time:

; <?php exit; ?> DO NOT REMOVE THIS LINE
; file automatically generated or modified by Matomo; you can manually override the default values in global.ini.php by redefining them in this file.
[General]
installation_first_accessed = 1736849085

What should happen?

The matomo-console command should not just crash without any further information.
What exactly should happen instead is a decision to be made:

• option 1: command succeeds, because when there is no database to be accessed, there are also no migrations to be done on it
• option 2: fail with a non-zero exit code, but also provide proper output on the actual issue (e.g. unable to connect to database), as not having a database is also a very unexpected condition when attempting to execute database migrations

How can this be reproduced?

When trying to run all potentially available database migrations via matomo-console core:update --yes, the command crashes with an exception due to failing to create a PDO connection:

matomo-console core:update --yes
Executing possibly pending database updates...
ERROR     [2025-01-14 10:55:26] 158861  Uncaught exception: /var/lib/matomo/share/libs/Zend/Db/Adapter/Pdo/Abstract.php(144): SQLSTATE[HY000] [2002] No such file or directory [Query: , CLI mode: 1]
In Abstract.php line 144:

  SQLSTATE[HY000] [2002] No such file or directory

In Abstract.php line 124:

  SQLSTATE[HY000] [2002] No such file or directory

core:update [--yes] [--skip-cache-clear]

using the following config.ini.php:

; <?php exit; ?> DO NOT REMOVE THIS LINE
; file automatically generated or modified by Matomo; you can manually override the default values in global.ini.php by redefining them in this file.
[General]
installation_first_accessed = 1736849085

Matomo version

5.2.0

PHP version

8.2.27

Server operating system

NixOS 24.11

What browsers are you seeing the problem on?

No response

Computer operating system

No response

Relevant log output

Validations

• Read our Contributing Guidelines.
• Follow our Security Policy.
• Check that there isn't already an issue that reports the same bug to avoid creating duplicates.
• The provided steps to reproduce is a minimal reproducible of the Bug.

[randy-innocraft]

Hi @osnyx. Thank you for creating the issue and bringing this to our attention, that's very appreciated. We have reviewed and triaged the problem internally, and we have confirmed it is an issue. Our team will prioritise this, and we will update you on the progress here when we have an update to share. If you have any further information or questions, please feel free to add them here.

[michalkleiner]

Hi @osnyx, can you please confirm what the use case is for you when you're trying to run the update command on an instance that's not been properly installed?

[osnyx]

@michalkleiner Thanks for the reminder, I needed to open a downstream issue first for this.

In the NixOS management code for Matomo, we automatically run all potentially available migrations each time before the phpfpm service is started, in case the package got updated in the meantime. https://github.com/NixOS/nixpkgs/pull/373894/files#diff-0e03d462952788d52d6acdff42ce7fee0ae7cee01087e823c2522fe9eb0f68e9R185

We used to rely on the existence of a config.ini.php as a sign that the Matomo installer had been completed. As that file is now already created by just opening the installer page without completing it, that execution guard was not sufficient and ran the matomo console without any db config being present. As a workaround, we're now also checking for the existence of a [database] INI section.

As I wrote above, I am fine with migrations either suceeding or properly failing in the case of non-existent DB config. As long as I know the intended behaviour, I can adjust the downstream NixOS management code accordingly. It's just that the current crash behaviour with an everything-but-clear error message does not look very intentional.