A History Server lets you investigate how application data reached its current state by browsing data changes through the current MDrivenServer model; it is for teams that need operational, support, debugging, or business answers about past data.
A History Server is an MDrivenServer configured as a HistorySlave. It receives changes from one master MDrivenServer into a separate database. Before it applies the master model, it makes classes versioned. Instead of updating an existing database row, it inserts a new version and timestamps the data. The result is a history of data changes from the time history collection started until now.
What you can use it for
Use a History Server when you need to answer questions that the current production database cannot answer.
| Question | Example | What the History Server provides |
|---|---|---|
| Why is this record in its current state? | A support request says that an order status was different yesterday. | You can inspect the earlier state and subsequent changes to determine when the status changed. |
| How has data changed over time? | You need to understand how frequently a customer record changes, or how the number of records grows. | You can browse data at earlier points in time and compare it with the current state. |
| Is a reported issue caused by data, user actions, or application behavior? | A user says that data disappeared from a page. | You can investigate the evolution of the relevant data rather than relying only on a current snapshot. |
The history database is separate from the master database. It is therefore suited to temporal investigation without turning the production database into a versioned store.
How history is collected
The master MDrivenServer keeps commit packages in the MDrivenServerSynk table. A HistorySlave uses this synchronization mechanism to receive master changes after the initial database copy. Changes appear on the HistorySlave after a short delay; it is not the master database and should not be treated as an immediate, writeable copy of it.
At startup, HistorySlave mode uses the master model and makes classes versioned before evolving the separate history database. Versioned storage adds timestamps to written data and retains versions by inserting new rows rather than updating existing rows.
For the setup procedure, master prerequisites, model retrieval, and connection configuration, follow Documentation:Setting up a History slave. For a comparison of HistorySlave, ReadOnlySlave, and ReadWriteSlave modes, see Documentation:Slave and History Server.
Browse data from the perspective of today's model
History is a history of data, not a history of model definitions. You query historical data using the model definition that is current on the HistorySlave.
For example, assume that the current model contains Customer with a Status property. You can use time-aware OCL, such as oclAtTime, to inspect a customer's historical state. You can also use the temporal collection operators described in Documentation:OCLOperators allInstancesAtTime. Start the MDriven Designer prototype in history-aware mode when you need to access this data interactively.
This is most useful when the model is relatively stable: the current definition can still represent the earlier data, while the History Server supplies the earlier values.
Understand the model-change boundary
A History Server cannot reconstruct a definition that no longer exists. Keep model-definition history separately, for example in Git or another repository used for your model and code.
| Model change | Effect on historical browsing | Example |
|---|---|---|
| A new definition is added | There is no data for that definition before it was introduced. | If Customer.LoyaltyLevel is added today, historical customer states cannot contain a value for it from last year.
|
| An existing definition is removed | Data that can no longer be represented by the current definition is lost over time from the history perspective. | If a property is removed from Customer, the current model no longer provides that property when you inspect older customer versions.
|
| The definition itself must be reproduced | The History Server is insufficient on its own. | Use the model repository to retrieve the definition that was in use at the required time. |
| A complete historical data-and-definition snapshot is required | Use retained database backups, not only a History Server. | Restore a backup together with the corresponding model definition when an exact historical environment is required. |
Do not present History Server results as a complete archive of every past schema and every past value. It is a practical middle ground: it preserves the evolution of data as the current definition can express it.
Plan retention and scope
History grows because each change creates a new version. Plan retention before the database becomes too large. In one reported long-running installation, a history database that had collected data since 2016 reached 700 million rows; truncating it to three years reduced it to 70 million rows. Your growth rate depends on the amount and frequency of changed data.
You can control which data is retained at the class level:
| Tagged value | Effect | When to use it | Important limitation |
|---|---|---|---|
NoHistory=true
|
Excludes the class from History Server versioning. | Fast-changing imported reference data that you do not need to investigate historically. | Changing an existing versioned class to non-versioned is not supported. Set this from the start, or recreate the table to apply it. |
HistoryKeepWeeks=NoOfWeeks
|
Keeps history for the specified number of weeks for that class. | Data that needs a shorter retention period than business-critical records. | It can produce an incomplete historical view. An older object version may refer to an object that has already been culled, and that reference will then appear as null even though it had a value at that time.
|
For example, retaining Customer history for three years while retaining a frequently refreshed imported lookup class for only a few weeks can reduce storage. However, a historical customer version that pointed to a culled lookup object may show no linked object. Account for this before using different retention periods in reports or investigations.
The current administrative truncation action is available at admin/MasterSlave/TruncHistory3Years(156 weeks). Review what retention period your organization needs before truncating, because removed history cannot be recovered from the History Server.
Choose the right mechanism
| Need | Use |
|---|---|
| Investigate how current data evolved under the current model | A HistorySlave. |
| Recover the exact model definition used at a previous time | Model and code version control, such as Git. |
| Recover a complete past data and definition snapshot | Database backups with defined backup-retention settings, together with the corresponding definition. |
| Scale reads or reduce latency for users in another location | A normal slave-server configuration; see Documentation:Slave and History Server. |
Operational considerations
- Start history collection before the period you need to investigate. A History Server cannot create detailed historical versions for changes that occurred before its start time.
- Keep one master per MDrivenServer cluster. The master retains synchronization packages in
MDrivenServerSynkuntil they are removed according to the queue-retention setting. - When preparing a production database as the initial history database, review the existing
MDrivenServerSynkcontent. Retaining only its tip can reduce backup size and improve read and update performance for that table. - Versioning changes database constraints: one-to-one associations can have uniqueness constraints that are not valid across all points in time. The history setup process handles this when it runs
EnsureVersioningTablesInDB, which addsStartTimeandStopTimecolumns. - Monitor database growth and identify the tables with the highest row counts before deciding whether to exclude classes, shorten retention, or truncate history. Documentation:Setting up a History slave includes a SQL Server query for this analysis.