Remap

Remap is a schema-migration tool that applies the current schema (defined in the deployed field and table GPAL dictionaries) to the underlying database layer.

Remap should be run in the following scenarios:

• Whenever the Genesis Server Framework or any Genesis server component has been upgraded, which could include schema changes.
• Whenever a new version of an application is deployed and any dictionary file has changed (this means changes to tables, or views GPAL).

Syntax

remap [-c | --commit]

Argument	Argument long name	Mandatory	Description	Restricted values
-f	--force	no	Forces the unlocking of a locked database	No
-c	--commit	no	Applies dictionary changes to the database	No
	--force-dao-generation	no	Forces the re-generation of DAOs on the given host	No
	--skip-dao-generation	no	Skips the re-generation of DAOs on the given host	No
	--ask-db-password	no	Prompts for a DB user password to be manually entered	No
-d	--dumpSQL	no	Outputs the SQL DDL statements to the console instead of applying them to the db	No
-m	--metadataOnly	no	Only updates the GSF dictionary and alias stores; does not apply any table changes	No
	--skip-unchanged	no	Forces remap to fail if the --commit option is used and the schema has been changed	No
	--skipTableDump	no	Skips the back-up of old data and runs much quicker; use with caution - you will not be able to roll back unless you have specifically made a full back-up	No
-dm	--dumpMode	no	Determines where the DDL statements are outputted when using --dumpSQL. The user will have the option of specifying the CONSOLE or an .sql file.	Yes: CONSOLE, FILE
	--dataLoad	no	Scans the genesis home folder for /data folders, and runs a sendIt --upsertAll operation on all the files in those folders	No
	--db-username	no	Allows the user to enter the username to override credentials via the cli. This command works with fdb and Oracle.	No
	--db-password	no	Allows the user to enter the password to override credentials via the cli. This command works with fdb and Oracle.	No

If you run remap with no arguments, it simply gives a report of changes that exist in the configuration:

==================================

Table Changes

==================================

Added ADMINISTRATOR.NAME

==================================

Field changes

==================================

No changes

==================================

Key changes

==================================

No changes

To commit the changes to the database, use the --commit argument.

note

If no changes are detected between the schema files and the current database schema, remap does not perform any further action.

How it works

For clarity, we refer here to the schema being used by the database layer as "schema" and the current file system schema as "dictionaries".

When you initially deploy your application to the platform, remap generates the schema from the dictionaries. No changes will be required, as there is no existing schema.

The next time you run remap this previously generated schema is compared with the dictionaries to find any changes.

Once it has finished the comparison, it prints the change list (see above), and if the "--commit` option was provided, it attempts to modify the current schema to match the deployed dictionaries.

Once generated, remap then re-generates code (i.e. database entities and repositories), based on the schema to ensure that the deployed application works as expected. This step can be time- and memory-consuming, and we have already implemented the option to deploy the generated code directly as part of the application package, instead of relying on remap for re-generating the code every time.

The remap command returns 0 if everything is successful, and any other number if something has gone wrong.

Additional operations

If using FoundationDB, remap will save the internal field and table aliases to the Alias Store.

Rollback

If a successful remap needs to be rolled back for any reason, you can:

• run remap again in an environment containing the previous Genesis schema files to apply the reverse changes
• use the CSV files generated during the remap process (located in $GENESIS_HOME/runtime/Remap) and reload the old data using the SendIt tool
• manually dump the database contents to CSV using DumpIt before performing remap and then recover them back using SendIt; this would have to be done as part of the CI/CD configuration
• create a database backup using native database tools (i.e. native PostgreSQL backup, native FoundationDB backup, etc.) and then use native database restore tools to return to the previous state

Capabilities

Action	Allowed
Add tables	Yes
Remove tables	Yes
Add fields to a table	Yes
Remove fields from a table	Yes
Add indices to a table	Yes
Add/Remove fields to an index	Yes
Remove indices from a table	Yes
Rename tables	Yes
Rename indices	Yes
Modify the default value of a field	Yes
Change the data type of a field	Some (See details below)

Considerations and limitations

Locks

When you run remap, the database is automatically locked to ensure that no other remap can run concurrently.

If the database crashes during a remap and the database remains locked (or if the database is locked for any other reason), run the following to unlock the database:

remap --force --commit

Transactions

Either all changes are applied or none are. In the case of databases that don't support transactional DDL (Oracle) or have transactional limitations (FoundationDB), remap clones each affected table and performs the changes on each cloned table instead of the original tables; this can add to the time it takes to perform the operation.

Data migration

Remap does not perform any complex data migration, only schema changes. Some custom steps may be required to handle more complex changes.

Field changes

Renamed fields are not supported by remap, as there is no way to identify individual fields (indices and tables are identified by an "id"). For this purpose, we have the rename fields script.

Field-type migration

As a rule, all sensible migrations are supported. However, some migrations require checks and validations, such as migrating a STRING to an ENUM type.

The following are valid without additional changes or caveats:

Original Field Type	New Field Type
Integer	Long
Integer	Float
Integer	Double
Integer	BigDecimal
Short	Integer
Short	Long
Short	Float
Short	Double
Short	BigDecimal
Long	BigDecimal
Float	Double
Enum	String
Float	BigDecimal
Double	BigDecimal
Date	DateTime
Long	Float
Long	Double

String to Enum Conversion

A common issue with type conversions is a String to Enum conversion where not all the data matches the allowed list of Enum values. Often, this mismatch is just a case of needing to capitalise the non-matching value, or add an underscore, or both. Where this is the case, you can run the FixEnumValues script, or add an installHook that calls it for you. See the section in server commands).