Datamodel Transformations

From a user perspective using GnuCash is a means to manage their accounting data. GnuCash manages stores this data in a specific format (our xml and sql data models). As GnuCash evolves these data models can change in response to code redesigns, new features, changing logic and even updated accounting law. When such data model changes occur it's important we provide the user with a means to transform their accounting data from to old model to the new model to ensure their data remains compatible with newer versions of GnuCash.

This page will accumulate the current mechanisms in place.

Note

while the intro above mentions 'accounting data' the scope of this page will be slightly broader. Aside from this obvious 'accounting data' GnuCash persists other information for this the underlying model may change over time. Think of user preferences (stored in GSettings or the .gcm files), report presets (collections of options to recreate reports) and perhaps others still.

With respect to data "upgradability" we aim for these general rules:

• We only support upgrades from one major release to the next. So you can jump from 4.x to 5.x in one step, but not from 3.x to 5.x. To go from 3.x to 5.x you first have to install and run 4.x in between.
• The last version of the previous stable series should be able to at least read the data from the current stable series. So 3.11 (last version in previous stable series) should be able to still read data written by 4.x but not necessarily data written by 5.x.

Accounting data

The user's primary data can be stored either in xml format or in an sql database. We support three database backends (sqlite files, MySql and PostgreSQL). Both xml and sql have data model transformation techniques but we don't use those.

Our rules to keep the user's data compatible are these:

• if a feature is added that introduces a data model change that's not compatible with previous versions of gnucash, this feature should be added in phases
  • in current stable series a feature code should be defined first. Any data file that has this feature code will no longer be opened by older versions of gnucash
  • current stable series should be adjusted such that
    1. it will never set the feature code itself
    2. it can read data that has the feature code set and hence knows how to use the new feature
    3. it doesn't have to be able to write the new feature
    4. if it can't write the new feature and the feature is a different representation of an existing feature, it can write using the old representation. In that case it should unset the feature code on writing.
  • next stable series can fully use the new feature. Each time it uses new feature it should set the feature code.

GSettings preferences

Contrary to accounting data, preferences are tied much more closely to a GnuCash installation so we can work from our general rules here.

The current rules are implemented:

• New preferences can be added at any time. Older versions will simply ignore them.
• Removing preferences is done in phases.
  1. In the current major series (N) the preference is marked for deprecation or - if another option replaces this one - for 'migration'. This is done by adding a `deprecate` or `migrate` entry in `gnucash/gschemas/prefs_transformations.xml`
  2. At the same time the GnuCash code is adjusted to no longer use the deprecated preference
  3. At the beginning of the next major series (N+1), the preferences that were marked for deprecation or migration are additionally marked as obsolete. This is done by adding an `obsolete` entry in `gnucash/gschemas/prefs_transformations.xml` in addition to the existing `deprecate` or `migrate` entry.
  4. At the beginning of the major series after that (N+2), all entries that were obsolete in major series (N+1) can now be removed, together with their associated deprecated or migrated entries. This removal happens both in `gnucash/gschemas/prefs_transformations.xml` and the relevant xyz.gschema.xml.in file.

This (slow) evolution ensures that

1. users can freely move back and forth between different GnuCash versions in the current series without losing any set preferences: no changes will be made to deprecated preferences in the stable series
2. users can safely upgrade to the next major series from any version in the current stable series: in the next major series the preferences are still defined, will be migrated if not already done so and only then reset). All this time the preference must remain defined in the gschema.xml file because of how GSettings works. If the preference is not defined, one can't migrate nor reset it.
3. users can also safely downgrade to the last version of the previous stable series: the last stable version of a previous series will never use deprecated/migrated preferences.
4. when moving from series N+1 to N+2 we can safely drop the obsolete preferences completely as we're sure they are no longer needed at all: nor for use (they haven't be in use since series N) nor for migration of obsoletion (that is guaranteed to have happened in series N+1 as users shouldn't jump straight from N to N+2).

Note

While the user won't lose preferences using this procedure, migration currently only happens once and only on upgrade, not downgrade. So if a user changes preferences in a newer version of GnuCash and then decides to install an older version, the older version will still see the old preference value (that is, until the preference gets marked obsolete). It may be possible to work out a safe way to keep old preferences in sync at least until they are obsoleted, but that's currently not implemented.

Report option name changes

There is a simple obsolete name to new name mapping in options.scm