Import from Database
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
This generator helps you jump-start Xomega object modeling by importing the model from an existing SQL Server database.
The generator builds the objects and fields from the corresponding database tables and columns,
declares logical types and fieldsets for object keys so that to preserve relationships between objects,
and declares reusable types for all other object fields.
Prior to running the generator though, you need to make sure you pre-configure the model as described below.
The generator takes model objects that have a configuration of the mappings between object fields and enumeration structure,
and imports enumeration data from their corresponding tables in the specified database into the model as Xomega enumerations.
Logical Types. The generator will try to map the database types to one of the existing Xomega types or,
if not possible, will define a new type that derives from one of the existing types. Therefore, before you run the import
you may want to make sure the existing types' configuration is consistent with your current system standards. For example,
the boolean type maps by default to a SQL Server type bit, as shown below.
However if the standard for your current system is tinyint to store a boolean, then you should update the Xomega type to
map to tinyint, so that it can be properly identified by the generator.
Field-sets. By the same token, the generator can identify groups of fields that match one of the field-sets
defined in the model and use a reference to the field-set instead of those fields. If all or most of your tables, for example,
have a set of standard columns, such as the user who created the record and the creation time stamp, then you can just define
such a fieldset in your model first and it will be automatically used by the imported objects.
If later on you will want to also add the user who last modified the record and the last modification time stamp, then you
could just add them to that field-set definition and they will be automatically included in all the objects that use that
field-set.
Foreign Keys for Subobjects. What you should also be cognizant of is that Xomega subobjects are inseparable
from their parent objects and require a cascading deletion whenever their parent object is deleted. As a result, for the
Import generator to define objects as subobjects, their foreign key relationship to the parent object should have cascading
deletion and the columns on both ends of the relationship should have the same names. If you would like some tables to be
imported as child objects then you may want to consider updating their foreign key relationship accordingly before the import.
You can obviously refactor the model structure after you import it, but sometimes it may be easier to make some changes in the model
or the database initially, delete the generated objects, and re-import them again.
1.2 Generator outputs
This generator creates a single or multiple .xom files with objects, fieldsets and logical types as defined by the OutputPath
parameter, and adds them to the model project.
Logical Types. For the columns where the generator cannot map the database type to one of the existing Xomega types,
it will define a new type that derives from one of the existing types, and will use it on all columns with the same type,
as illustrated below.
You can rename and refactor such types after the import to give them proper logical names, e.g. "phone number".
Key Types. For primary keys the generator will define either a simple logical type, or a fieldset,
if the key is composite with more than just parent table's key. The following snippet illustrates this setup.
For sub-objects, the primary key of the parent object will be dropped from the list of fields, as it is included implicitly.
Fixed Table Names. If you set the Keep Table Names parameter of the generator to "true", the generated
objects will have a configuration element with a sql:table element that provides a mapping to the DB table name,
as follows.
This allows renaming generated objects without worring about affecting the table name. Without such a configuration, the table
name for the object will be implicitly derived from the object's full name using specified database naming conventions (case).
Fixed Column Names. If you set the Keep Column Names parameter of the generator to "true", the fields
on generated objects will have a configuration element with a sql:column element that provides a mapping to the DB column
name, as follows.
This allows renaming generated objects' fields without worring about affecting the column name. Without such a configuration, the column
name for the field will be implicitly derived from the field's name using specified database naming conventions (case).
2. Configuration
The following sections describe configuration parameters used by the generator.
2.1 Generator parameters
The following table lists configuration parameters that are set as the generator’s properties.
| Parameter |
Value Example |
Description |
| Generator Name |
Import from Database
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
| Folder |
Model Enhancement
|
Folder path to the generator inside the Model project. The folders are separated by a backslash (\). |
| Include In Build |
False
|
A flag indicating whether or not running this generator should be included in building of the model project. |
| Output |
| Output Path |
Import/{Module/}{File}.xom |
Relative path where to output generated .xom files, which will be added to the model project.
The path may contain {Module/} and {File} placeholders to output files by database schema and table respectively.
|
| Database |
| Database |
SQL Server |
Database type of the source database. Currently only SQL Server (sqlsrv) is supported.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
| Database Version |
11.0 |
The version of the source database.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
| Database Case |
CamelCase |
The database case for the database objects' names: UPPER_CASE, lower_case or CamelCase.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
| Database Connection |
Use Project Settings |
Database connection string for the source database. Edited via a 'Database Connection Configuration' dialog,
which also sets the other Database parameters of the generator, and saving all this configuration for the entire project.
Value 'Use Project Settings' takes this value from the corresponding property of the model project.
|
| Naming Convention |
| Keep Table Names |
True |
Whether or not to preserve table names in generated objects. |
| Keep Column Names |
True |
Whether or not to preserve column names in generated objects. |
| Keep Constraint Names |
False |
Whether or not to preserve constraint names in generated objects. |
| Naming Case |
lower |
The case to use for logical names: lower, upper or camel. Leave empty to use DB names as is. |
| Naming Delimiter |
space |
The delimiter to use for logical names: space, underscore or dash. Leave empty to use DB names as is. |
2.2 Model configuration
The generator doesn't use any other configuration parameters from the model.
2.3 Common configurations
When importing the model from a database you should first of all define the database connection for the generator. You can
do it via the Database Connection Configuration dialog that pops up from the generator's Properties page. In that dialog
you should specify an OLE DB connection string to your database, which Xomega will validate and use to read your database
metadata. On the next tab of the dialog you can specify which database tables you would like to exclude from the model.
Next, the system will try to determine if your database names are case-sensitive and will set the Database Case to CamelCase
or your choice of UPPER_CASE or lower_case respectively, which will be used for generating tables for all new objects as
well.
It makes sense to save this database configuration as default project settings, which will be one of the options in the
dialog, so that all other database-related generators could reuse the same settings. This way, for example, the database
change script generator won't try to remove the tables that have been explicitly excluded from the model. If you save it
as a default configuration then it will be available in the model project's Properties page, and the corresponding generator
properties will be set to the 'Use Project Setting' value.
3. How to use the generator
The sections below provide some details on how to work with the generator.
3.1 Running the generator
You can run this generator for the entire database or for a subset of tables after configuring the database generator parameters.
The model must contain no objects defined when the generator runs to prevent overwriting any custom changes if you rerun it.
The generated Xomega files will be automatically added to the project under the folder designated by the Output Path
property. You can make it output to the project folder, but initially you may want to consider generating it in some project
sub-folder (such as the default Import/ folder). This will allow you to review the generated files, and clean them all
easily if you realize that you need to make any adjustments in the database or the configuration, and then rerun the generator.
3.2 Customizing the output
If upon review of the imported model you would like to re-import it differently, you will need to remove all of the generated
objects, make the necessary changes in the generator parameters, such as whether or not to keep table or column names, in
the model, such as defining new types or fieldsets that can be used by the import, or in the database, such as adding foreign
keys with cascade delete between parent objects and sub-objects, and then rerun the generator.
After that you can make any necessary changes directly in the model without rerunning the generator anymore.
3.3 Cleaning generator’s output
This generator does not support cleaning of the generated files. While you review the initial import of the model from the database,
you may want to output the imported objects into a dedicated folder under the model project, so that it would be easy to delete the
generated folder, make the necessary updates, and rerun the generator.