For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.


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

The configuredatabase Ant task creates the relational databases that are used by MobileFirst Server administration service, MobileFirst Server live update service, MobileFirst Server push service, MobileFirst runtime, and the Application Center services. This Ant task configures a relational database through the following actions:

In addition, if one of the following conditions is met:

Then, the task can have the following effects:

Note: The configuredatabase Ant task has not effect if we use it with Cloudant.


Attributes and elements for configuredatabase task

The configuredatabase task has the following attributes:

Table 1. Attributes for the configuredatabase Ant task
Attribute Description Required Default
kind The type of database:

In MobileFirst Server: MobileFirstRuntime, MobileFirstConfig, MobileFirstAdmin, or push.

In Application Center: ApplicationCenter.

Yes None
includeConfigurationTables To specify whether to perform database operations on both the live update service and the administration service or on the administration service only. The value is either true or false. No true
execute To specify whether to execute the configuredatabase Ant task. The value is either true or false. No true
kind
IBM MobileFirst Platform Foundation V8.0.0 supports four kinds of database: MobileFirst runtime uses MobileFirstRuntime database. MobileFirst Server administration service uses the MobileFirstAdmin database. MobileFirst Server live update service uses the MobileFirstConfig database. By default, it is created with MobileFirstAdmin kind. MobileFirst Server push service uses the push database.Application Center uses the ApplicationCenter database.
includeConfigurationTables

The includeConfigurationTables attribute can be used only when kind attribute is MobileFirstAdmin. The valid value can be true or false. When this attribute is set to true, the configuredatabase task performs database operations on both the administration service database and the live update service database in a single run. When this attribute is set to false, the configuredatabase task performs database operations only on the administration service database.

execute

The execute attribute enables or disables the execution of the configuredatabase Ant task. The valid value can be true or false. When this attribute is set to false, the configuredatabase task performs no configuration or database operations.

The configuredatabase task supports the following elements:

Table 2. Inner elements for the configuredatabase Ant task
Element Description Count
<derby> The parameters for Derby. 0..1
<db2> The parameters for DB2. 0..1
<mysql> The parameters for MySQL. 0..1
<oracle> The parameters for Oracle. 0..1
<driverclasspath> The JDBC driver class path. 0..1

For each database type, we 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 The name of the property. Yes None
value The value for the property. Yes None


Apache Derby

The <derby> element has the following attributes:

Table 4. Attributes for the <derby> element
Attribute Description Required Default
database The database name. No MFPDATA, MFPADM, MFPCFG, MFPPUSH, or APPCNTR, depending on kind.
datadir The directory that contains the databases. Yes None
schema The schema name. No MFPDATA, MFPCFG, MFPADMINISTRATOR, MFPPUSH, or APPCENTER, depending on kind.

The <derby> element supports the following element:

Table 5. Inner element for the <derby> element
Element Description Count
<property> The 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 6. Attributes for the <db2> element
Attribute Description Required Default
database The database name. No MFPDATA, MFPADM, MFPCFG, MFPPUSH, or APPCNTR, depending on kind.
server The host name of the database server. Yes None
port The port on the database server. No 50000
user The user name for accessing databases. Yes None
password The password for accessing databases. No Queried interactively
instance The name of the DB2 instance. No Depends on the server
schema The 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 7. Inner elements for the <db2> element
Element Description Count
<property> The JDBC connection property. 0..∞
<dba> The 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 the credentials for the database administrators. This element has the following attributes:

Table 8. Attributes for the <dba> element for DB2 databases
Attribute Description Required Default
user The user name for accessing database. Yes None
password The 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 the JAR files for the DB2 JDBC driver and for the associated license. We can retrieve those files in one of the following ways:

We cannot specify details of table allocations, such as the table space, by using the Ant task. To control the table space, we must use the manual instructions in section DB2 database and user requirements.


MySQL

The element <mysql> has the following attributes:

Table 9. Attributes for the <mysql> element
Attribute Description Required Default
database The database name. No MFPDATA, MFPADM, MFPCFG, MFPPUSH, or APPCNTR, depending on kind.
server The host name of the database server. Yes None
port The port on the database server. No 3306
user The user name for accessing databases. Yes None
password The 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 10. Inner elements for the <mysql> element
Element Description Count
<property> The JDBC connection property. 0..∞
<dba> The 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 the database administrator credentials. This element has the following attributes:

Table 11. Attributes for the <dba> element for MySQL databases
Attribute Description Required Default
user The user name for accessing databases. Yes None
password The 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 12. Attribute for the <client> element for MySQL databases
Attribute Description Required Default
hostname The 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. We can download that file from the Download Connector/J page.

Alternatively, we can use the <mysql> element with the following attributes:

Table 13. Alternative attributes for the <mysql> element
Attribute Description Required Default
url The database connection URL. Yes None
user The user name for accessing databases. Yes None
password The 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 14. Attributes for the <oracle> element
Attribute Description Required Default
database The database name, or Oracle service name.

Note: You must always use a service name to connect to a PDB database.

No ORCL
server The host name of the database server. Yes None
port The port on the database server. No 1521
user The user name for accessing databases. See the note under this table. Yes None
password The password for accessing databases. No Queried interactively
sysPassword The password for the user SYS. No Queried interactively if the database does not yet exist
systemPassword The 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 our 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 15. Inner elements for the <oracle> element
Element Description Count
<property> The JDBC connection property. 0..∞
<dba> The database administrator credentials. 0..1
For information about the available connection properties, see Class OracleDriver.

The inner element <dba> specifies the database administrator credentials. This element has the following attributes:

Table 16. Attributes for the <dba> element for Oracle databases
Attribute Description Required Default
user The user name for accessing databases. Yes None
password The password for accessing databases. No Queried interactively

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

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

Alternatively, we can use the <oracle> element with the following attributes:

Table 17. Alternative attributes for the <oracle> element
Attribute Description Required Default
url The database connection URL. Yes None
user The user name for accessing databases. Yes None
password The 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: Installation reference