Datasources

A datasource is a named connection to a specific database with specified credentials. You can define a datasource in one of three locations:

2. For web applications,

The datasource is then used to control the database's connection pool and allow the BoxLang engine to execute JDBC calls against it.

What Database Vendors Are Supported?

The following database vendors are supported and available:

Each database we support comes with an installable BoxLang module which either

1. provides the necessary client dependencies for making JDBC connections to a running database server (MySQL, Postgres, etc.)

2. OR contains the database vendor itself, as in the case of Apache Derby or HyperSQL, which are both in-memory database.

To use any of these databases you'll need to install its BoxLang module to support JDBC connections to that datasource.

Make Sure to Specify a Driver

The datasource configuration struct should be defined exactly the same whether you are using an inline, ad-hoc datasource or configuring a datasource in your boxlang.json or Application.bx. Make sure you have a "driver" key defined OR the driver clearly denoted in the JDBC url:

Defining Datasources In boxlang.json

You can define a datasource at the BoxLang runtime level by placing it in your boxlang.json:

Defining Datasources In Application.bx

For web runtimes, you can also define the datasources in the Application.bx, which is sometimes our preferred approach as the connections are versioned controlled and more visible than in the admin. You will do this by defining a struct called this.datasources. Each key will be the name of the datasource to register and the value of each key a struct of configuration information for the datasource. However, we recommend that you setup environment variables in order to NOT store your passwords in plain-text in your source code.

Defining Inline Datasources

Finally, for smaller or simpler applications with few queries, you may find it useful to define your datasource at query time. So instead of giving the name of the datasource, it can be a struct definition of the datasource you want to connect to:

Default Datasource

You can also define a default datasource to allow you to omit the datasource completely from query calls.

To do this, you'll need to define a default datasource in one of two locations:

1. In your BoxLang runtime's boxlang.json config file via the defaultDatasource key

2. or, for web server runtimes, in a this.datasource variable in your Application.bx file

Defining a default datasource via boxlang.json

Defining a default datasource via Application.bx

Portable Datasources

• CF Mappings

• Data sources

• Mail servers

• Request, session, or application timeouts

• Licensing information

• Passwords

• Template caching settings

• Basically any settings in the web based administrator

You can easily place a .cfconfig.json in the web root of your project, and if you start up a CommandBox server on any BoxLang engine, CFConfig will transfer the configuration to the engine's innards:

Datasource Configuration

All Configuration Properties

Datasource Connection Pooling

• maxConnections

• minConnections

• connectionTimeout

• idleTimeout

• maxLifetime

• keepaliveTime

Pool Statistics

BoxLang offers a number of pool statistics which can be retrieved from the datasource object. To do this, first find your datasource name from the list of registered datasources:

Next, retrieve the datasource by its unique datasource name, and call .getPoolStats() on the result:

This returns a struct of pool metadata including the following keys:

• pendingThreads

• idleConnections

• totalConnections

• activeConnections

• maxConnections

• minConnections

Find out what datasources you have defined by dumping out this getBoxContext().getRuntime().getDatasourceService().getNames()