Ant configuredatabase task reference

Reference information for the configuredatabase Ant task. This reference information is for relational databases only. It does not apply to Cloudant®.

Overview

Note: In MobileFirst Server V7.1.0, the reports database (WLREPORT) is deprecated. Use Operational analytics instead. Note that setting up the reports database is optional in this release and earlier releases.
The configuredatabase Ant task creates the relational databases that are used by MobileFirst Administration Services, the MobileFirst runtime, and the Application Center Services. This Ant task configures a relational database for a MobileFirst project, or the Application Center Services, through the following actions:
  • Checks whether the MobileFirst tables exist and creates them if necessary.
  • If the tables exist for an older version of IBM MobileFirst™ Platform Foundation, migrates them to the current version.
  • If the tables exist for the current version of IBM MobileFirst Platform Foundation, does nothing.
In addition, if one of the following conditions is met:
  • The DBMS type is Derby.
  • An inner element <dba> is present.
  • The DBMS type is DB2®, and the specified user has the permissions to create databases.
Then, the task can have the following effects:
  • Create the database if necessary (except for DB2, Oracle 12c, and Cloudant).
  • Create a user, if necessary, and grants that user access rights to the database.
Note: The configuredatabase Ant task has not effect if you use it with Cloudant.
In IBM® Worklight Foundation V6.2.0, a new database was introduced, which is referenced with kind WorklightAdmin for Administration Services. This database can support one MobileFirst runtime or more, and can handle the artifacts of those MobileFirst runtimes.
Important: If you upgrade from an IBM Worklight version earlier that V6.2.0, you must also migrate the data from the IBM Worklight runtime to the new database for MobileFirst Administration Services. IBM Worklight Foundation V6.2.0 introduced a new element, admindatabase, for this purpose, as shown in Table 2.

Attributes and elements for configuredatabase

The configuredatabase task has the following attributes:
Table 1. Attributes for the configuredatabase Ant task
Attribute Description Required Default
kind Type of database:

In MobileFirst Server: Worklight, WorklightReports, or WorklightAdmin

In Application Center: ApplicationCenter

 Yes None

IBM MobileFirst Platform Foundation V7.1.0 supports four kinds of database: MobileFirst runtimes use Worklight and WorklightReports databases. MobileFirst Administration Services use the WorklightAdmin database. Application Center uses the ApplicationCenter database.

The configuredatabase task supports the following elements:
Table 2. Inner elements for the <configuredatabase> Ant task
Element Description Count
derby Parameters for Derby 0..1
db2 Parameters for DB2 0..1
mysql Parameters for MySQL 0..1
oracle Parameters for Oracle 0..1
driverclasspath JDBC driver class path 0..1
admindatabase Parameters for migrating data from IBM Worklight V6.1.x runtime to IBM MobileFirst Platform Foundation V7.1.0 Administration Services database 0..1
For each database type, you can use a <property> element to specify a JDBC connection property for access to the database. The <property> element has the following attributes:
Table 3. Attributes for the <property> element
Attribute Description Required Default
name Name of the property Yes None
value Value for the property Yes None

Attributes and elements for admindatabase

Use the <admindatabase> element for migrating data from a MobileFirst runtime database to the MobileFirst Administration Services database. This element is mandatory when you migrate your IBM Worklight runtime projects from V6.1.x and the kind attribute of configuredatabase is Worklight.

The admindatabase element has the following attribute.
Table 4. Attribute for the <admindatabase> element
Attribute Description Required Default
runtimeContextRoot Context root of the MobileFirst runtime Yes None
Because the MobileFirst Administration Services can handle one or more MobileFirst runtimes, you must reference a specific context root for each runtime. Use the runtimeContextRoot attribute to specify this context root. After MobileFirst data is migrated, you cannot change the context root of the MobileFirst runtime, unless the MobileFirst Administration Services database is removed and a new database is created.
The <admindatabase> element supports the following elements.
Table 5. Inner elements for the <admindatabase> element
Element Description Count
derby Parameters for Derby 0..1
db2 Parameters for DB2 0..1
driverclasspath JDBC driver class path 0..1
mysql Parameters for MySQL 0..1
oracle Parameters for Oracle 0..1

Apache Derby

The <derby> element has the following attributes:
Table 6. Attributes for the <derby> element
Attribute Description Required Default
database Database name No WRKLGHT, WLREPORT, WLADMIN, or APPCNTR, depending on kind.
datadir Directory that contains the databases Yes None
schema Schema name No WORKLIGHT, WORKLIGHT, WLADMINISTRATOR, or APPCENTER, depending on kind
The <derby> element supports the following elements:
Table 7. Inner elements for the <derby> element
Element Description Count
property JDBC connection property 0..

For the available properties, see Setting attributes for the database connection URL.

DB2

The <db2> element has the following attributes:
Table 8. Attributes for the <db2> element
Attribute Description Required Default
database Database name No WRKLGHT, WLREPORT, WLADMIN, or APPCNTR, depending on kind
server Host name of the database server Yes None
port Port on the database server No 50000
user User name for accessing databases Yes None
password Password for accessing databases No Queried interactively
instance Name of the DB2 instance No Depends on the server
schema Schema name No Depends on the user

For more information about DB2 user accounts, see DB2 security model overview.

The <db2> element supports the following elements:
Table 9. Inner elements for the <db2> element
Element Description Count
property JDBC connection property 0..
dba Database administrator credentials 0..1

For the available properties, see Properties for the IBM Data Server Driver for JDBC and SQLJ.

The inner element <dba> specifies credentials for database administrators. This element has the following attributes:
Table 10. Attributes for the <dba> element for DB2 databases
Attribute Description Required Default
user User name for accessing database Yes None
password Password or accessing database No Queried interactively

The user that is specified in a <dba> element must have the SYSADM or SYSCTRL DB2 privilege. For more information, see Authorities overview.

The <driverclasspath> element must contain JAR files for the DB2 JDBC driver and for the associated license. You can retrieve those files in one of the following ways:
  • Download DB2 JDBC drivers from the DB2 JDBC Driver Versions page
  • Or fetch the db2jcc4.jar file and its associated db2jcc_license_*.jar files from the DB2_INSTALL_DIR/java directory on the DB2 server.

You cannot specify details of table allocations, such as the table space, by using the Ant task. To control the table space, you must use the manual instructions in section Configuring the DB2 databases manually.

MySQL

The element <mysql> has the following attributes:
Table 11. Attributes for the <mysql> element
Attribute Description Required Default
database Database name No WRKLGHT, WLREPORT, WLADMIN, or APPCNTR, depending on kind
server Host name of the database server Yes None
port Port on the database server No 3306
user User name for accessing databases Yes None
password Password for accessing databases No Queried interactively

For more information about MySQL user accounts, see MySQL User Account Management.

The <mysql> element supports the following elements:
Table 12. Inner elements for the <mysql> element
Element Description Count
property JDBC connection property 0..
dba Database administrator credentials 0..1
client The host that is allowed to access the database 0..

For the available properties, see Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J.

The inner element <dba> specifies database administrator credentials. This element has the following attributes:
Table 13. Attributes for the <dba> element for MySQL databases
Attribute Description Required Default
user User name for accessing databases Yes None
password Password for accessing databases No Queried interactively

The user that is specified in a <dba> element must be a MySQL superuser account. For more information, see Securing the Initial MySQL Accounts.

Each <client> inner element specifies a client computer or a wildcard for client computers. These computers are allowed to connect to the database. This element has the following attributes:
Table 14. Attributes for the <client> element for MySQL databases
Attribute Description Required Default
hostname Symbolic host name, IP address, or template with % as a placeholder Yes None

For more information about the hostname syntax, see Specifying Account Names.

The <driverclasspath> element must contain a MySQL Connector/J JAR file. You can download that file from the Download Connector/J page.

Alternatively, you can use the <mysql> element with the following attributes:
Table 15. Alternative attributes for the <mysql> element
Attribute Description Required Default
url Database connection URL Yes None
user User name for accessing databases Yes None
password Password for accessing databases No Queried interactively
Note: If you specify the database with the alternative attributes, this database must exist, the user account must exist, and the database must already be accessible to the user. In this case, the configuredatabase task does not attempt to create the database or the user, nor does it attempt to grant access to the user. The configuredatabase task ensures only that the database has the required tables for the current MobileFirst Server version. You do not have to specify the inner elements <dba> or <client>.

Oracle

The element <oracle> has the following attributes:
Table 16. Attributes for the <oracle> element
Attribute Description Required Default
database Database name, or Oracle service name
Note: You must always use a service name to connect to a PDB database.
 No ORCL
server Host name of the database server Yes None
port Port on the database server No 1521
user User name for accessing databases. See the note under this table. Yes None
password Password for accessing databases No Queried interactively
sysPassword Password for the user SYS No Queried interactively if the database does not yet exist
systemPassword Password for the user SYSTEM No Queried interactively if the database or the user does not exist yet
Note: For the user attribute, use preferably a user name in uppercase letters. Oracle user names are generally in uppercase letters. Unlike other database tools, the configuredatabase Ant task does not convert lowercase letters to uppercase letters in the user name. If the configuredatabase Ant task fails to connect to your database, try to enter the value for the user attribute in uppercase letters.

For more information about Oracle user accounts, see Overview of Authentication Methods.

The <oracle> element supports the following elements:
Table 17. Inner elements for the <oracle> element
Element Description Count
property JDBC connection property 0..
dba Database administrator credentials 0..1
For information about the available connection properties, see Class OracleDriver.
The inner element <dba> specifies database administrator credentials. This element has the following attributes:
Table 18. Attributes for the <dba> element for Oracle databases
Attribute Description Required Default
user User name for accessing databases Yes None
password Password for accessing databases No Queried interactively

The <driverclasspath> element must contain an Oracle JDBC driver JAR file. You can download Oracle JDBC drivers from JDBC, SQLJ, Oracle JPublisher and Universal Connection Pool (UCP).

You cannot specify details of table allocation, such as the table space, by using the Ant task. To control the table space, you can create the user account manually and assign it a default table space before running the Ant task. To control other details, you must use the manual instructions in section Configuring the Oracle databases manually.

Alternatively, you can use the <oracle> element with the following attributes:
Table 19. Alternative attributes for the <oracle> element
Attribute Description Required Default
url Database connection URL Yes None
user User name for accessing databases Yes None
password Password for accessing databases No Queried interactively
Note: If you specify the database with the alternative attributes, this database must exist, the user account must exist, and the database must already be accessible to the user. In this case, the task does not attempt to create the database or the user, nor does it attempt to grant access to the user. The configuredatabase task ensures only that the database has the required tables for the current MobileFirst Server version. You do not have to specify the inner element <dba>.
Parent topic: Reference