SingleStore Studio WebSocket Proxy
On this page
SingleStore v7.the proxy
) has a small footprint, and typically a low overhead when running.
Each proxy instance opens: - A new Unix socket for communicating with the SingleStore engine - An HTTPS port for communicating with the outside world
Start the Proxy
-
A free, open port must be used for the WebSocket proxy; the port can be specified using the
https_
or theproxy_ port http_
variable.proxy_ port -
As the
https_
andproxy_ port http_
WebSocket variables are mutually exclusive, the proxy will fail to start if both are set, and you will be prompted to update theproxy_ port memsql.
file.cnf -
The
https_
variable requires SSL to be enabled.proxy_ port For more information on enabling SSL, refer to SSL Secure Connections guide. -
If multiple nodes have a WebSocket variable set, only the Master Aggregator’s proxy will be used, with the non-aggregator proxies remaining dormant.
If a new aggregator is attached or promoted, it must have a WebSocket variable set in order to serve WebSocket traffic.
There are three options available for starting the proxy.
Option 1: Modify the memsql. cnf
file
-
On the Master Aggregator host of a SingleStore cluster, add one of the following lines to the
memsql.
file.cnf -
For HTTPS:
https_
proxy_ port = <port> -
For HTTP:
http_
proxy_ port = <port>
-
-
Start the cluster.
sdb-admin start-node --all
Option 2: SingleStore Toolbox
-
On the Master Aggregator host of a running cluster, use
sdb-admin update config
to set either thehttps_
orproxy_ port http_
variable.proxy_ port For HTTPS:
sdb-admin update-config --key https_proxy_port --value <port>For HTTP:
sdb-admin update-config --key http_proxy_port --value <port>
Refer to the update-config command reference for more information on how to update the configuration of the Master Aggregator.
Option 3: SQL
-
Start the cluster and run the following in a database connection where you have superuser SUPER privileges.
For HTTPS:
SET GLOBAL https_proxy_port = <port>;For HTTP:
SET GLOBAL http_proxy_port = <port>; -
Restart the proxy.
RESTART PROXY;
This will allow the proxy to start even if no proxy port was specified in the memsql.
file.https_
and http_
is not supported, select the protocol that best fits your requirements.
Caution
In the case of conflicting variables, such as when both the https_
and http_
variables are set, the proxy will throw an error but not abort.RESTART PROXY
will be disabled until this discrepancy is resolved.
Change the Proxy Port
-
To change a proxy’s port when it’s running, specify a new port and restart the proxy.
For HTTPS:
SET GLOBAL https_proxy_port = <port>;For HTTP:
SET GLOBAL http_proxy_port = <port>; -
Restart the proxy.
Note that RESTART PROXY
still requires SUPER.RESTART PROXY;
By design, RESTART PROXY
is designed to either fail, where nothing undesirable happens and an error is returned, or to work absolutely, where a proxy is running on the port specified by the global variable.
About the Proxy State
Regardless of how it was started, the proxy will not restart itself on a failure.RESTART PROXY
.
If RESTART PROXY
does not throw an error, the state of the proxy is reflected in the global variable at the time of the restart.
The proxy log, websocket_
, can be found in the same directory as the other SingleStore logs.
Use SingleStore Studio with the Proxy
Prior to Studio v1.
Master Aggregator Host Architecture
![](https://images.contentstack.io/v3/assets/bltac01ee6daa3a1e14/blt98f0ea07741dd1b1/66db608743cd951372d5ac55/memsql-studio-proxy-architecture-dLN3p2.png?width=850&disable=upscale&auto=webp)
With the introduction of this WebSocket Proxy (or, simply, the proxy
), Studio can now connect to SingleStore via HTTPS on hosts other than the Master Aggregator.
This solution has a number of advantages:
-
Unlike the previous solution, Studio can now accept users that are configured as
REQUIRE SSL
.Previously, the communication between Studio and SingleStore was not over HTTPS, which necessitated the co-location requirement. As a consequence, Studio no longer needs to be co-located with a SingleStore cluster in order to provide secure communications. -
Traffic no longer needs to be proxied through Studio and can now go directly to the SingleStore cluster.
As shown in the diagram below, Studio can now connect directly to a SingleStore cluster through the wss://
protocol.
Separate Host Architecture
![](https://images.contentstack.io/v3/assets/bltac01ee6daa3a1e14/bltc832cc3c5c7834af/66db609ef16381219e326f9c/memsql-studio-websockets-architecture-Agrkjs.png?width=850&disable=upscale&auto=webp)
Architectural Differences
-
The machine running the browser needs to have direct access to the Master Aggregator host.
Previously, only the singlestoredb-studio
server required this access. -
For situations where
REQUIRE SSL
is not mandatory, and if the additional configuration required to use a direct WebSocket connection becomes a bottleneck, it may be simpler to use the existing Studio architecture, where Studio is served over HTTPS and thesinglestoredb-studio
server is co-located with the Master Aggregator.
There are some differences with this new SingleStore Studio architecture compared to the one it replaces:
Prerequisites
-
Studio must be served via HTTPS to establish and use a proxy connection via the
wss://
protocol. -
The SingleStore endpoint added to Studio must use the same domain that’s configured in the SingleStore SSL certificate as expressed in the
memsql.
file.cnf -
The port (the
https_
orproxy_ port http_
value) must be exposed so that a browser can communicate over it.proxy_ port -
The browser must be configured to trust the certificate.
This can either be achieved by using a certificate created by a known CA, such as letsencrypt. org, or by an internal enterprise CA that may be pre-installed on a company computer. Refer to How to add a trusted CA certificate to Chrome and Firefox for more information.
The following requirements must be met in order to use a secure proxy connection from your browser.
Configure SingleStore Studio
-
Edit the Studio state file and add the following lines to the cluster definition:
-
websocket = true
-
websocketSSL
=true
orfalse
-
If using
https_
:proxy_ port true
-
If using
http_
:proxy_ port false
-
-
port = <port>
-
If
websocket
istrue
, the WebSocket port specified using thehttps_
or theproxy_ port http_
variable in this stepproxy_ port
-
-
-
Restart Studio.
Using
systemd
with package-based installations of Studio:sudo systemctl restart singlestoredb-studioUsing
sudo
with package-based installations of Studio:sudo singlestoredb-studio &For non-
sudo
/tarball-based installations of Studio:cd singlestoredb-studio-<version>nohup ./singlestoredb-studio > studio.stdout 2> studio.stderr < /dev/null & -
Log into Studio and connect to the cluster that you configured to use WebSockets.
Use the following steps to configure Studio to use the WebSocket proxy to connect to your cluster.
Last modified: February 16, 2024