From a0d25885445f24e0728e3cf5261e5ebd8cef890d Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Thu, 22 Oct 2026 09:50:16 +0200 Subject: [PATCH 1/2] Document browser connections over Bolt WebSocket and SSL --- pages/client-libraries/javascript.mdx | 64 ++++++++++++++++++-- pages/database-management/ssl-encryption.mdx | 9 ++- 2 files changed, 67 insertions(+), 6 deletions(-) diff --git a/pages/client-libraries/javascript.mdx b/pages/client-libraries/javascript.mdx index 6b14f8d7a..810bd8aaa 100644 --- a/pages/client-libraries/javascript.mdx +++ b/pages/client-libraries/javascript.mdx @@ -12,11 +12,10 @@ import CodeSnippet from '/components/code-snippet/CodeSnippet' Learn how to create a JavaScript application that connects to the Memgraph database and executes simple queries. -Running queries directly from a web browser is **not -recommended** because of additional requirements and possible -performance issues. In other words, we encourage you to use -server-side libraries and clients for top performance whenever -possible. +Run the driver in a server-side application where you can. A page in a web +browser can connect to Memgraph too, but the database credentials end up in +client-side code, and a page served over HTTPS needs extra setup. See [Connect +from a web browser](#connect-from-a-web-browser). ## Quickstart @@ -291,6 +290,61 @@ Then, you can connect to the database with the following snippet: For more details on how to create user with credentials and set authentication, visit the [Memgraph authentication guide](/database-management/authentication-and-authorization/users#administer-users). +### Connect from a web browser + +In a web browser, the JavaScript driver connects over WebSocket instead of a +TCP socket. Memgraph accepts WebSocket connections on the Bolt port (7687 by +default), so a page served over HTTP connects with the same `bolt://` URI and +code as in [Database connection](#database-connection). + +Memgraph accepts WebSocket connections on the Bolt port only when SSL is +disabled. If Memgraph runs with the `--bolt-cert-file` and `--bolt-key-file` +flags, browser connections fail, because the Bolt port has no secure WebSocket +(`wss://`). Without SSL, the connection is unencrypted (`ws://`), and browsers +block unencrypted WebSocket connections from pages served over HTTPS. + +To query Memgraph from a page served over HTTPS, use one of these setups: + +- **Backend:** the page calls your own server over HTTPS, and the server + queries Memgraph with the driver. Use this setup where you can, because the + database credentials stay on the server. +- **TLS-terminating reverse proxy:** a proxy accepts `wss://` connections from + the browser and forwards them as plain WebSocket to Memgraph's Bolt port. + Make Memgraph reachable only from the proxy. + +For example, this nginx configuration accepts `wss://` connections on port 443 +and forwards them to Memgraph running without SSL: + +```nginx +events {} + +http { + server { + listen 443 ssl; + ssl_certificate /etc/nginx/certs/cert.pem; + ssl_certificate_key /etc/nginx/certs/key.pem; + + location / { + proxy_pass http://MEMGRAPH_HOST:7687; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_read_timeout 3600s; + } + } +} +``` + +Replace `MEMGRAPH_HOST` with the address of your Memgraph instance, and the +certificate paths with your own. The `Upgrade` and `Connection` headers pass +the WebSocket handshake through to Memgraph, and `proxy_read_timeout` keeps +idle connections open for an hour instead of nginx's default 60 seconds. + +In the page, connect the driver to the proxy with an encrypted URI: +`bolt+s://PROXY_HOST:443`, where `PROXY_HOST` is the proxy's hostname. The +browser checks the proxy's certificate itself, so use a certificate the browser +trusts; the driver can't skip that check. + ### Query the database After connecting your driver to Memgraph, you can start running queries. diff --git a/pages/database-management/ssl-encryption.mdx b/pages/database-management/ssl-encryption.mdx index 05c48a53d..8c978cc4a 100644 --- a/pages/database-management/ssl-encryption.mdx +++ b/pages/database-management/ssl-encryption.mdx @@ -141,7 +141,14 @@ SSLMode::Require` to the `ConnectParams`. -WebSocket over SSL is currently not supported in Memgraph. +When SSL is enabled, the Bolt port doesn't accept WebSocket connections, so +JavaScript applications in a web browser can't connect over secure WebSocket +(`wss://`). To query Memgraph from a page served over HTTPS, see [Connect from +a web browser](/client-libraries/javascript#connect-from-a-web-browser). + +The [log WebSocket server](/database-management/monitoring#real-time-logs-tracking-via-websocket-server) +on port 7444 uses the same certificate. When SSL is enabled, connect to it +with `wss://`. From 56cf96403f6a7efe3dc8f9db2d4b0ec279a065b9 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Thu, 22 Oct 2026 14:20:47 +0200 Subject: [PATCH 2/2] Drop the reverse proxy setup; recommend a backend --- pages/client-libraries/javascript.mdx | 49 ++++----------------------- 1 file changed, 6 insertions(+), 43 deletions(-) diff --git a/pages/client-libraries/javascript.mdx b/pages/client-libraries/javascript.mdx index 810bd8aaa..18ec08b70 100644 --- a/pages/client-libraries/javascript.mdx +++ b/pages/client-libraries/javascript.mdx @@ -14,8 +14,8 @@ Memgraph database and executes simple queries. Run the driver in a server-side application where you can. A page in a web browser can connect to Memgraph too, but the database credentials end up in -client-side code, and a page served over HTTPS needs extra setup. See [Connect -from a web browser](#connect-from-a-web-browser). +client-side code, and a page served over HTTPS can't connect directly. See +[Connect from a web browser](#connect-from-a-web-browser). ## Quickstart @@ -303,47 +303,10 @@ flags, browser connections fail, because the Bolt port has no secure WebSocket (`wss://`). Without SSL, the connection is unencrypted (`ws://`), and browsers block unencrypted WebSocket connections from pages served over HTTPS. -To query Memgraph from a page served over HTTPS, use one of these setups: - -- **Backend:** the page calls your own server over HTTPS, and the server - queries Memgraph with the driver. Use this setup where you can, because the - database credentials stay on the server. -- **TLS-terminating reverse proxy:** a proxy accepts `wss://` connections from - the browser and forwards them as plain WebSocket to Memgraph's Bolt port. - Make Memgraph reachable only from the proxy. - -For example, this nginx configuration accepts `wss://` connections on port 443 -and forwards them to Memgraph running without SSL: - -```nginx -events {} - -http { - server { - listen 443 ssl; - ssl_certificate /etc/nginx/certs/cert.pem; - ssl_certificate_key /etc/nginx/certs/key.pem; - - location / { - proxy_pass http://MEMGRAPH_HOST:7687; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_read_timeout 3600s; - } - } -} -``` - -Replace `MEMGRAPH_HOST` with the address of your Memgraph instance, and the -certificate paths with your own. The `Upgrade` and `Connection` headers pass -the WebSocket handshake through to Memgraph, and `proxy_read_timeout` keeps -idle connections open for an hour instead of nginx's default 60 seconds. - -In the page, connect the driver to the proxy with an encrypted URI: -`bolt+s://PROXY_HOST:443`, where `PROXY_HOST` is the proxy's hostname. The -browser checks the proxy's certificate itself, so use a certificate the browser -trusts; the driver can't skip that check. +To query Memgraph from a page served over HTTPS, have the page call your own +backend over HTTPS, and query Memgraph from the backend with the driver. +Keeping Memgraph behind a backend is good practice in any case: the database +credentials stay on the server, and Memgraph isn't reachable from the browser. ### Query the database