CI/CD Integration

This guide explains how to integrate DBmarlin with your Continuous Integration (CI) or Continuous Deployment (CD) tools. With this integration, your CI/CD tools can send custom events directly to DBmarlin for things such as Code releases or Deployments which allows you to visualise if there was an impact on database performance resulting from it.

About CI/CD

CI and CD are two acronyms frequently used in modern development practices and DevOps. CI stands for continuous integration, a fundamental DevOps best practice where developers frequently merge code changes into a central repository where automated builds and tests run. CD can either mean continuous delivery or continuous deployment which are similar practices; the main difference being how quickly changes that pass all stages of the pipeline are deployed into production.

Integrating CI/CD tools

In some cases, different tools could be used for CI and CD. However, the same tool may be used for both. Whether you are using a single tool for both or separate tools, it makes sense to integrate DBmarlin with the one doing the deployment of code (CD) into an environment, since it is only when code has application traffic passing through it and hitting the database, that the database performance can be measured.

If you are using Jenkins or Liquibase for CI/CD then we have specific instructions you can follow. For other CI/CD tools, please follow the general instruction below which should work with any CI/CD tool.

Prerequisites

To use this guide, you should have:

1. An active DBmarlin installation.
2. A working CI/CD toolset that can make an HTTP call to the DBmarlin API.

Configure your CI/CD tool

The way you configure your CI/CD tool depends on which tool you use. Here's a general guideline:

1. All CI/CD tools should have the ability to create an HTTP action which can make an HTTP call to a API endpoint. This may be called a Webhook or other name depending on the tool you are using. If an HTTP action isn’t available directly, then an alternative is to have it run a script which would invoke a shell command such as curl or wget. These are Linux command line tools for making HTTP calls (on Windows you could use Powershell instead).

2. Within the HTTP action, you need to make a POST request to the DBmarlin's /archiver/rest/v1/event endpoint and in the body of the request send all the required information.

   • The URL endpoint will look something like this: endpoint=$dbmarlin_host/archiver/rest/v1/event where the $dbmarlin_host will be that of your DBmarlin server (usually the same as you connect to in your browser)
   • In the POST body section needs to include details about the event. This can include the event name, description, and timestamp, among other details. For example:

   [
     {
       "startDateTime": "2023-05-26T10:21:03.563Z",
       "databaseTargetId": 0,
       "eventyTypeId": 0,
       "title": "string",
       "endDateTime": "2023-05-26T10:21:03.563Z",
       "colourCode": "#00047D",
       "description": "string",
       "detailsUrl": "string"
     }
   ]
   • startDateTime - ISO formatted datetime for the event start.
   • databaseTargetId - The ID value of the database in DBmarlin. The ID can be found via API /archiver/rest/v1/datasource
   • eventyTypeId - The ID value of the event type. 'Code Release' is ID=2 by default. The ID can be found via API /archiver/rest/v1/event/type
   • title - The title of the event. You may pass variables from your CI/CD tool such as the build number or job name.
   • endDateTime (Optional) - ISO formatted datetime for the event end.
   • colourCode (Optional) - Colour code in CSS style Hex RGB format.
   • description (Optional) - More detailed description of the event. You may pass variables from your CI/CD tool such as the build number or jon name.
   • detailsUrl (Optional) - A URL the will appear in DBmarlin as a Hyperlink. This could be the build URL for example so you could click from DBmarlin back into the CI/CD tool.

3. Open API docs for the /archiver/rest/v1/event endpoint are available https://play.dbmarlin.com/archiver/rest/v1.html#/

4. The HTTP action you created, should be triggered when a new deployment occurs. Normally you would only want it to trigger on a successful deployment so you might add it as an ‘on success’ action (this may have a different name depending on which CI/CD tool you are using.)

Testing the integration

Once you've configured the CI/CD tool, it's recommended to test the integration to make sure it's working correctly. Trigger a test event from your CI/CD tool and confirm that it appears correctly in DBmarlin's interface.

Conclusion

By following these steps, you can set up your CI/CD tools to send events to DBmarlin. This integration allows you to gain a more detailed understanding of how your code deployments impact your database's performance.