Oct 13th, 2023

Surreal Stickies 2.0: Adding Graph Relations, Live Queries, and Authentication

by Pratim Bhosale, 5 min read

Introduction

Welcome back to the second instalment of our tutorial series on building a notes app with Next.js, Tailwind, and SurrealDB. In Part 1, we laid the groundwork for Surreal Stickies, a full-stack note-taking application. We covered the essentials, from setting up your development environment to building CRUD APIs and a user interface. If you haven’t read it yet, we recommend starting there as a prerequisite to get the most out of this tutorial.

In this tutorial, we’re taking Surreal Stickies to the next level! With the release of SurrealDB 1.0, we have many new features to explore and integrate into our application. In this part, we will introduce:

👉 Multi-user capabilities, authentication and permissions.

👉 Tagging features for better note organization.

👉 Real-time updates using Live Queries.

So, let’s dive right in and make our notes app more efficient and customizable!

For those who want to directly skip to running the application, you can clone it from our examples repository on GitHub. Steps to set up the project and run it for the first time are included in our README.

After you build this application, here’s how your updated stickies app will look! In this example, we’re helping Harry Potter take some critical notes on his first day at Hogwarts!

Direct Database Connection

In the new version, we’ve eliminated the need for a separate API layer to interact with the database. By directly connecting to SurrealDB, we’ve streamlined the architecture and simplified the codebase.

In contrast, the first version used a more traditional approach, where API routes were defined to handle CRUD operations. These routes would then interact with SurrealDB.

Let’s start by running the SurrealDB instance locally on our machine by running the following command in your terminal.

surreal sql --conn ws://localhost:3001 --user root --pass root --ns test --db test --pretty

This command will open up a particular terminal window where you can type and run database commands directly. We recommend reading more about the SQL command in SurrealQL.

Creating and Running Schemas

Now that we are connected to SurrealDB, let’s recreate the schemas for our stickies app and manually add them to our SurrealDB instance. Specifically, we’ll define schemas for our tables - user, tag and sticky.

User Table

The user table will store information about each user, such as their name, username, and password. We also define permissions to ensure users can only modify their own data.

Define a schemafull table named user and set the permissions for the user table which allows select, update, and delete operations only where the ID of the record matches the authenticated user’s ID.

DEFINE TABLE user SCHEMAFULL
    PERMISSIONS
        FOR select, update, delete WHERE id = $auth.id;

Define a field named name of type string on the user table and assert that the length of the string must be greater than or equal to 2

DEFINE FIELD name ON user TYPE string ASSERT string::len($value) >= 2;

Define the field username of type string and set the value to be the lowercase version of the input

DEFINE FIELD username ON user TYPE string VALUE string::lowercase($value);

Define the field password of type string and set its permissions such that the password field cannot be selected

DEFINE FIELD password ON user TYPE string PERMISSIONS FOR select NONE;

Define the field created with its value set to the current time the record is created. If the record is updated, the created field will not change

DEFINE FIELD created ON user VALUE $before OR time::now() DEFAULT time::now();

Define the field updated and have its value set to the current time whenever the record is created or updated

DEFINE FIELD updated ON user VALUE time::now() DEFAULT time::now();

In SurrealDB 1.0, you can now add traditional and unique indexes to your fields. So, we define a unique index on the username field, ensuring that no two user records can have the same username.

DEFINE INDEX unique_username ON user FIELDS username UNIQUE;

Define an event that triggers when a user record is deleted. It deletes all sticky and tag records where the author or owner matches the ID of the deleted user.

DEFINE EVENT removal ON user WHEN $event = 'DELETE' THEN {
    DELETE sticky WHERE author = $before.id;
    DELETE tag WHERE owner = $before.id;
};

Tag table

The tag table will store information about each tag, including its name and the owner who created it. The owner field will resemble the user record type.

DEFINE FIELD owner ON tag TYPE record<user>

Permissions will ensure that only the owner can modify or delete their tags. We will later focus on how we use the tag table.

Sticky table

The sticky table will store details about each sticky note, such as its content, colour, and the author who created it. Table permissions ensure that only the author can perform CRUD operations on their sticky notes.

Assigned-To table

The assigned_to table will establish a many-to-many relationship between tags and sticky notes. It will contain fields to link a tag with a sticky note and timestamps for creation and updates. Table permissions will ensure that only the owner of the tag and the sticky note can modify or delete the relationship.

You can find all the schema queries in the schema folder of the notes-v2 project.

Multi-user capabilities, authentication and permissions

Our authentication layer will reside inside our database itself. Defined in the auth.surql schema it will handle the sign-in and sign-up processes. We will let our front-end code take care of the signout process.

DEFINE SCOPE user SESSION 7d
    SIGNIN (
        SELECT * FROM user WHERE username = $username AND crypto::argon2::compare(password, $password)
    )
    SIGNUP (
        CREATE user CONTENT {
            name: $name,
            username: $username,
            password: crypto::argon2::generate($password)
        }
    );

The DEFINE SCOPE statement is used to set up the scoped authentication rules for user sessions. Here’s a breakdown:

• DEFINE SCOPE user SESSION 7d: This sets up a scope named user and specifies that the session will be valid for 7 days. We’ve picked up a random number here.
• SIGNIN (...): This part of the statement defines the signing-in logic. It selects a user from the user table where the username matches the provided $username and the $password matches the hashed password stored in the database.
• SIGNUP (...): This part defines the logic for signing up a new user. It creates a new record in the user table with the name, username, and a hashed version of the password.

It uses SurrealDB’s built-in cryptographic functions to manage user credentials securely.

Add tagging features for better note organisation

In this section, we’ll walk through implementing tagging functionalities in our Surreal Stickies app using SurrealDB’s graph capabilities. We’ll focus on creating, assigning, and deleting tags and how these operations interact with our schema.

First, let’s create a new file called tag_assignments.ts in your project’s lib directory. This file will house the logic for tag assignments.

Step 1: Implement the assignTag Function

In tag_assignments.ts, let’s start by writing a function called assignTag. This function will use the RELATE statement to establish a relationship between a tag and a sticky note.

export async function assignTag({
    tag,
    sticky,
}: {
    tag: Tag['id'];
    sticky: Sticky['id'];
}) {
    tag = record('tag').parse(tag);
    sticky = record('sticky').parse(sticky);

    const [result] = await surreal.query<[AssignedTo[]]>(
        /* surrealql */ `
            RELATE ONLY $tag->assigned_to->$sticky;
        `,
        { tag, sticky }
    );

    return result.result && result.result.length > 0;
}

This query will create a new edge from the tag to the sticky only if it doesn’t already exist.

Step 2: Implement the unassignTag Function

Next, let’s write another function called unassignTag. This function will remove the relationship between a tag and a sticky note.

export async function unassignTag({
    tag,
    sticky,
}: {
    tag: Tag['id'];
    sticky: Sticky['id'];
}) {
    tag = record('tag').parse(tag);
    sticky = record('sticky').parse(sticky);

    const [result] = await surreal.query<[AssignedTo[]]>(
        /* surrealql */ `
            DELETE $tag->assigned_to WHERE out = $sticky RETURN BEFORE;
        `,
        { tag, sticky }
    );

    return result.result && result.result.length > 0;
}

The DELETE query will delete the edge from the tag to the sticky.

Step 3: Implement the assignedTags Function

Finally, let’s write a function called assignedTags to fetch all tags related to a specific sticky note.

export async function assignedTags(sticky: Sticky['id']) {
    sticky = record('sticky').parse(sticky);

    const [result] = await surreal.query<[Tag[]]>(
        /* surrealql */ `
            $sticky<-assigned_to<-tag.*
        `,
        { sticky }
    );

    return z
        .array(Tag)
        .parse(result.result ?? [])
        .filter(
            ({ id }, index, arr) =>
                index == arr.findIndex((item) => item.id == id)
        );
}

The RELATE query fetches all tags that are related to the sticky through the assigned_to edge.

And there you have it! You’ve successfully added tagging functionalities to your Surreal Stickies app using SurrealDB’s graph capabilities. Now go ahead and run your app to see the tagging in action!

Enable real-time updates using Live Queries.

As we build our application, one feature that will significantly enhance the user experience across multiple devices is Live Queries. This ensures that changes are immediately reflected in the UI whenever a sticky note is created, updated, or deleted in the database. To achieve this, we’ll integrate Surreal’s live queries into our Zustand store for sticky notes. We use Zustand in order to render our UI correctly and hold the state of all our sticky notes.

surreal.live<Sticky>('sticky', ({ action, result }) => {
    switch (action) {
        case 'CREATE':
        case 'UPDATE':
            store.mergeStickies([Sticky.parse(result)]);
            break;
        case 'DELETE':
            store.deleteSticky(result.id);
            break;
    }
});

Understanding the Live Query Listener

Here’s what each part does:

• surreal.live('sticky') listens for real-time updates on the sticky table.
• The action parameter can be either CREATE, UPDATE, or DELETE, representing the type of operation that triggered the update.
• store.mergeStickies([Sticky.parse(result)]); merges the newly created or updated sticky note into the existing Zustand state.
• store.deleteSticky(result.id); removes the deleted sticky note from the Zustand state.

Building the Frontend for Stickies

While the backend logic and database interactions are the main focus of this blog, let’s briefly touch upon the frontend structure. The frontend code is organized into components and hooks, each serving a specific purpose in the application. This can be explored in detail in the GitHub repository.

Component Structure

• Add-Sticky Component: Responsible for adding new stickies. Utilizes the useCreateSticky hook.
• Sticky Component: Manages the display, editing, and deletion of individual stickies. Employs hooks like useDeleteSticky and useUpdateSticky.
• Tag Picker: Allows users to pick tags for their stickies. Fetches available tags using the useTags hook.

Hooks and State Management

• Stickies Hook: Defined in [lib/hooks/stickies.ts](https://github.com/surrealdb/examples/blob/main/notes-v2/src/lib/hooks/stickies.ts), this hook uses SWR for data fetching and caching.
• Zustand for Auth: Zustand is used for managing the authentication state in [lib/stores/auth.tsx](https://github.com/surrealdb/examples/blob/main/notes-v2/src/lib/stores/auth.tsx).

A Closer Look at the Navbar Logic

The sign-out logic of our notes app resides inside our Navbar. When a user clicks the sign-out button, the following sequence of actions occurs:

const { trigger: signout } = useSWRMutation('auth:signout', async () => {
    await surreal.invalidate(); // Invalidate the user session
    localStorage.removeItem('token'); // Remove the token from local storage
    await refresh(); // Refresh the authentication state
});

This logic ensures that the user session is invalidated using the in-built surreal.invalidate() method, and the token is removed from local storage, effectively signing the user out of the application.

For a complete understanding of the sign-out code in the frontend, please refer to the GitHub repository.

Live Demo and Q&A

We recently hosted a live demo of Surreal Stickies at Surrealdb World. If you missed it, you can watch the recording here.

Wrapping It Up: Your Next Steps

We’ve come a long way, from setting up our Surreal Stickies app to leveraging top features from the 1.0 release. But this is just the start. Here’s how you can keep the momentum going:

👉 Show and Tell: We’d love to see what you’ve built. Share your project on social media and tag @SurrealDB on Twitter. Your work could inspire others!

👉 Join the Conversation: Our community is a great place to get your questions answered, stay updated on new releases, and showcase your own projects!

So, what are you waiting for? Dive in, explore more, and keep building. Looking forward to seeing you in the community!