Metadata store

Build metadata is information that DBB creates and stores during the build process both for use in future build processes as well as reporting the results of a build. Beginning in DBB v2.0.0, the Liberty Web Application that was used to access the build metadata in earlier DBB versions and its corresponding RepositoryClient toolkit APIs have been replaced with the new MetadataStore toolkit APIs. These new toolkit APIs now directly access the DBB build metadata that is stored either in Db2® databases or on the z/OS® UNIX System Services (USS) file system without the need of an intermediate web application connection.

The metadata store APIs enables you to manage the dependency collections and build results created during a DBB build process. These concepts and how they are used by DBB are explained in more detail at

DBB metadata command line interface (CLI)

The DBB CLI provides simple, easy-to-use access to the DBB build metadata without the need to write and run custom DBB Groovy utility scripts. Primarily targeted for build engineers and developers who need to debug and clean up topic branch build metadata, the DBB CLI provides read and delete access to the build metadata. For more information, see Metadata store command-line interface.

Creating a metadata store connection

DBB provides the MetadataStoreFactory class in the com.ibm.dbb.metadata package, which is used to create a MetadataStore instance to connect to the back end metadata store implementation. DBB provides two metadata store implementation connections:

z/OS UNIX file system metadata store connection

DBB provides an "out of the box" implementation for early prototyping and testing DBB. The z/OS UNIX file system metadata store eliminates the need to set up an IBM Db2 database and instead stores DBB metadata and query indexes on the z/OS UNIX file system in JSON files.

IMPORTANT: NOT TO BE USED FOR PRODUCTION. It does not scale well for applications larger than 1000 source files. The Db2 metadata store is recommended when DBB is used in production.

Creating a z/OS file system metadata store connection

You simply need to enter the following command:

MetadataStore metadataStore = MetadataStoreFactory.createFileMetadataStore()

By default, this command creates a new z/OS UNIX directory at $USER/.dbb, where all of the DBB metadata will then be stored and accessed for the current user that runs the build process on z/OS UNIX.

Alternatively you can provide an alternative location:

File metadataStoreLocation = new File(/u/builder/shared/dbb/metadata")
MetadataStore metadataStore = MetadataStoreFactory.createFileMetadataStore(metadataStoreLocation)

In this case, the DBB metadata stored is created at /u/builder/shared/dbb/metadata/.dbb to allow access by other application developers on the development team. RACF® access must have been configured correctly for others to access it.

Db2 metadata store connection

DBB 2.0 now provides direct connections for storing and accessing DBB build metadata from the DBB toolkit on z/OS UNIX to either Db2 for Z and Db2 for LUW databases without the need to deploy a Liberty Web Application. Before you can use the Db2 metadata store API to store and access DBB build metadata directly on IBM Db2, some setup and configuration is required:

If you are upgrading to DBB 2.0 from a previous release of DBB and are currently using IBM Db2 for z/OS or Db2 for LUW, see Configuring additional environment variables to support direct Db2 connections, which is part of the Upgrading to DBB 2.0 documentation.
If you are new to DBB or are not currently using IBM Db2 for z/OS or Db2 for LUW, see Setting up Db2 as the build metadata database

Creating an IBM Db2 metadata store connection

The DBB MetadataStoreFactory class provides several ways to create a Db2 metadata store connection depending on how your Db2 database server is configured for client connections. Most if not all Db2 JDBC driver connections require a user ID and password. Because DBB is often run in a batch environment, a clear text password is not acceptable. If a Db2 password is required to make a secure Db2 connection, all DBB Db2 connections require the user to provide either a location of a DBB encrypted password file created by the DBB password file utility or a password string argument that has been encrypted by using the same utility.

DBB Db2 password file DBB provides a utility shell script to create an encrypted password file that can be stored on the local file system and referenced when creating a Db2 metadata store.

String url = "jdbc:db2://system1.company.com:5040/DBB1"
String id = "USER1"
File pwFile = new File("/user1/build/user1.txt")
MetadataStore metadataStore = MetadataStoreFactory.createDb2MetadataStore(url, id, pwFile)

To create a password file, complete the following tasks:

Log in to z/OS UNIX.
From a command line, navigate to the directory where you want to create the password file.
Type $DBB_HOME/bin/pwf.sh <pass.txt> where <pass.txt> can be any file name the user has access to.
When prompted, type the password. The password is encrypted and stored in the <pass.txt> file.

NOTE: Though the password file uses AES-256 bit encryption, since the encryption key is embedded in the DBB toolkit installation, it is possible that it can be identified and used to potentially decrypt the password file. Set appropriate operating system file permissions on the password file to prevent access from unauthorized users. The main benefit of using a password file is to avoid the repetition of the password in the clear in build scripts and property files.

Db2 Encrypted Password Argument The DBB MetadataStoreFactoryclass also allows you to pass in the Db2 password as a Java™ string argument instead of a password file. However, the password string needs to be encrypted by using the DBB Db2 password file utility. You can then copy the encrypted password out of the password file and store it in a CI/CD secrets store to be used in pipeline scripts.

Basic Db2 connection

As shown above, if your Db2 server is set up by using a basic configuration, DBB provides a simple way to create the connection with just the Db2 server URL, user ID, and either the location of a password file or an encrypted password string argument:

String url = "jdbc:db2://system1.company.com:5040/DBB1"
String id = "USER1"
File pwFile = new File("/user1/build/user1.txt")
MetadataStore metadataStore = MetadataStoreFactory.createDb2MetadataStore(url, id, pwFile)

Advanced configured Db2 connection

DBB also gives you full control over how to create the Db2 connection by providing APIs that allow you to pass in Db2 connection properties including advanced security mechanisms. A sample file that shows some Db2 connection configuration properties is located at $DBB_HOME/conf/db2Connection.conf.

// load the Db2 connection properties
File db2ConnectionFile = new File("/usr/lpp/IBM/dbb/conf/db2Connection.conf")
Properties db2ConnectionProps = new Properties()
db2ConnectionProps.load(db2ConnectionFile)

// create a configured connection
String id = "USER1"
File pwFile = new File("/user1/build/user1.txt")
MetadataStore metadataStore = MetadataStoreFactory.createDb2MetadataStore(id, pwFile, db2ConnectionProps)