Getting ready to connect

Mode can connect to most popular databases that can be queried using SQL or a SQL-like language, including databases hosted on private networks or on private machines, databases hosted in VPCs and VPNs, and databases hosted in the cloud by third parties such as Amazon and Microsoft. By default, each data source you connect to your Mode organization can be queried by all members of your Organization.

Obtain database credentials and connection details

When you set up a new data source, you will provide Mode with the credentials for a user account in your database that Mode will use to execute queries against the database. Therefore, the permissions configured for the user account provided will govern which tables and records members of your organization will have access to in Mode when they use that data source. A best practice is to create (or ask your database admin to create) a new database user specifically to use with Mode. Grant this new user with read-only permissions for the schemas and tables you want your Mode users to be able to query.

Choose a connection method

Mode can connect to your database in two ways:

  • Direct Connect: Mode will connect directly to your database over the public internet. This is the simplest way to connect but may require your database or network to be configured to allow Mode’s servers to connect to it.
  • Bridge: Mode connects to your database with the assistance of a small helper application installed on a computer inside your network with direct access to your database. This enables Mode to connect to your database even if it cannot be accessed from the public internet.

Typically, users are able to connect Mode to their database using Direct Connect. There are, however, a few common scenarios in which you will likely need to use Bridge and/or seek the assistance of your network administrator to connect:

  • You need to be connected to a VPN/VPC or physically in the office to access your database
  • You need to configure your database to allow Mode to directly connect (e.g., whitelist Mode’s IP addresses), but you do not have access to the database’s configuration console.

Direct Connect


Direct Connect is the simplest way to connect your database to Mode. You provide Mode with the necessary credentials, and Mode’s servers connect directly to your database. Most databases hosted by third parties such as Amazon, Google, and Segment are publicly accessible and are compatible with Direct Connect. In some cases, databases hosted in private networks can also be publicly accessible and are compatible with Direct Connect.


In order to use Direct Connect, your database must:

  • Be publicly accessible via the internet (Not sure? Follow these steps.)
  • Have SSL encryption enabled
  • Be allowed to accept incoming connections from Mode’s IP addresses

Your database may require you to whitelist Mode’s IP addresses before it will accept an incoming connection from our servers. All connections from Mode will come from one of these four IP addresses:

If your database or network environment does not meet the above requirements, consider connecting with Mode’s Bridge Connector instead.

How to connect

To connect a new data source to your Organization using Direct Connect:

  1. Navigate to the Mode home page for the Organization you would like to connect the data source to.
  2. Click on Connect a Database.
  3. Select your database from the list.
  4. Follow the on-screen instructions to connect your database.



Typically, users will connect Mode directly to their database. However, there are many situations where directly connecting Mode to your database is not possible and modifying the configuration of your VPN/firewall is not practical or desired. For these cases, Mode offers an easy to install, configure and maintain application (“the Bridge connector”) to coordinate communication between Mode and your databases.

When you write and run a query in Mode, the Bridge sends a request to your database to execute the computation. Once complete, Bridge sends data back to Mode, so you can visualize and share the results.

Bridge connects to Mode by making outbound TCP connections on the following ports:

  • HTTPS/433
  • TCP/8444


You can install the Bridge connector on any computer running any of the following supported operating systems:

  • Most 64-bit Linux distributions, including:
    • CentOS 6, 7
    • Debian 7, 8
    • Fedora 20
    • Red Hat Enterprise Linux 6, 7
    • Ubuntu 12.04, 13.04, 14.04, 16.04
    • We can provide a generic tarball for all other Linux systems. Please contact our success team for more information.
  • macOS 10.11 or later
  • Windows 10 or Windows Server 2012 R2 or later

Bridge will install in one of the follow locations depending on which operating system the host computer is using. To install and configure Bridge, you must have sufficient (typically local administrative) privileges on the host computer.

OS Install Directory Log File Location
Linux /opt/mode/bridge /opt/mode/bridge/bridge.log
OS X /usr/local/mode/bin ~/.modeanalytics/bridge.log
Windows C:\Program Files\Mode Analytics\Bridge Connector\ Windows Event Viewer

Tip: When connecting to a database in AWS, most customers will run Bridge in an EC2 virtual machine. In these cases, you should set up a 64-bit EC2 instance running Linux that can both connect to your Redshift/RDS cluster and can connect to on ports 443 and 8443.

How to connect

IMPORTANT: You must have administrative access to the computer where you intend to install the Bridge connector.

To connect your database using Bridge:

  1. Navigate to the Mode home page and click on your name in the upper left corner of the window.
  2. Check that you are connected to the correct organization. If it’s the wrong organization, click Switch to change organizations.
  3. Select Connect a Database from the dropdown.
  4. Click on the type of database you want to connect to Mode.
  5. Click on the Bridge Connector link under Enter your credentials.
  6. If you are installing Bridge for the first time, click on the Connect a new bridge link. You will be prompted to select an operating system and install Bridge.
  7. If you’ve already installed Bridge before, select a Bridge that you’d like to connect your database to.
  8. Once Bridge is installed and running, click Next.
  9. Fill out your database credentials and click Connect.

Mode should confirm that you’re connected.

Note: If you start writing queries right away, the schema browser in Mode’s query editor can take a few minutes to initially populate.


Bridge requires very little administration once it has been configured. Our system packages will install Bridge and configure the system to run Bridge via the systems service manager. Bridge’s configuration file bridge.json contains a credential and should be treated like a secret when incorporating into configuration management systems.

  • Linux: /opt/mode/Bridge/conf/Bridge.json
  • Mac: $HOME/.modeanalytics/Bridge.json
  • Windows: C:\Program Files\Mode Analytics\Bridge Connector\Bridge.json

The commands to restart Bridge vary across operating systems. Generally, OSX uses launchctl; Linux uses init system, init.d, upstart, or systemd; and Windows uses the Service Manager. For non-Windows systems, run the stop command followed by the start command to restart Bridge. If you don’t see commands listed for your system below, please contact our success team.

SYSTEM       | stop                             | start
------------ | -------------------------------- | ----------------------------------
OSX          | launchctl stop                   | launchctl start
               com.modeanalytics.bridge           com.modeanalytics.bridge
Ubuntu       | sudo stop mode-bridge            | sudo start mode-bridge
Ubuntu 16.04 | sudo systemctl stop mode-bridge  | sudo systemctl start mode-bridge
CentOS       | sudo /etc/init.d/mode-bridge stop| sudo /etc/init.d/mode-bridge start
CentOS 7+    | sudo systemctl stop mode-bridge  | sudo systemctl start mode-bridge
Linux        | /etc/init.d/mode-bridge stop     | /etc/init.d/mode-bridge start

For Windows systems, you can restart Bridge in the Windows Services manager. Open the Windows Services manager, find the Mode Bridge service, right click and select Tasks then Restart.


Mode supports TLS/SSL (Transport Layer Security/Secure Socket Layer) for encrypting communication with your database. This type of security, which encrypts data while it’s in transit, is commonly referred to as transport encryption.

For additional auditing, Mode tags each query with additional metadata which will appear in the database system logs:

  • The Mode username and email address of the user running the query.
  • A link to that query in Mode, which includes the time the query was run and the exact dataset returned.

At Mode, we take security very seriously. Learn more about Mode’s approach to security.


I have several databases, do I need to run several Bridge connectors?

Nope! A single Bridge connector can easily handle multiple databases.

How does the Bridge connector maintain high availability?

Multiple Bridge connector instances sharing the same configuration file can be run simultaneously on different servers or even different data centers without conflicting with one another. This helps ensure a high amount of redundancy and availability. It can also be used to guarantee zero downtime system upgrades of either software or hardware.

What user does the Bridge connector use to access the database?

When you connect your database to Mode, you will provide a database user account that will be used by everyone in your organization with access to this data source to run all queries. The Bridge connector will use this user account to query your database. We recommend you create a read-only user according to your database vendor’s instructions. For additional auditing, the Bridge connector adds tags to each query with the Mode username of the user running the query and a unique report run token that can be used to identify the exact dataset that was returned. This information will appear in your database systems logs, so you will still be able to easily identify individual users’ actions.

What data does the Bridge connector have access to?

The Bridge connector connects relies on the database to enforce data access permissions.

What happens if I disable transport encryption?

If you disable transport encryption while configuring Bridge, this will disable the encrypted connections between the computer running Bridge and your database.

Note: All communication between the computer running Bridge and Mode will still be fully encrypted. This cannot be disabled.

Which database connection types allow me to disable transport encryption?

You can disable transport encryption for the following databases:

  • MySQL
  • PostgreSQL
  • Vertica

Last updated April 18, 2018