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 database 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 connection, you will provide Mode with the credentials for a user account in your database that Mode will use to execute queries against the database. The permissions granted to this user account will govern which tables and records members of your organization can access when they use that database connection in Mode.

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 read-only permission 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 solution lets Mode connect to your database even if it’s not publicly accessible.

Typically, users are able to connect Mode to their database directly. 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, namely if:

  • You need to be connected to a VPN/VPC or physically in the office to access your database; or,
  • 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 add a new data connection to your organization using Direct Connect:

  1. Navigate to the Mode home page for the organization to which you’d like to add the connection and click on your name in the top left corner.
  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 in which directly connecting Mode to your database is not possible or modifying the configuration of your VPN/firewall is not practical or desirable. For these cases, Mode offers an application (“the Bridge connector”) to coordinate communication between Mode and your databases. The Bridge connector is easy to install, configure, and maintain.

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:

  • macOS 10.11 or later
  • Windows 10 or Windows Server 2012 R2 or later
  • Most 64-bit Linux distributions, including:
    • Ubuntu 14.04 16.04 18.04 LTS
    • Fedora 27, 28, 29
    • CentOS 6, 7
    • Debian 8.0, 9.0
    • Our success team can provide a generic tarball for many other 64-bit Linux systems.

We also support running Bridge inside a Docker container.

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.

Bridge will install in one of the following 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
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

How to connect

You must have admin access to the computer on which 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 not, 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.
  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. If you would like to use an existing Bridge, select the Bridge that you’d like to connect your database to.
  7. Once Bridge is installed and running, click Next.
  8. Fill out your database credentials and click Connect. Mode should confirm that you’re connected.


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 system’s service manager. Bridge’s configuration file bridge.json contains a credential and should be kept secret when incorporating it into configuration management systems.

You can locate the configuration file using the following OS-specific paths:

  • 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 start or stop Bridge vary across operating systems. If you don’t see commands listed for your system below, please contact our success team.

OS Stop Bridge Start Bridge
OSX launchctl stop com.modeanalytics.bridge launchctl start 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
Windows Windows Services Manager Windows Services Manager

Run Bridge in a Docker container

These instructions assume that you have administrative access to a Linux host running Docker engine, and would like to run Mode’s Bridge client as a container.

  1. Pull the Docker image

    Run the following command to pull the Docker image:

    docker pull modeanalytics/bridge-client

    Make sure you are running docker commands as the root user (default on Linux), or that your user has access to the Docker engine on your host.

  2. Generate credentials for Bridge

    To generate Bridge credentials, you must be an admin of the organization you want Bridge to connect to:

    1. Navigate to Organization Settings and and select Bridge Connectors.
    2. Input a name for this Bridge connection and then click Create Bridge.
    3. Your credentials will be displayed. Record them now as you will not be able to retrieve them later.
  3. Configure your Bridge host

    Create a new configuration file on the host where you want to install Bridge. We recommend naming the file /etc/mode-bridge.env. Your configuration file should look like the following, replacing the example values with your real credentials and server:

  4. Create a container

    You only need to create a container once. Our Docker image downloads and runs the latest release of Bridge when it is first started and on subsequent restarts. Run the following command on the host:

    docker create --env-file /etc/mode-bridge.env --name mode-bridge modeanalytics/bridge-client

    Note: The above command above assumes your Bridge configuration is in /etc/mode-bridge.env. If you chose a different location, replace it with the correct file path.

  5. Start Bridge client

    Run the following command to start your new container and Bridge:

    docker start mode-bridge

    To verify that your Bridge connector has been configured correctly, you can inspect the logs for any error messages by running the following command:

    docker logs --tail 30 mode-bridge

    If you discover you need to make any corrections to your configuration file, edit the file and then restart your container to apply the changes by running the following command:

    docker restart mode-bridge


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?

No. 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 connection 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 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 March 13, 2019