Skip to content

Tutorials

Connect to SurrealDB via ngrok

This guide will walk you through connecting a local SurrealDB instance to the internet using ngrok, making it accessible remotely.

Ngrok is a cross-platform application that allows developers to expose their local web servers to the internet. It hosts a local web server on its own sub-domain and makes your local development box available on the internet through Tunneling.

This setup is beneficial for remote development and quick testing of applications built locally on SurrealDB.

This guide assumes the following:

Important

Tunneling refers to the process of using a network protocol to encapsulate a different payload protocol, enabling data to pass securely through a network or the internet

There are two ways to connect to a SurrealDB instance via ngrok tunnel.

Open your command line or terminal and run the following command to start SurrealDB.

surreal db start memory -A --user root --pass secret

We use the default username root and password secret. You can replace it with your own credentials if you have set them up.

Open another command line or terminal window (do not close the SurrealDB one) and run the following command to expose SurrealDB’s default port (8000) to the internet:

ngrok http 8000

Note the forwarding address provided by ngrok. For example, 25f6-2402-e280-2189-38e-9c15-d08-2f83-779e.ngrok-free.app.

Important

Keep this address handy as we will use it in the next step.

Connect using the forwarding address from ngrok, replacing [ngrok-address] with the address you noted earlier. You can open an interactive REPL:

surreal db sql --endpoint wss://[ngrok-address] --user root --pass secret --ns main --db main --pretty

Or run a one-shot check that creates a record and selects it:

echo "CREATE registration SET full_name = 'John Doe', email = 'johndoe@gmail.com', address_line1 = 'Room number 1, Hogwarts', address_line2 = 'Near Diagon Alley', city = 'Hogwarts', country = 'England'; SELECT * FROM registration;" | surreal db sql --endpoint wss://[ngrok-address] --user root --pass secret --ns main --db main --pretty --hide-welcome

In this guide, we have looked at how we can connect to a local instance of SurrealDB using tunnels like ngrok which can help with testing applications. ngrok provides a random or custom subdomain for your tunnel URL every time you start the tunnel, which is difficult to predict. The data transmitted over the ngrok tunnel is encrypted, ensuring the information remains secure while it travels over the internet.

Was this page helpful?

Last updated