Chapter 4Database and services
This chapter is for the support technician and the laboratory's IT administrator. It sets out:
- what runs on the server after installation: the database, the program and the scheduled tasks;
- how the program starts, and how to stop and restart it without harming anything;
- how to check the database's health, and what to do when it does not run.
4.1 What runs on the server
| Name in Windows | Kind | What it is | When it starts |
|---|---|---|---|
ClarusPrimePostgres | Windows service | The PostgreSQL database | With the computer, automatically |
Server in the task folder \Clarus\Clarus_prime\ | Hidden scheduled task | The program itself | At every Windows sign-in |
Updater in the same folder | Scheduled task | The update installer | A minute after the computer starts, and when the program asks for it |
Support in the same folder | Scheduled task | Carries out remote support actions | When the program asks for it |
On a member computer the task Member takes the place of Server, and there is no database. All the names are in Appendix C: Service names.
4.2 The database
Setup brings PostgreSQL 18 with it, and creates a database cluster of the laboratory's own:
| Item | Value |
|---|---|
| Port | 5439; if it is taken, Setup takes the first free port after it |
| Who can reach it | This computer alone (the address 127.0.0.1); the network never reaches it |
| Database name | clarus_lis |
| The program's account in it | clarus_lis |
| Its administrator account | postgres |
| Sign-in | With an encrypted password (SCRAM-SHA-256), even from the computer itself |
| Encoding | UTF-8 |
| Data folder | pgdata inside the program's data folder: D:\Clarus\Clarus_prime\data\pgdata or C:\ProgramData\Clarus\Clarus_prime\data\pgdata |
| Log | postgresql.log in the logs folder, rotated every 20 MB |
Setup sizes the database's memory to the computer's: an eighth of the memory for its cache, between 128 MB and 1 GB.
4.2.1 The passwords
Setup generates two random passwords: one for the administrator account and one for the program's account. It keeps them in the file cluster-superuser.json in the data folder, which only administrators and the SYSTEM account can read.
The program keeps its address for the database, with its account's password, in its configuration file clarus-lis.config.json in the program's folder.
4.2.2 A laboratory installed without administrator rights
When the program is installed for one user without administrator rights (see 2.10 Installing without administrator rights), the database is not registered as a service. Instead a sign-in task named ClarusPrime PostgreSQL starts the database when that user signs in, and only then. So after the computer restarts, nothing runs until that user signs in.
4.3 How the program starts
The program starts with no window at every Windows sign-in, through the task Server. That is on purpose: after a night-time restart for a Windows update, the analysers start their day before anyone opens the program, so it has to be listening.
When it starts, this happens in order:
- It makes sure the database is running. If the database service is stopped, it starts it and waits for it to answer, for two minutes at most.
- If it does not answer, it tries to repair it by running the database setup again, for three minutes at most.
- If it still does not answer, it stops and writes a message naming the log files
postgresql.logandpostgresql-startup.log, and the repair command to run by hand. - It prepares the laboratory. Meanwhile the program's pages answer that it is being prepared, and ask to try again in a few seconds.
- It runs, and with it the station that prints and links the analysers (see Chapter 7: Printers).
Two copies of the program never start together. If a second user signs in to Windows while the program runs, it does not start again, and the program's desktop shortcut opens its window on the copy already running.
4.4 Stopping and restarting
The safest way is always to restart the computer itself and then sign in. Windows then closes the database cleanly, and everything starts again in its order.
When the technician needs to stop the program alone without a restart, the stop script is in the program's folder:
D:\Clarus\Clarus_prime\packaging\windows\stop-clarus-lis.ps1
It stops, in order, the program first and then the database service. Run it from PowerShell with administrator rights. Then start the program again from its desktop shortcut, which starts the database before it.
4.4.1 A database running outside its service
After an update the database can be left running, but outside its registered service, so the service shows as stopped. In older versions this refused every new connection until Windows restarted. Now the database setup detects it by itself: it stops the copy running outside the service cleanly, then starts the service. If it cannot stop it, it leaves the database running and writes a warning; then restart the computer.
4.5 Checking its health
4.5.1 From the program
The Support menu has two screens:
- Health and diagnostics: the Database card with its size and integrity, and the server readiness card with the number of database connections and open sessions. Below them is the Database maintenance section.
- Server and updates: the database's kind, address and port, and the state of updates.
4.5.2 Database maintenance
In the Database maintenance section the technician measures the database's size with Measure now, and sees the last maintenance and what the server recommends. The operations are:
| Operation | What it does |
|---|---|
| Quick check | A quick check of the data's integrity |
| Integrity check | A full integrity check, longer than the quick one |
| Repair foreign keys | Repairs the links between tables if any is broken |
| Update statistics | Updates the database's statistics, so queries run faster |
| Vacuum | Recovers the space left by deleted and changed records |
| Checkpoint | Writes what is held in memory to the disk |
None runs unless the technician asks; each is recorded in the audit under their name, and none deletes a record. The database also cleans itself automatically in the background, as PostgreSQL does, so none of these is needed in ordinary use. Run Update statistics after a large migration, although the program already does it by itself after every migration from RealLab.
4.5.3 From a browser
On the server itself, the program answers two addresses the technician can open in a browser. The port is the program's port (see Appendix A: Ports):
| Address | What it says |
|---|---|
http://127.0.0.1:<port>/api/health | The program is running, and its version. It does not touch the database |
http://127.0.0.1:<port>/api/ready | The program reaches the database. If it does not, it answers with code 503 |
If the first answers and the second does not, the program runs and the database does not.
4.6 When the database does not run
| What shows | Likely cause | What to do |
|---|---|---|
| The program does not open after the server restarted | Nobody has signed in to Windows | Sign in, wait a minute, then open the program |
A message at start naming postgresql.log | The database did not start | Read the last lines of postgresql.log and postgresql-startup.log in the logs folder (see Appendix B: Paths), then restart the computer |
The service ClarusPrimePostgres is stopped and will not start | A full disk, a damaged database file, or security software blocking it | Check the free disk space first. Then read the log. Delete nothing from pgdata |
/api/health answers and /api/ready does not | The program runs and the database does not | Restart the computer. If it happens again, run the repair command from the start message, with administrator rights |
Port 5439 is taken by another program | Another program on the computer has PostgreSQL | Nothing: Setup took another port and recorded it. See the actual port in the configuration file |
| The program is slow and the database is large | Old statistics or unrecovered space | Run Update statistics and then Vacuum outside working hours |
If the database folder itself is damaged, the way back is to restore from the latest backup (see 8.9 Restoring from a backup).