Docs
Back to website ->

Bridge Connector

Suggest Edits

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 to access your DB within your private network.

The Bridge Connector offers a convenient and powerful alternative to using a SSH bastion, enabling usage of your DB as a cloud connection without having to expose any ports to incoming requests. This allows you to take full advantage of the full range of cloud connection functionality, including being shared with teammates, being used for scheduled queries and scheduled dashboards, being used with the dbt Core Integration, and more. Similar to a SSH bastion, the Bridge Connector client that is installed within your network does not directly run your queries, and does not come with any database adapters.

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
  • 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:

  1. 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.
  2. 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.
  3. 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.
  4. If you believe that a Bridge Connector or Bridge Secret has been compromised, you can delete the bridge within the PopSQL UI. Once deleted, no more connections can be made via that bridge, the tunnel between PopSQL and any existing Bridge Connectors using those credentials will be closed, and no Bridge Connectors will be able to authenticate or connect with those credentials again in the future. You can then create a new bridge in the UI, restart the Bridge Connector using the new Bridge ID and Bridge Secret, and update your connections to use the new bridge.

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.

Updated 9 days ago

Cookie settings