Intro

We’ve recently been focussed on making Waltz more welcoming to newcomers. Part of that has been through enhancing our getting-started processes with the aid of some fantastic contributions from the Waltz community. In particular:

However, in this post we wish to focus on how we are improving our documentation and taking a look at some database related process enhancements.

Database documentation

Liquibase

Beginning in Waltz 1.40 we are adding table and columns level documentation to our database definitions. To add this documentation we will be using two features of Liquibase:

An example of what this looks like for a single table (e.g. entity_hierarchy) is shown below:

liquibase

Liquibase transforms these commands to the appropriate dbms specific statements. These statements can be written to a DDL script or applied directly to the database. After applying these changes we can see the documentation is now available:

table

jOOQ Codegen

One unexpected benefit of documenting our database objects is that jOOQ is taking the table and column docs and including them in the generated code.

jOOQ

As you can see this will be a great help in the dev process, especially when dealing wit less frequently used tables and columns.

Multi Vendor Database migration support

The above screenshots were taken whilst working on the issue: Entity Hierarchy: show level of both ancestor and descendant node #5916. This issue adds a new (non-nullable) column to our entity hierarchy table to represent the level of the descendant node. We wished to ensure that Waltz correctly updates this column for any pre-existing data. The update is performed by a Liquibase task which can run arbitrary sql. However, the syntax of the update statements varies between database vendors so we need a few variants of the statement (the appropriate variant is selected by Liquibase via the dbms attribute on changesets).

jOOQ Translate

Luckily the jOOQ website has a superb page which translates SQL statement written in one dialect to another. Keen to give this a try we wrote the migration script for Postgres (1) and requested a translation to SQL Server (2). We quickly tested the resultant statement to ensure it worked and included it in our liquibase script.

jOOQ Translate

We will definitely be using this feature again as it saves so much effort. As we are heavy users of jOOQ within Waltz we have huge confidence in the ability of this tool to generate correct output even for complex statements.

Conclusion

We hope this has shown you how we are making steps to improve our development process by improving our documentation and streamlining our database migration script authoring. If you have any questions reach out to us via our GitHub issues page.