Use SurrealDB to Persist Data with Rocket REST API

Reading Time: 8 minutes
SurrealDB

Databases are essential in web development for organizing data in various forms and shapes (both structured and unstructured). Their ultimate goal is for the stored data to be easily retrievable, updated, queried, and generally administered via a graphical user interface (GUI), dashboard, or even command line interface (CLI).

We can use database management systems to perform all database actions through a graphical user interface. With these GUIs, we can get a bird’s-eye view of all the data in our database for easy analysis of the schema or data types, as well as general ease of administration.

SurrealDB shortens development time for modern applications by simplifying the entire database and API stack, eliminating the need for most server-side components. This allows you to quickly and cheaply build secure and performant apps. Its design allows it to run in a variety of environments, including embedded or distributed cloud environments.

Furthermore, because it is a cloud-hosted database, it is simple to host or deploy because SurrealDB can be deployed anywhere, including the SurrealDB Cloud. It can be hosted in the cloud, on-premises, embedded, or edge computing environments in general.

SurrealDB is the solution for database administration, which includes general admin and user management, enforcing data security and control, performance monitoring, maintaining data integrity, dealing with concurrency transactions, and recovering information in the event of an unexpected system failure.

In this blog, we’ll explore:

  • What is SurrealDB?
    • What is Jamstack?
    • SurrealDB for Jamstack & Serverless Applications
    • Why use SurrealDB?
    • Features of SurrealDB
    • SurrealDB vs. PostgreSQL
    • Rocket REST API
  • Hands-on
  • Conclusion

What is SurrealDB?

SurrealDB is a serverless document-graph web database that is flexible, developer-friendly, and fully ACID transactional. Never again will you have to be concerned about database provisioning, scaling, sharding, replication, or correctness.

SurrealDB claims to be the ultimate cloud database for all types of applications, according to the documentation. It is a cloud-native, end-to-end database that supports most traditional applications, including web and mobile. It can also be used for backend-based applications such as Serverless and Jamstack.

What is Jamstack?

Jamstack

SurrealDB for Jamstack and Serverless Applications

Jamstack & Serverless

SurrealDB’s ability to function as both a database and a real-time collaborative API backend layer is one of its advantages. This means it can function as a single, plug-and-play database server. It is highly available, scalable, and distributed, and it supports:

  • SQL querying from client devices
  • GraphQL
  • ACID transactions
  • WebSocket connections
  • Both structured and unstructured data
  • Graph querying
  • Full-text indexing
  • Geospatial querying
  • Row permission-based access

SurrealQL is an out-of-the-box SQL-style query language included with SurrealDB. SurrealQL supports real-time queries, faster and more performant query processing, advanced permissions, and access control for multi-tenant applications. SurrealDB also asserts that it is the next-generation database for serverless applications.

SurrealDB is a NoSQL database, which eliminates the need for the majority of server-side components and layers that are typically required when using other types of database systems. It is adaptable and can easily fit into any type of technology stack. You can also start it with a simple command or a direct connection to a client-side application.

It also works when there are multiple queries or analytics to be performed on a server.

Why use SurrealDB?

SurrealDB is an innovative NewSQL cloud database that is suitable for serverless, jamstack, single-page, and traditional applications. Its versatility and financial value are unparalleled, with the ability to deploy on the cloud, on-premise, embedded, and edge computing environments. Get started with SurrealDB Cloud in one click for a simple setup.

It has a very specific advantage in that there is no need for a complex database and backend setup.

SurrealDB also handles the majority of security rules on your behalf. It provides advanced table- and row-based, customizable access permissions for different types of users, allowing granular data access patterns.

Features of SurrealDB

SurrealDB is so simple to set up and use that your engineering team will be up and running in no time. There is no need to waste time learning a new query language or syntax because the method of querying your data in previous databases works immediately. It is a fast and highly performant database that can scale to meet your needs. It has the following features:

  • Distributed ACID transactions: SurrealDB handles scalability behind the scenes, leaving developers with few operational and management tasks. This is because SurrealDB handles manually creating and allocating additional databases or server resources by default, allowing it to be highly available, distributed, and ACID-compliant.
  • No complex backend servers or APIs: SurrealDB allows us to specify both the database and the API schema in one place. Once a schema is defined, database access is granted automatically to the appropriate parties, eliminating the need for custom code or integration.
  • Support for multi-tenancy: SurrealDB allows us to connect directly to various end-user devices and run SurrealQL queries from web browsers. This means that users can only see or edit the data to which they have been granted access.
  • Inbuilt access and permissions: SurrealDB’s direct client connection provides built-in permissions, which speeds up the development process.
SurrealDB
  • Online and offline data sync: SurrealDB also allows for real-time queries. It ensures that client devices are in sync with client applications, end-user devices, and server-side components in real-time.
  • Support for GraphQL and REST APIs: We can query the database with any tool we want, but we have SurrealQL, GraphQL (which is not yet implemented but is on the roadmap), REST, and JSON-RPC over WebSockets support.
  • Highly scalable and distributed in nature: SurrealDB can be run in a standalone, in-memory, or distributed cluster mode. SurrealDB is designed to be highly scalable and available in accordance with its distributed nature, and it is implemented in such a way that it can easily handle multi-table transactions as well as document and record IDs without table locking.
  • Rewritten in Rust: SurrealDB is entirely written in Rust. Rust, as we know, has a small memory footprint and low CPU requirements. As a result, SurrealDB has advanced querying capabilities and can function as a database server that can be hosted in a distributed cluster.
  • Architecture: SurrealDB has a one-of-a-kind architecture that supports or can be configured for single-node (in-memory) and on-disk storage, as a distributed key-value store, and as a distributed (multi-node) cluster.
  • Support for multiple different clients and libraries: SurrealDB supports the most popular programming languages, including JavaScript, TypeScript, Rust, Go, and others. To ensure low-latency, lightning-fast query performance, connections to client libraries are made via WebSockets using a binary standard.
  • SurrealQL: SurrealDB also includes SurrealQL, a SQL-like query language with minor differences and improvements for data manipulation. SurrealQL data querying uses the SELECT, UPDATE, CREATE, and DELETE methods or statements, just like regular SQL.

Other Features

  • Querying in the SQL style.
  • Deep fetching with no JOIN.
  • Transactions with multiple rows and tables.
  • Indexes with multiple columns and full-text search.
  • SurrealDB includes a collection of strongly typed data types that can be easily converted from one form to another.
  • SurrealDB includes built-in methods for working with and managing a wide range of data types and structures by default.
  • Transactions are used to group statements together.

SurrealDB vs. PostgreSQL

SurrealDB vs. PostgreSQL

PostgreSQL and SurrealDB are very similar in nature, but they offer distinct feature sets that are worth investigating. Although both are free and open-source relational DMS, PostgreSQL can be used for commercial and non-commercial projects.

PostgreSQL has been in active development for over 30 years and is available for all major operating systems, including macOS, Linux, Windows, BSD, and Solaris. Many of the applications we use on a daily basis are powered by it. It is also more stable and has been battle-tested over time, making it resilient and highly available for a wide range of mission-critical workloads.

Despite issues with table and index bloating, PostgreSQL integrates with a wide range of other tools and platforms. It also supports distributed ACID transactions, which modify multiple rows across multiple shards, structured and unstructured data, and online/offline data synchronization.

Rocket REST API

The REST API has become the industry standard for connecting and transferring data from one source to another. It provides a set of design guidelines and architectural patterns for creating and deploying web services.

Rocket is a Rust-based HTTP web framework that prioritizes security, flexibility, and speed. Rocket includes features such as type-safety, reusability, logging, static file serving, and many others that developers can use to create scalable applications with less code.

Hands-On

SurrealDB

The repository for the code used in this blog is at https://github.com/workfall/workfall-surreal-rocket

Folder Structure

SurrealDB

Installations

Since this is a Rocket application, you must have Rust installed, including the rust toolchain which is the manager for Rust compilation tools. For this blog, we shall use the nightly build.

SurrealDB is built in Rust and therefore integrating with Rust is much simpler, but it supports various libraries in JavaScript, Deno, and Golang.

To create a new Rocket application we use the command cargo new <application_name> and then add the following to your Cargo.toml:

SurrealDB

This will install surrealdb and rocket crates.

App.toml:

This file holds some variables that we can use throughout our application. Here we shall set our database information.

SurrealDB

SurrealDB uses the namespace, database, and datastore parameters to create a new database instance. The datastore param has three options, it can either be in memory, a local file system, or a distributed (remote store). In our case will use the local file system hence the file://temp.db value.

Rocket.toml:
In this file, we’ll put configs pertaining to the Rocket framework. On the default configs, we shall change the port because apparently surrealdb crate uses the same port.

SurrealDB

src/db/middleware.rs(1):

Here we shall create the middleware that initializes the database when Rocket is launched. The rocket uses the Fairing module to create middleware.

SurrealDB

src/db/middleware.rs(2):

We use the figment method to extract variables from the App.toml config file.

src/db/mod.rs:

SurrealQL queries

Note: SurrealDB has a lot of features including but not limited to numerous powerful Data types with their respective functions, other SurrealQL statements, and operators. Feel free to look at their documentation at surrealdb.com.

SurrealDB uses the <table>:<item_id> syntax to store items in the documents. If the id is not specified, SurrealDB will automatically create a unique id for the item. To create a new record, use the CREATE statement. To update a record, use the INSERT statement as shown in the image below.

src/main.rs(1):

src/main.rs(2):

API Test

Create user:

Fetch users:

Conclusion

In this blog, we learned how to use SurrealDB in a Rust Rocket application and the advantages SurrealDB has over other databases. You can always pick SurrealDB if you need to alleviate any of the problems that you may encounter when architecting with either NoSQL or Relational databases.

We also looked that just like Redis, SurrealDB can offer an in-memory datastore solution which makes it flexible and fast. We will come up with more such use cases in our upcoming blogs.

Meanwhile…

If you are a Rust Lover and want to explore more about the above topics, here are a few of our blogs for your reference:

Stay tuned to get all the updates about our upcoming blogs on the cloud and the latest technologies.

Keep Exploring -> Keep Learning -> Keep Mastering 

At Workfall, we strive to provide the best tech and pay opportunities to kickass coders around the world. If you’re looking to work with global clients, build cutting-edge products, and make big bucks doing so, give it a shot at workfall.com/partner today!

Back To Top