Overview

The SQL data source is used to retrieve and set values in a SQL database. This is a polling data source that will read values based upon a given update period.

Connectivity

Any database supported by JDBC can be accessed. A specific JDBC driver is required to connect to any particular database, but such drivers are readily available for most databases including MySQL, MS SQL Server, IBM DB2, Oracle, Sybase, and many others. The driver for MySQL is included with this product. See the documentation for your particular database for information on where to get the appropriate JDBC driver.

Configuration

Every data source requires a Name, which can be any description. The Update period determines how often the database will be read.

The Driver class name specifies the Java class that implements the JDBC Driver interface within your JDBC driver. This value can be found in the documentation for your driver. The following is a list of driver class names for the given database, and is provided as convenience only. Note that connectivity typically requires the installation of driver software on the Mango server. If you are having problems, please consult the documentation for your database.

The Connection string depends both upon the database you are using and the specifics of its installation. Your JDBC driver documentation will explain how to derive the value for your database. The Username and Password fields provide the necessary credentials for your database to accept connections from this application.

Your Select statement must be a valid SQL statement. SQL is intended to be a standardized data access language, but different databases often have subtle interpretive differences or provide language extensions, so you should use your database's documentation to help you construct the SQL statement for your purposes.

Use the Row-based query checkbox to determine if the query is row-based or column-based. Because this affects the attributes in the data point configuration, this selection can only be changed when there are no points defined for the data source. See below for more information about row vs. column -based queries.

Row-based query handling

Row-based queries have specific expectations of the structure of the query's result set, but allow large amounts of similar data to be extracted more easily than with column-based queries. The result set must have the following structure.

Column-based query handling

Column-based queries use the names of the result set columns to locate point values and time overrides. It is important to recognize that that only the first row of the result set is used in a column-based query.

There may be cases where using a row-based query is desirable, but not possible because the data types are of the values are too disparate. In such cases may be possible to construct the SQL statement to transpose a row-based query into a column-based query. A typical statement for retrieving data in multiple rows may look like this:

select status from relays

To transpose such a table to retrieve values in a single row, the following could be done (assuming 3 relays):

select
  r1.status as r1status,
  r2.status as r2status,
  r3.status as r3status
from relays r1, relays r2, relays r3
where r1.relayId = 'relay1'
  and r2.relayId = 'relay2'
  and r3.relayId = 'relay3'

Please note that the above are simply examples provided for convenience and instruction. Your specific database may require very different solutions.

Select statement testing

The Statement test section may be used to test both your configuration values and your SQL select statement. Clicking the Execute button will cause a connection to be attempted with your database, and if successful, the SQL will be executed. Any errors that occur will be displayed. If the SQL statement runs successfully, the results will be displayed appropriately depending on whether the statement is row- or column-based. Column-based queries will list a line for every column, providing the column name, the column data type (in parentheses, using the JDBC type definition), and the value retrieved. Row-based queries will display the result set in a table with the column names and data types as headers, and a row of data for each row in the result set (up to a maximum of 50 rows).