Database Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID database Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.3
Sep 05, 2013
1.509
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
n/a (id: kohsuke)
Usage Installations 2013-Apr 385
2013-May 433
2013-Jun 496
2013-Jul 531
2013-Aug 546
2013-Sep 554
2013-Oct 589
2013-Nov 613
2013-Dec 619
2014-Jan 632
2014-Feb 684
2014-Mar 736

This library plugin defines a common abstraction to connect to relational database. By doing so, it serves three purposes:

  • It allows database driver plugins (such as H2 Database Plugin) to be developed, improving the user experience for administrators.
  • It simplifies other plugins that use RDBMS by eliminating the need to code up a configuration UI to let administrators select database.

This plugin is not meant to be used by end users by itself. It's supposed to be included through the dependencies of other plugins. If you are wondering how to store your job configuration etc. in a database, the answer is that you cannot.

Usage

Abstraction

The key class in this plugin is the Database class, which acts as a holder for JDBC DataSource instance. The Database class is an extension point to be implemented by database driver plugins.

The calling code can use this DataSource instance to obtain a connection to the database.

Use the Jenkins global database

This plugin adds a system configuration entry to let the administrator configure the database used by Jenkins to store miscellaneous stuff. So the easiest way for plugins to start storing data to the database is to use this Database instance. This global database instance is kept in the GlobalDatabaseConfiguration class. You can inject this via @Inject, or you can call GlobalDatabaseConfiguration.get() to retrieve it, and then use the getDatabase() method to obtain the Database instance.

Because the database is shared by all the plugins, please use table names that include your plugin name as a prefix to avoid collisions.

Use the per-job database

In addition to the global database, this plugin also creates a database local to TopLevelItem. These databases are normally backed by embedded database that stores data under $JENKINS_HOME/jobs/NAME, and this simplifies the backup, copying, deletion of the data that's local to jobs (such as test reports, coverage data, and so on.)

This information is kept in the PerItemDatabase class, which you can obtain by PerItemDatabaseConfiguration.findOrNull().

Your own database

Sometimes it makes sense to store data to an entirely different database. A good example of this is the Jenkow Plugin, which embeds an existing 3rd party software that uses database. Users may already have a database with data in it, in which case he'd want to just connect to that.

A plugin that wants to do this should define a field whose type is Database (see example). In the config.groovy/.jelly, use the f:dropdownDescriptorSelector tag to allow the user to select a database (see example).

The database plugin contains a complete example in its src/test directory. Clone the repository and run mvn -Prun, then open http://localhost:8888/database-console/ to see this example in action.

JPA support

This plugin exposes it through JPA 2.0 API (internally, it uses Hibernate but please do not rely on this fact if you can as it may change.) The entry point to the JPA support is the PersistenceService class, and this exposes methods for obtaining EntityManagerFactory for both the global database as well as arbitrary per-item database of your choice.

Because there are several different databases, involved, @Entity annotation alone is not sufficient. For persisted classes meant for the global database, please put @GlobalTable in addition to @Entity. For the per-item database, please put @PerItemTable.

The following code shows how to use this to persiste a new row:

public class Push {
    @Inject
    PersistenceService ps;

    public void go(int n) throws IOException, SQLException {
        Jenkins.getInstance().getInjector().injectMembers(this);
        EntityManager em = ps.getGlobalEntityManagerFactory().createEntityManager();
        em.getTransaction().begin();
        TestRow row = new TestRow();
        row.buildNumber = n;
        row.x = "foo";
        em.persist(row);
        em.getTransaction().commit();
        em.close();
    }
}

@GlobalTable
@Entity
public class TestRow {
    @Id
    @Column
    public int buildNumber;

    @Column
    public String x;
}

Developing driver plugin

MySQL Database Plugin and PostgreSQL Database Plugin are good examples of typical database driver plugins. For other "unsual" drivers that doesn't use the canonical host+database+username+password+properties combo, see H2 Database Plugin source code as an example.

Add the test jar of the database plugin to your driver plugin, so that you can use the debug database console feature during mvn hpi:run. This lets you interactively test your driver plugin and its configuration screen.

Changelog

Version 1.2 (Sep 5, 2013)

  • JPA support

Version 1.1 (Dec 14, 2012)

  • initial version

Labels

Edit
plugin-database plugin-database Delete
plugin-library plugin-library Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.