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.
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 db start memory -A --user root --pass secretWe use the default username root 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 8000Note the forwarding address provided by ngrok. For example, 25f6-2402-e280-2189-38e-9c15-d08-2f83-779e.ngrok-free.app.
Keep this address handy as we will use it in the next step.
Connect and verify
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 --prettyOr 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-welcomeConclusion
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.