Setting up Db2 as the build metadata database

1. Create a database for the DBB artifacts.

• Db2 for Linux, UNIX, and Windows

  As the database instance user, issue the following command:

  db2 create database DBB using codeset UTF-8 territory en PAGESIZE 8192
  

  Note: Db2 requires a PAGESIZE of 8k or larger.

• Db2 for z/OS

  When you run DBB with Db2 for z/OS, you must create a Db2 storage group and a Db2 database. You must also authorize a user to the storage group and database.

  1. Create a storage group

     CREATE STOGROUP DBBSTG VOLUMES ('*') VCAT yourHlq ;
     

     The storage group can be named something other than DBBSTG.

     yourHlq is the high-level qualifier of your Db2 files. It must exist on your system, and the DBB server JDBC user must have full access to it.

  2. Create the database

     You must create the database with UNICODE as the CCSID. The following example shows Db2 SQL create statements:

     CREATE DATABASE DBBZ001 STOGROUP DBBSTG BUFFERPOOL BP16K0 CCSID UNICODE;  
     COMMIT;
     

     You can replace the database name on the CREATE DATABASE statement with a different name. The database name is used during table creation so the script must be changed to match.

     BP16K0 is an example of the buffer pool name. On z/OS, a 16 K page size or larger is required. This buffer pool is used for creating tables. Table spaces are created in the default 16 K buffer pool, unless you selected a larger buffer pool.

  3. Authorize user access to the database

     The DBB metadata store API requires a user ID and password to access the database. Customers can either create a single builder user ID and password that all the DBB builds can use to access the database, or provide access to each developer who runs DBB topic and main branch builds. In this example, the user has the name dbbuser.

     The minimum authority to create the tables and indexes in the next step requires DBADM access to the database and USE access to the storage group.

     GRANT USE OF STOGROUP DBBSTG TO dbbuser;
     GRANT DBADM ON DATABASE DBBZ001 TO dbbuser;
     

2. Create your database tables by using the supplied scripts.

Refer to the SQL scripts located in the DBB installation on z/OS UNIX, which by default are at /usr/lpp/IBM/dbb/ddl/ for the supported databases to create the schema and tables that are used by the DBB server to store file metadata. See Clustering indexes for DBB Db2 database tables to explicitly set table index clustering in the SQL scripts.

Modify the schema and database name in the script as necessary. To change the schema name, set one or both schema properties.

• Db2 for Linux, UNIX, and Windows

As the database instance user, from the /usr/lpp/IBM/dbb/ddl directory, run the following commands to create database tables:

db2 connect to DBB  
db2 -stvf create_DB2.sql
db2 disconnect DBB

• Db2 for z/OS

  1. You can use tools such as Data Studio or SPUFI to run the script to create the database tables that are used by the DBB server to store file metadata.

  2. Use /usr/lpp/IBM/dbb/ddl/create_DB2z.sql to create the tables for Db2 for z/OS.

  3. Authorize user access to the database tables.

     The DBADM can be used with the metadata store APIs. However, the minimum authority to access the database requires DELETE, INSERT, SELECT, and UPDATE on the database tables.

  SET SCHEMA DBBZ;
  GRANT DELETE, INSERT, SELECT, UPDATE
       ON TABLE
            A_CONTENT_MAPPING,
            ARTIFACT,
            ARTIFACT_CONTENT,
            BR_ATTACHMENT_MAPPING,
            BR_PROP_MAPPING,
            BR_REPORT_DATA_MAPPING,
            BR_REPORT_MAPPING,
            BUILD_RESULT,
            BUILD_RESULT_PROPERTY,
            COL_LF_MAPPING,
            COLLECTION,
            DBB_SEQ_TABLE,
            DBB_TABLE_VERSIONS,
            LD_CATEGORIES,
            LD_LIBRARIES,
            LF_DEP_MAPPING,
            LF_LANGUAGES,
            LOGICAL_DEPENDENCY,
            LOGICAL_FILE,
            PERMISSIONS
       TO dbbuser;  
  COMMIT ;  
  

  In addition to permissions for the above tables, the DBB_ROLE_MAPPING table should have DELETE, INSERT, SELECT, and UPDATE on the database table for an administrator.

  GRANT DELETE, INSERT, SELECT, UPDATE
      ON TABLE
           DBB_ROLE_MAPPING
      TO <admuser>;  
  COMMIT ;
  

  For all the other users, the DBB_ROLE_MAPPING table should have SELECT on the database table.

  GRANT SELECT ON TABLE DBB_ROLE_MAPPING
      TO <dbbuser>;  
  COMMIT ;
  

The build result attachments, build report, and build report data are stored as BLOBs. The supplied scripts set the BLOB size to 100 M. If you anticipate attaching larger files or have an exceptionally large source code repository, you might want to consider increasing the BLOB size.

If you find that your BLOB size is too small (SQLCODE -302 from INSERT into table ARTIFACT_CONTENT) after installation, you can modify the BLOB definition, for example to 150 M, by using the following command:

alter table ARTIFACT_CONTENT alter column CONTENT_DATA set data type blob(150M)

3. Store your database drivers in an accessible location.

Get the driver and the license JAR files from your installation directory of Db2 for Linux, UNIX, and Windows or Db2 for z/OS and store them into a directory that is accessible by DBB.

• Db2 for Linux, UNIX, and Windows

Copy the db2jcc4.jar and db2jcc_license_cu.jar files from your installation directory of Db2. For example, these files are typically located in the /opt/ibm/db2/V<version>/java directory on Linux.

• Remote Db2 for z/OS

If your Db2 for z/OS installation resides on a different z/OS machine or even a different LPAR than the DBB Toolkit installation, then you need to copy the db2jcc4.jar and db2jcc_license_cisuz.jar files from your z/OS system installation directory of Db2 for z/OS to a location accessible to the DBB installation. These files are typically located in the <baseInstallDir>/jdbc/classes directory.

• Local Db2 for z/OS

If your Db2 for z/OS is already accessible to the DBB installation, then there are now additional copying steps. Add the db2jcc4.jar and db2jcc_license_cisuz.jar files from your z/OS system installation directory of Db2 for z/OS to your CLASSPATH. These files are typically located in the <baseInstallDir>/jdbc/classes directory.

4. Configure additional environment variables to support direct Db2 connections

After you have stored your available Db2 JDBC drivers in a location that is accessible to the DBB toolkit, follow the Configuring additional environment variables to support direct Db2 connections documentation to allow DBB to access them.