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:

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 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.

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, 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	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. 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 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. You can download that file from the Download Connector/J page.

Alternatively, you 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 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 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. 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 you run the Ant task. To control other details, you must use the manual instructions in section Oracle database and user requirements.

Alternatively, you 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>.