Bridge Connector

The PopSQL Bridge Connector makes it possible for PopSQL to connect to a database located within a private network, without requiring you to modify your firewall or VPN configuration to make the database publicly accessible to the internet. This is achieved with the assistance of a small helper application running inside of your private network, which connects to PopSQL’s servers and forms a secure tunnel that allows PopSQL to access your database.

The Bridge Connector offers a convenient and powerful alternative to using a SSH bastion, enabling usage of your database as a cloud connection without having to expose any ports to incoming requests. This allows you to take advantage of the full range of cloud connection functionality, including sharing the connection with teammates, scheduling queries and dashboards, being used with the dbt Core Integration, and more. Similar to an SSH bastion, the Bridge Connector client that is installed within your network does not directly run your queries - it merely forms a tunnel through which PopSQL can access databases within your private network.

Requirements

To setup a Bridge Connector, you must be an organization admin in PopSQL, and you must have sufficient privileges to install and run programs on a host computer within the private network where your database is located. Be sure to check with your network administrator before installing the Bridge Connector.

Currently, the Bridge Connector Client is available to be setup as a docker container.

The Bridge Connector makes an outbound TCP connection to bridge.popsql.com on port 4000. You may therefore need to adjust your firewall to allow outbound TCP connections on this port.

Installation

Create a new bridge within the PopSQL UI by going to Preferences > Bridge Connector. When creating the connector, we recommend giving it a descriptive name so you know what network it’s located within and what it’s being used for. You will be provided with a Bridge ID and a Bridge Secret in return, which you should keep secret and secure. These will serve as credentials, which allow the Bridge Connector to authenticate itself when connecting to PopSQL’s servers. Note that you will not be able to view the Bridge Secret again in the future, so be sure to record it and store it in a safe location. If you lose your Bridge Secret, we recommend deleting the bridge and creating a new one.

Next, pull down the docker image: docker pull ghcr.io/timescale/popsql-bridge-client:latest.

Run the container, providing the Bridge ID and Bridge Secret as the BRIDGE_ID and BRIDGE_SECRET environment variables, respectively. Additionally, we recommend that you provide an ALLOW environment variable that contains a comma-separated list of host/port combinations corresponding to the databases within your network that you want to allow the Bridge Connector to connect to. If you do not provide this, the Bride Connector will be able to connect to any host/port within your private network.

For example, it might look like this via the docker CLI:

docker run \
    --env BRIDGE_ID=0db4d173-a5ba-4be9-ae26-beab2f2875ee \
    --env BRIDGE_SECRET=82028996-27d6-4282-ab73-6ce39a941204 \
    --env ALLOW=localhost:5432,internal_server:1234 \
    --network host \
    ghcr.io/timescale/popsql-bridge-client:latest

You should see output like the following, which indicates that the Bridge Connector has successfully connected and authenticated itself with PopSQL’s servers:

INFO    Connecting to bridge server     {"address": "bridge.popsql.com:4000"}
INFO    Handling incoming proxy connections

If you are unable to connect or notice any errors in the logs, contact our engineers and we will be happy to help troubleshoot.

If you are planning to share connections that use the Bridge Connector, or use it for scheduled queries/dashboards, you will likely want to set it up to run as a long-lived daemon on a reliable machine within your network. If your Bridge Connector goes down for any reason, any connections configured to use that bridge will be unable to connect.

Using the Bridge Connector

To set up a connection to use the Bridge Connector, either create a new connection or edit an existing connection (see managing connections). Within the connection form, you will see an option to use a bridge. Choose the bridge you want to use for this connection from the drop-down. In the host/port fields, enter the host and port as you would when connecting directly to the database from within your private network. Note that if you provided an ALLOW environment variable when starting the Bridge Connector, the host/port you enter here must be included in the list if allowed hosts/ports, or PopSQL will be unable to connect to the database through the bridge. Click “Test” to verify that the connection is configured and working properly.

That’s it! You should now be able to use the connection anywhere in PopSQL, in the same way you would use a cloud connection.

Note that Bridge Connectors are currently only supported for the following database types:

ClickHouse
Microsoft SQL Server
MySQL
Postgres
Presto
Redshift
Timescale
Trino

Security

PopSQL takes the security and privacy of your data very seriously. For this reason, in addition to PopSQL’s standard security practices, we have implemented several measures to ensure the security of all bridge connections:

Only organization admins are allowed to create, edit, or delete Bridge Connectors in the PopSQL UI.
In order to connect, you must provide both a Bridge ID and a Bridge Secret. The Bridge Secret is a secure token that is not stored anywhere on our servers after initially being generated. Only the bcrypt hash of the secret is stored on our machines, and is used to authenticate your Bridge Connector when it connects. This ensures that, as long as your Bridge Secret is kept private and secure, nobody will be able to impersonate your Bridge Connector.
Only one Bridge Connector can be connected using a given Bridge ID and Bridge Secret at any given time. As long as your Bridge Connector client is successfully connected, you can be sure that no other client has connected with the same Bridge ID and Secret.
All bridge connections are tunneled through a secure, encrypted TLS connection. This ensures that no man-in-the-middle attacks can spy on your data or queries as they are transmitted over the internet through the bridge connection.
The Bridge Connector takes an optional ALLOW parameter, which, if given, only allows connections to hosts and ports within your private network that are included in the list. This acts like a built-in firewall, ensuring that the Bridge Connector cannot be used to connect to resources within your private network that you do not want PopSQL to have access to.
If you believe that a Bridge Connector or Bridge Secret has been compromised, you can rotate the secret within the PopSQL UI. When a Bridge Secret is rotated, any existing Bridge Connectors using that secret will be immediately disconnected, and no Bridge Connectors will be able to authenticate or connect with those credentials again in the future. You can then restart the Bridge Connector using the new Bridge ID and Secret. Alternatively, you can fully delete a Bridge Connector via the PopSQL UI, which will likewise immediately disconnect any existing Bridge Connectors and prevent them from connecting with that Bridge ID and Secret in the future.

Note that unlike when using direct connections, your query data is transmitted through PopSQL’s servers when using the Bridge Connector (although it is only stored if result sharing is enabled). If this is not acceptable to your security team, you may need to use direct connections instead.

Notice

The popsql-bridge-client makes use of the github.com/hashicorp/yamux library, which is licensed under the Mozilla Public License, Version 2.0. Source code for the yamux library can be found at: https://github.com/hashicorp/yamux.