|
Note: Adding SQL database objects in RayPack is not only required if a new database has to be created on the later target machines of the package, but as well if SQL scripts have to run on already existing SQL databases on those target machines. SQL database objects may be used as mere database connection definition references. |
In order to add an SQL database to a packaging project, users go to the SQL Databases view of the Visual Designer mode.
With a click on the Create new... button, the options menu is displayed. Click on SQL database to invoke the New SQL Database Wizard.
Work your way through the steps of the wizard to define all required properties for the new item.
At any time, using the Next or Back buttons, which are displayed at the bottom of the wizard dialog, allows to navigate within the already processed steps.
To exit the wizard without creating a new object, use the Cancel button, also located at the bottom of the wizard dialog.
Step 1: General
Server
The physical address of the database server. This property is mandatory. It may either be defined by directly entering a string value of max. 255 characters length, or by using one of the variables available within the packaging project (e. g. a property). To trigger support for dynamic content input, users have to type an opening square bracket. The dialog for MSI formatted string input fields is displayed. Please refer to the common dialogs section for further details on how to handle this type of input control.
Instance
The instance name of the target SQL database object. If this optional value is not set, the default instance of the specified database server will be addressed.
The square brackets at the right-hand side of the input field indicate, that it is a special input field, allowing packagers to use Properties and other variable packaging project information for the value definition. Please refer to the MSI formatted string field section for further details on how to handle this typical kind of user interface control in RayPack.
Database
This mandatory field has to contain the name of the target database itself. It may neither be empty, nor exceed a length of 255 characters.
|
Tip: There are some official Microsoft recommendations regarding the restrictions database schema objects should follow. It may be handy to apply them to the database name at this point:
In SQL Server 2012, an object name can be up to 128 characters long. Non-quoted identifier names must follow these rules: •The first character must be alphanumeric, an underscore (_), an at sign (@), or a number sign (#). •Subsequent characters can include alphanumeric characters, an underscore (_), an at sign (@), a number sign (#), or a dollar sign ($). •The identifier must not be a Transact-SQL reserved word. •Embedded spaces or special characters are not allowed. Identifiers that start with an at sign (@) or a number sign (#) have special meanings. Identifiers starting with @ are local variable names. Those that start with a # are temporary table names.
Excerpt derived from SQL Server 2012 - Guide to Migrating from MySQL to SQL Server 2012. |
User
Accessing databases usually requires credentials. These have to be given in the form of a RayPack user object. To select or create a user object, click on the browse button [...] at the right-hand side of the user input field. The Select User dialog is displayed. Please refer to the Common dialogs section for further details on how to manage user data objects.
However, the user property of an SQL database object is optional, which allows packagers to define connection settings wherever and however they prefer to.
|
Be aware: User objects may very likely be used at several places within SQL database, script, and IIS management structures. When the same user item is referred to from different locations, changing the properties of that user item actually takes effect for all related objects. Please double-check the correctness of user profile changes, and make sure all related objects are still valid and operational with the modified set of properties. |
Step 2: Attributes Info
Run-time behavior
This steps allows to determine the activities performed during the several run-times of a typical Windows Installer package:
•On install
•On uninstall
•On reinstall
It is possible to independently determine if the database object should be created, dropped, or not affected at all during a specific run-time type. A typical setting would be to create the database on install, execute no action on uninstall, and create on reinstall.
Continue on error
When this checkbox is activated, errors that occur during the activities defined above do not lead to a package run-time execution to fail. It is recommended to keep it deactivated (as it is per default), if a database is vital for the operability of other package resources.
Confirm updates of existing databases
If the database already exists on the target device, activating this checkbox demands user confirmation for any action that manipulates the existing database at package run-time.
If the checkbox is not active, manipulations of existing databases will be executed without explicit user confirmation. It is highly recommended to double-check the expected and actual run-time behavior of the target package in order to prevent data loss and negative user experience.
Step 3: File Specification Info
If the SQL database object is actually used to create a new database on the package target machines, it is possible to define properties for the database files and log files:
Create File Specification
If this option is active, the following file related settings become effective and will be considered during the SQL database creation phase.
The destination of the newly created database file has to be defined by selecting one of the already given directories within the packaging project, or by creating a new one. Both procedures may be done by clicking the browse button [...] at the right-hand side of the destination folder property control item, and using the interface of the common dialog Select directory.
The name of the database file has to be given with the Microsoft SQL database standard extension *.mdf. A default name is derived from the value entered as database name, and the suffix "_DB". It is recommended to follow a definitive file name convention to prevent accidental removal or manipulation of vital resources.
The initial size of the file. The entered value may be extended with the suffixes KB, MB, and GB. If no suffix is provided, the value will be considered to be given in MB. If this optional property is not defined, a default of 1MB initial size is actually applied to the file.
When the initial file size does no longer suffice to manage the required amount of data, the growth size determines the steps for file enlargements:
•If a value is given without one of the possible suffixes KB, MB, GB, or %, the value is considered to be given in MB.
•If no value is given, the default growth step is 10%.
•A growth step may not be smaller than 64KB
•A growth step may not be larger than the max. file size (see below)
In order to prevent the database from overpopulating the parent device, it is recommended to define a maximal size for the database content. The entered value may be extended with the suffixes KB, MB, and GB. If no suffix is provided, the value will be considered to be given in MB. If this optional property is not defined, the file may grow until the available disk space is fully consumed.
Create Log File Specification
If this option is active, the following log file related settings become effective and will be considered during the SQL database creation phase.
Destination folder
See above.
File name
The name of the log file has to be given with the Microsoft SQL database standard extension *.ldf. A default name is derived from the value entered as database name, and the suffix "_DBLog". It is recommended to follow a definitive file name convention to prevent accidental removal or manipulation of vital resources.
Size
See above.
Growth size
See above.
Max size
See above.
Step 4: Summary
Use the summary page to check the correctness of the SQL database properties that were defined during the previous wizard steps.
•If all properties are set as required, click Process to finally create the SQL database item.
•If changes are due, click Back until the wizard step with the incorrect property definition(s) is displayed and make modifications as required.
Please note that changes in an early step may lead to different defaults or options in any later step. Therefore, please verify that all steps contain the desired settings whilst NEXTing to the summary page again.
Step 5: Finished
Once the new SQL database control object has been created, the wizard can be closed by using the Finish button at its lower right corner. The SQL Databases view is updated, and the list of existing items contains the newly created object at the lowest position.