1. DB Best Documentation
  2. Migration Platform
  3. Object mapping

Object mapping

Object Mapping tab in the Mapping module contains the rules defining how the DB Best Migration Platform creates potential matching pairs in the source and target metadata trees. Object Mapping also enables the correct performance of the platform commands and modules.

Default rules

The Object Mapping module consists of two components:

  • Objects mapper — that provides a general mapping algorithm, and
  • Mapping rules — a set of rules, specific for the current source and target dialects, responsible for matching objects of certain types.

The DB Best Migration Platform utilizes Object Mapping across all its modules:

  • Data Migration module — utilizes object mapping to match the data migration pairs.
  • Schema Comparison module — utilizes object mapping to match the pairs of compared objects.
  • Data Comparison module — utilizes object mapping to match the pairs of objects in the Data Comparison module.
  • Test Organizer module — utilizes object mapping to match the pairs of tested objects when a test is created.
  • Schema Conversion module — utilizes object mapping to match the schemas/databases to perform the Convert schema operation.

Mapping rules

The Object Mapping module has a set of rules to define the process of matching the names of converted database objects to the original objects and vice versa.

There is a set of default rules and you can also set custom rules. The mapping rules are executed consequently, according to the Apply order. To configure the mapping rules, use the Naming Patterns.

Naming pattern (convention)

Naming patterns (Naming convention) provide a combination of wildcard groups that describe object names, and how the source object name relates to the target object name and vice versa.

  • % — a special symbol that describes the following letter or symbol (almost equivalent to [\w]* in regular expressions)
  • %d — wildcard group (where d is a number) represents a named part of a string, can be used to reference a string part from another naming pattern

Example: Full name Schema.Package.Obj means %1.%2.%3, so if you want to reference Schema.Package$Obj, the corresponding name pattern is: %1.%2$%3

Apply order

Every mapping rule has its Apply order number. The rules are applied consistently according to the order (Figure 1).

You can change the Apply order manually. For that, drag-and-drop the rule to the required place.

When the object appears on the opposite side, the mapping process stops. If the current rule can’t find the object, the next rule is applied until the matching is complete or no more rules left. If mapping can’t find a suitable object, the top metadata object (Server) is selected in the opposite tree.

Note: The rules are applied consistently, so consider placing extraordinary cases in the beginning.

Figure 1. Apply order

Figure 1. Apply order

​​Default rules

Default rules simplify and speed up the process of mapping.

The set of default rules includes the default schema matching rule, default package matching rule, and common sense rules. Figure 2 represents the visible default rules in the current implementation.

Figure 2. Default rule

Figure 2. Default rules

Default schema matching

The default schema matching rule (Order 1, Figure 2) maps schema A from the source to the target schema dbo, which is inside the database A. The rule is applicable for schemas where the source name is like % to the target name like %.dbo.

Example:

  • AutoTest -> AutoTest.dbo
  • TestSchema -> TestSchema.dbo (in this case we have database on the target TestSchema)

Default package matching

The default package matching rule (Orders 2 – 5, Figure 2) maps the source procedure to the target procedure. The rule ()  is applicable for schema package objects where the source name is like Schema.Package.Object to target name like Schema.dbo.Package$Object.

Example:

  • AutoTest.TestPackage.SomeProcedure -> AutoTest.dbo.TestPackage$SomeProcedure
  • TestSchema.PackageName.Function -> TestSchema.dbo.PackageName$Function

Note: The rules  operates the same logic but differ in the types of source and target objects. This separation allows you to disable a rule for certain types.

Common rules

The Object Mapping module operates a set of common-sense rules that are not displayed on the Object Mapping rules tab.

However, you should rely on them to apply the functionality correctly:

Rules applicable to all objects: 

  1. Objects which names differ in one/two symbols are matched.
  2. Filters match objects by logical compatibility.
  3. Filters match objects by name.
  4. Objects are matched by case-sensitive names.
  5. Objects are matched by name inside parent candidates.
  6. Resolve false-positive schema matches to both: schema and database.

The rule applicable to procedures: 

  1. Functions match routines using their parameters.

Custom rules

You can create your custom rules to simplify the process.

  1. Click the Add button (Figure 3) in the Object mapping rules window.
Figure 3. Add button on Object mapping rules tab

Figure 3. Adding a new rule

Figure 4. New mapping rule tab

Figure 4. New mapping rule window

  1. In the New mapping rule window (Figure 4), specify the name of the rule, the type of objects where the rule applies, and the source and target objects.
  2. Click Create to save a new rule

Disabling rules

You can disable the rules, and they won’t apply during the mapping process. To do so, move the switcher in the status field (Figure 5).

Figure 5. Status of rules

Figure 5. Rules’ statuses

Removing rules

To remove custom rules, check the necessary rules and click the Remove button.

Note: You can remove only the custom rules.

Didn’t find the answer?

You can report problems, ask questions or share ideas for improvements on our email [email protected].