How to connect to an SQL database

How to connect to an SQL database

How to create SQL Database Connection

Before you start

  • Verify that your database is running correctly.
  • Make sure your database is accessible from a public IP address.
  • Verify that your database accepts connections from Octoboard IP address:

Configuring new connection

To configure your first connection and add a widget, use the red button on the bottom-right and select ADD WIDGET (if you are adding widgets to a report, make sure you enter EDIT mode first).

Add widget button

Once you click ADD WIDGET, you will be brought to the standard connection wizard. On the first page, select the database you would like to connect to. Scroll down to locate your database of choice. Select it and click NEXT.

Wizard connect to oracle

You will be prompted to enter your database connection details. Creating SQL database connection is a very similar process for all supported databases. In this tutorial we are using Oracle as an example:

Oracle wizard connection

You will be prompted to enter connection details for your database. Click "TEST CONNECTION" button. Octoboard will tell you if your connection is successful. Click APPLY to finish the process.

Octoboard cannot connect to a database on localhost ( Your database has to be accessible from a public IP address.

Once your database connection is established, you can start running SQL queries and display information in database widgets. You can create complex SQL statements but your SELECT fields have to conform to requirements of each widget type.

To proceed to creation of a database widget, please click NEXT in the connection wizard.

The process of adding database widgets to your dashboards and reports is covered in this Knowledge Base tutorial.


Are there any limits or SQL query requirements?

  • Only SELECT statements are allowed.
  • Do not terminate your queries with a semicolon (;).
  • Do not use comments in your SQL queries.
  • Column counts should match requested widget type. This is covered in earlier paragraphs of this tutorial.
  • Query results are limited to 1000 rows. This should be sufficient for most cases. If you hit this limit, try to optimize your output by (a) aggregating returned datasets (use GROUPBY statement) and (b) returning data in descending order (use "SORT BY field DESC")
  • Queries should run in under 10 seconds. After that period, the widgets will timeout. If that happens, try to simplify your queries.

I cannot connect to my database. What should I do?

First, make sure your database is accessible online. Run the following command from a public computer (from a public IP address, not on your private network). Replace your_db_host and your_db_port with the host and port of your database:

f:Unix OS: nc -v your_db_host your_db_port

f:Windows OS: telnet your_db_host your_db_port

Please contact your database administrator and make sure that your database accepts connections from the following Octoboard IP address: