Connect to SurrealDB via Ngrok tunnel

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.

Prerequisites

This guide assumes the following:

You have SurrealDB installed and a fresh instance of SurrealDB running.
Downloaded Ngrok to be used as a tunnel.

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

Steps

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

Start SurrealDB Instance

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

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

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

Set Up Ngrok Tunnel

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 to SurrealDB via the Ngrok Address

Now, let's connect to your SurrealDB instance using the forwarding address provided by Ngrok.

Run the following command in a new terminal window/tab, replacing [ngrok-address] with the actual Ngrok forwarding address you noted earlier:

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

Verify the Connection

Finally, let’s ensure the connection is properly set up by running a test query. With the help of the CREATE statement, create a new record.

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';

And let's query the data from the record now.

SELECT * FROM registration

Conclusion

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.