SurrealDB is a newly launched database that has recently started gaining popularity in the programming world.
SurrealDB was built with the Rust language and was created by Tobie Morgan Hitchcock and Jaime Morgan Hitchcock.
SurrealDB's new database comes with many features, but I'm most interested in the Deno surrealDB library.
In this article, we'll create a simple todo app with the Fresh framework and SurrealDB database. We'll use the Fresh framework to build out the API with surrealDB.
Deno and Fresh are production ready. So you can build any web app and deploy it with one single click. But keep in mind that SurrealDB may not be. According to their docs, SurrealDB is production ready but the documentation is not super clear on the issue.
All the code is available on GitHub.
Here's a Demo of What We'll be Building:
How to Install SurrealDB, Deno, and the Fresh Framework
There are three requirements to follow along with this tutorial: the first is having Deno installed, the second is having the SurrealDB database, and the last one is using the Fresh framework.
First, we'll install the surrealDB database and the Fresh framework with Deno. You can skip this part if you have already installed both Deno and the SurrealDB packages.
How to Install the SurrealDB database on Linux
The SurreadDB installation process is pretty easy for all operating systems. For example, in Linux, you can install the database with one single curl command.
If you have a different operating system, I suggest reading the SurrealDB installation docs.
In Linux, use this command:
To start the surrealDB database in Linux, run the following command:
- You use the
--userflag for your username. In my case, my username is root.
- You use the
--passflag for your password. In my case, my password is root.
To learn more about all the flags or options, run
surreal start --help command. This is what you'll see:
Now you're ready to use the SurrealDB database.
How to Install Deno on Linux
To learn more about Deno, you can read this helpful tutorial I found on freeCodeCamp written by Brian Barrow.
To install Deno on Linux, you need one command:
How to Install the Fresh Framework with Deno
You can set up a Fresh project with the following command:
You can run a local development server with
deno task start .
Note that both the Fresh framework and SurrealDB use the same
8000 port. In the SurrealDB, I didn't find any document about port changing. But in Fresh, you can easily change the port inside
main.ts file. Then, without changing the port, your Fresh localhost redirects the SurrealDB local host.
For example, you can change the port in Fresh like this:
Fresh Framework Project Structure
The project folder structure is pretty straightforward. For this project, we must follow the folder and file structure to create a todo list app with SurrealDB.
Let's further discuss some essential files here:
- The components folder helps contain all custom components built with Preact.
- In the
deno.jsonfile you add tasks and the importMap file. Tasks are similar to scripts in Node, and in the importMap section, you pass a JSON file that contains all your import packages from Deno.
dev.tsis a file created only for development.
fresh.gen.tsgenerates and updates automatically based on
dev.ts. It includes all routes, islands, and other configurations.
import_map.jsonfile contains imports of all packages which you need to run your project.
main.tsis the main entry point that helps start your application.
routesfolder handles your path and API. It is similar to the Next.js pages folder.
/). For example,
twind.config.tsconfigures Tailwind CSS
utilityfolder contains the database configuration.
You can learn more about folder structure from Fresh's official docs.
Again, to run a local development server, use the command
deno task start .
How to Install the SurrealDB Database Library in the Fresh Framework
You need the Deno-based surrealDB library (module). It's a SurrealDB library created by the SurrealDB team.
The SurrealDB library (module) helps you connect your application to your database. The surrealDB module connects your local and remote databases very easily.
To install the SurrealDB module in the Fresh framework, simply copy the following code and paste it into
How to Setup the SurrealDB Database in Fresh
The first step is to create a setup file for the SurrealDB database. The setup file helps you connect the Fresh framework to the SurrealDB database.
In my case, I create a database setup in a separate
utility/database.ts file. The separate file helps reduce your code and is easier to manage.
To connect the database, ensure that your database is running and your password and username match your database conditionals.
For example, run your local SurrealDB user name and password that's the same as in your
surreal start --log debug --user root --pass root memory
How to Use SurrealDB Module (Library) Methods
The SurrealDB module comes with inbuilt methods. All the methods help you perform CURD operations on the SurrealDB database. These methods allow you to create quickly and get, update, and delete things from the database.
In this article, we'll use four methods which are
There are other methods provided by SurrealDB, which you can read about on the surrealDB module documentation page.
How to Create the API Endpoints
To create a Todo app, you need four endpoints. We'll use the Fresh framework to create APIs. All the API routes go in the
- Isdone (Update)
The Get API
The Get API lets you show all data from the todo table. To access all data from Todo table, you need a
select() function provided by the SurrealDB module.
The Post API
In the Post API, you'll create a new todo based on the title. All the todos are saved inside the todo table. With the get API, you access all todos from the todo table.
To create a new todo item in the database, you can use the SurrealDB module's inbuilt
The Isdone (Update) API
The Isdone API helps to update the todo items inside the todo table. To update data from the table the surrealDB module provides an inbuilt
update function for this.
update function, you can promptly update the todos by one or more items in one request.
The Delete API
You use the Delete API to delete a todo from the todo list. You'll use the inbuilt
delete() function. With this inbuilt function, you can quickly delete a todo based on the todo's id.
How to Create the UI for the Todo App
The index page shows that both the
Item.tsx files come from the island. We'll design the home (Index) page layout with them.
The Box.tsx Component
The Box component helps call the post API and create a new todo in the database.
Box.tsx is an island-based component that's created with Preact. Preact is similar to React, but Preact is a lightweight version of the library.
On the Box component, we get the value in the input with the onChange Event. Then, after the user clicks on the add button, we call the post API to create a new todo in the SurrealDB database.
The Item.tsx Component
Item component calls two APIs – one is the delete API and the second is the update API. The delete API deletes an item from the todo table and the update API updates item in the todo table in the database.
Item.tsx is an island component similar to the Box component. The item component is also built with Preact.
Our first button changes based on whether the todo is complete or pending, and the second button deletes the todo based on the Todo's ID.
First, we get the value in the input with the onChange Event. And after the user clicks on the add button, we call the post API to create a new todo in the SurrealDB database.
When the remove button gets clicked, we call the delete API with the todo ID to delete the todo from the database. When the Not Done button gets clicked, we call the Isdone API to update Isdone in the database.
And there you have it - we've implemented all our functionality in our Todo app.
SurrealDB is a helpful database, and I hope you enjoyed learning about it in this tutorial.
There are often a lot of requirements to start working with other databases, but SurrealDB is very simple. You need one command to start the database locally and work with it. It is a new revolution in databases.
The big problem is that SurrealDB is not clear on whether it comes with production capabilities. As of right now, it doesn't seem to fulfill the one-click production-ready web app (like MongoDB Atlas, for example).
You can deploy SurrealDB with a Docker image. The problem is that documents are sometimes not enough info for a new developer (for example, how to change passwords and users in a Docker container).
Without cloud Infrastructure, you would not be able to deploy the application with SuurealDB. So for that reason, I did not provide a live demo of the Todo app. But I know that in the future, SuurealDB will change the future of databases.