Coldbox and VueJS untangled

Commandbox-migrations and SQL server

Cfmigrations is a nice tool to describe database changes and version them with your application code. It comes in two flavours as a forgebox package: cfmigrations if you want to manage your database changes from within you application and commandbox-migrations if you want to do the same from within commandbox. Actually the commandbox version is just a wrapper around cfmigrations. The forgebox description gives a nice overview how to use this tool.

How to use: some MSSQL and java problems

So why this post, if the manual is already there? Because it doesn’t always work out of the box, and you have to know how to use this tool in commandbox. So let’s start.
First we are going to install commandbox-migrations. Start up commandbox in your homedir and execute

install commandbox-migrations

If you want to start using migrations, you have to initialize it. This will not do any database activity yet, it just creates the right keys in your box.json.

migrate init

The following entry will be created in your box.json


Save yourself some trouble and change your default grammar immediately, because the Autodiscover probably doesn’t work within commandbox. Your options (as documented here) are: MSSQLGrammar, MySQLGrammar, OracleGrammar and PostgresGrammar. We choose MSSQLGrammar. As you can see from the box.json, most options are populated with environmental variables instead of real values (the values surrounded by ${} ). This is a good practice so your credentials don’t end up in you code, and you probably need different values for development and production. To use environmental variables in your commandbox environment you can install the commandbox-dotenv package. Now you can create your environmental variables in a file called .env in your root directory. Please make sure you exclude this file from version control!!!

Now you need to set your environmental variables DB_PASSWORD, DB_USER, DB_SCHEMA, DB_CONNECTIONSTRING and DB_CLASS. Values for password and user are obvious, but what about the other values? In my environment I can leave the DB_SCHEMA empty, but I need values for DB_CONNECTIONSTRING and DB_CLASS. If you don’t know these values yet, you can find these values by creating a a datasource in your Lucee Admin. If you edit this datasource, you will find some useful info at the bottom of this screen, like this

datasource properties

So I entered all values for the Microsoft driver in my .env file and tried to install the tables necessary for cfmigrations (by default called cfmigrations. I executed this:

migrate install

This will NOT work. You have to reload commandbox first, to retrieve your added (or changed) environmemtal variables. You can do this just by executing the command reload. If you forget to reload, you will probably get a java.lang.NullPointerException. But after reloading and trying to create a valid MSSQL connection we will enter Microsoft/Java problem territory

The driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption. Error: “

For some reason the Microsoft driver is not very cooperative in a commandbox environment, although I have no issues when used in my Lucee server. The commandbox gitbook manual has some info on hitting databases from commandbox: and indeed:

Microsoft SQL Server Issues
If you are getting SSL related exceptions when trying connecting to an MS SQL database using the Microsoft SQL Server (JDBC4) driver (, try using the jTDS driver (net.sourceforge.jtds.jdbc.Driver) instead.

So, that’s really a waste of time if you try to use cfmigrations with SQLServer for the first time! Actually I ‘ve used it a zillion times with older versions of commandbox back in the Lucee 4.5 days without any problems. But hey, problem solved! I changed my settings in .env and reloaded commandbox

jtds instead of the microsoft driver

If I execute migrate install again, cfmigrations is ready for some real database modifications, which I will describe in a later post.

Cfmigrations really is a very handy tool. It is nice if you can reconfigure your database tables directly from commandbox, but you really need some extra info in advance, such as:

  • how to work with commandbox-dotenv
  • why is a SQL driver misbehaving in a commandbox environment, and more important: how to avoid this by using the jTDS driver.

I am sure the process is a lot easier with some other databases, but I hope this write-up helps. If you really want to avoid all the trouble in configuring your database, you can also use cfmigrations from within your application, where you have your datasource already available.

Internationalization (i18n) in a ColdBox REST API

When developing a ColdBox REST API we wanted to add multilingual capacities. Coldbox has a nice module cbi18n for this.  When you set a new locale using


this locale will usually be saved in a cookie and sent back with every request. But for our REST API we are looking for a more standard way of content-negotiation. We want to set an Accept-language header on every request and return a Content-Language header for one of our supported languages. The Accept-language can contain multiple choices, and each choice can have language, country and a q factor which specifies a preference. Example:

Accept-Language: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5

In our case we are only serving two languages, English (en) and Dutch (nl) which is the default if no header is specified. So, in our header we need to find out which language (nl, en or something else) is requested and if it is not Dutch (nl) we serve English. In a later stage we might add German for some customers but for now these two languages are sufficient.

Coldbox interceptors are the perfect vehicle for this kind of logic. We define a LanguageInterceptor which has the following code:

// Language interceptor
	property name = "i18n"				inject="i18n@cbi18n";
	void function configure(){

	function preProcess( event, interceptData, buffer, rc, prc ) {
		var languageHeader =event.getHTTPHeader( "Accept-Language", "nl" );
		// get first language from comma separated list
		//cleanup for potential ;q weighting factor
		//plus cleanup for potential - dash separator
		var firstLanguage = listFirst(listFirst(listFirst(languageHeader),";"),"-");
		var newLocale = ( firstLanguage == "nl") ? "nl_NL" : "en_US";
		var contentLanguage = ( firstLanguage == 'nl') ? "nl-NL" : "en-US";
		event.setHTTPHeader( name = "Content-Language", value = contentLanguage );

As you can see from the listfirst/listfirst/listfirst line, there is some parsing involved, because there might be multiple language entries separated by a comma. Each of these entries could have a q factor appended (after a ; character) and finally there might be a country designation after a . So finally we end up with nl, en or something else. Coldfusion locales are formattet as nl_NL or en_US for example, and in the Content Language returned everything should be formatted with a dash instead of an underscore.

Finally, don’t forget to register your interceptor in Coldbox.cfc or your ModuleConfig.cfc!

© 2019

Theme by Anders NorenUp ↑