Automatic database recovery
Final Release Note
Description
For MUMPS users getting started with YottaDB and using default database settings, in case the database was not cleanly shutdown, the ydb
script recovers the database before opening it. It also deletes old journal files so that they did not consume all disk space.
This enhancement aims to make database recovery automatic for users of all languages, whether built in to the core YottaDB engine (C and MUMPS) or a language accessing YottaDB through a plugin/wrapper (Go, Python, Java…).
Note that this should be implemented after [#365 (closed)] because it depends on it.
Draft Release Note
Global directory regions and database file headers contain an AutoJNL field. In the global directory, the [NO]AUTOJNL region qualifier is used to control its value (in turn, the default for the region is set from the template, and the default value in the region template with the YottaDB distribution is AUTOJNL).
When a YottaDB process is the first to open a database file with AUTOJNL set:
-
If the database was shutdown cleanly:
- If there is no journal file, it creates a journal file using values in the fileheader, or defaults for those values
- If there is journal file, it uses it.
-
If the database was not shutdown cleanly:
-
If the replication state of the database file is ON, the process issues a REQROLLBACK error.
-
If the replication state of the database file is OFF:
- If there is a valid before image journal file, the process performs a MUPIP JOURNAL RECOVER BACKWARD operation on the database file. This recovery is performed in a separate process with the output of the MUPIP process directed to the stderr of the process opening the database, and a default name for the lost transaction file. If the MUPIP process does not succeed, the database file open fails.
- If there is no valid before image journal file (which includes the case of a valid nobefore image journal file), the process issues a REQRUNDOWN error.
-
AUTOJNL aims to simplify “out of the box” YottaDB usage. When AUTOJNL is set in a multi-region database used by applications with transactions that span regions, since recovery for AUTOJNL databases is performed one database region at a time rather than across all regions of a multi-region database, the forward phase of recovery will stop at the first multi-region transaction, with subsequent output directed to the lost transaction file. Consequently, AUTOJNL is not recommended for multi-region databases used by applications with region-spanning transactions.