Read and Write to an Appwrite Database in Minutes!
Let’s set the stage. You’re at your first MLH hackathon and you’re not really sure what kind of project you want to build. You spend some time forming a team, sitting down together and coming up with ideas; you have some laughs, exchange some stories, drink some water, eat some pizza, and the next thing you know, there’s only 12 hours left before your submission deadline!
Sigh. We’ve all been there before. Well, maybe not the exact same situation, but if you’re in the business of attending hackathons, then you know what it’s like to work on a deadline. Luckily for us, there are tons of time-saving tools out there to help us cut-down on development time without having to sacrifice the quality of our projects!
Enter Appwrite; a self-hosted backend-as-a-service platform that provides developers with all the core APIs required to build any application. Instead of spending hours coding your own REST APIs, Appwrite has all the functionality you need to customize your own backend without having to write & test a ton of code. Best of all, it’s absolutely free to use!
Did I mention that Appwrite would be sponsoring MLH Hackathons during the upcoming season? That’s right! Keep reading to improve your chances of wining the ‘Best Use of Appwrite’ prize category at your next MLH event!
Getting Started
Today I’ll be showing you how to set up an Appwrite Database and make read and write requests using Node.JS!
So put down that pizza crust, crack your knuckles and throw that hood over your head like a true hacker because we’re about to make things happen.
Typically, you would code your own REST API to utilize a database, file storage, or user authentication from the frontend of an application. With Appwrite, you don’t need to write any code to get started! You can spin up your self-hosted server by running the Docker installer tool from your terminal.
Don’t know what Docker is? TL;DR, Docker is a container platform that allows you to build, deploy, run, update and manage applications remotely. Instead of having to configure your local operating system to the specifications of your app, you can configure a docker container to meet those specifications. In the process, you’d be reducing development time, and avoiding problems you may encounter with dependencies and/or libraries across operating systems. This is particularly convenient for developer teams that have varying developer environments (i.e. Tim has a MacBook running macOS Catalina while Sarah has a Dell XPS running Windows 11).
With docker running in the background, you can use Appwrite’s quick-start command in your terminal to spin up an Appwrite Docker Container. Head over to https://hackp.ac/Appwrite and click on the “Get Started” button pictured below.
From there, you’ll see a couple of different options that you can use including Bash, PowerShell, and CMD. Pick what works for you!
I’m going to use Bash and run the following command ⬇️
docker run -it — rm \
— volume /var/run/docker.sock:/var/run/docker.sock \
— volume “$(pwd)”/appwrite:/usr/src/code/appwrite:rw \
— entrypoint=”install” \ appwrite/appwrite:0.15.3
It will take a couple of minutes for your Docker container to get going, but once that’s done you’ll be asked to choose ports for your server, a secret api key and a hostname / DNS record. I suggest using the defaults for now. Once you get through the initial set up, Appwrite should install successfully.
It will look similar to the read out pictured. ⬇️
From here, you’ll want to open up a web browser and type localhost in the address bar. Since we’ve chosen localhost as our Appwrite hostname, this is where your Appwrite console will populate. If you’re a first time user, you’ll need to set up an account, but once that’s complete, you should see something similar to the image below. ⬇️
Setting up your first Appwrite Project
So far so good! With your console up and running, you can now create your first project. A project on Appwrite is exactly what it sounds like. A single workspace that will house all of the Appwrite functionality you plan on using for the application you are building. Go ahead and hit the “Create Project” button to give your first Appwrite backend a catchy name.
As you can see below, I named mine MLH-DEMO (all caps, super edgy). The initial page you see will have an empty activity chart, but you’ll want to access the drop down menu by clicking on the ellipses to the top left of your screen
From the dropdown menu, you’ll want to choose the database option and then give your database a name. Here, you can see that I named mine MLH-DEMO-DB.
Setting up your first Appwrite Database
Before we move on, it’s important to note some of the naming conventions that Appwrite uses for its native databases. A Collection, in this case, is what we would commonly refer to as a Data Table. In the same vein, Documents are the Appwrite equivalent to a Row on a Data Table and Attributes are the Column Headers you would find on a Data Table.
Indexes are used by Appwrite databases to quickly locate data without having to search through every document for results. Think of them as a way of tagging specifics types of attributes you are inputting into your database.
Now that we’ve got that cleared up, go ahead and hit the “Add Data Table”… I mean, “Add Collection” button, and give it a name.
Pretty simple so far right? Now we’re going to manually add a document with a single attribute and index to our new collection.
First, you’ll need to create an attribute. Go ahead and click on the attribute option and hit the “Add Attribute” button. I want my attribute to be a string and I’m going to name the Attribute ID Food_Type. I guess I’m hungry so I’ll go ahead and fill my collection with food items.
Once you have an attribute set up, click on Indexes to set up a Key for your new data type. I’ve gone ahead and set the type as key and named the index key Food_ID. Last but not least, you’ll need to associate the index to an existing attribute, in this case, I’ll use Food_Type.
Now let’s add a new document to our collection. Go ahead and let Appwrite auto-generate a unique ID for your new document. All you should need to do is add a string to the Food_Type attribute. Pizza was my choice this time around.
And just like that, we’ve populated our first Appwrite database with some data! The next step is to read that data from a simple Node.JS codebase.
Making your first read
Appwrite’s native database service supports Create, Read, Update & Delete (CRUD) operations. Now that we have some data in our database, let’s go ahead and see how we can leverage that data from our code. For this, I’m going to use the Appwrite Node.JS SDK and the accompanying GitHub Repository.
First things first, let’s go ahead and set up our file structure.
In your IDE of choice, go ahead and spin up a project folder and create a read.cjs file within it. Feel free to leave the file blank for now.
Next, open up a new terminal window and run the following commands:
npm init
npm install node-appwrite — save
This will install the node-appwrite SDK to your project. You should now see a package-lock.json and package.json file both containing dependency references to the node-appwrite package.
In the Appwrite GitHub repository, you’ll want to find the list-documents code sample provided.
Head over to sdk-for-node/docs/examples/databases/list-documents.md. Copy and paste the code into your read.cjs file. Your file should now look like this:
Remember to reformat your code. Some of the lines may be incorrectly commented out when you initially paste the code sample into your file.
As you can see, we’re simply importing the node-appwrite SDK, creating a new client and database object then setting an API endpoint that will access our existing project, database and eventually collection.
In order to customize this fetch call, you’ll need to replace all of the strings in brackets with the corresponding information from your Appwrite project.
Please note: For the purposes of this tutorial, I’ll be hardcoding all of the values directly into my code, but if you’re planning on pushing a version of this code up to GitHub or running it in a live production environment, I highly recommend that you use environment variables to hide your database’s sensitive information.
To get your Database ID, you’ll need to head back to the drop down menu by clicking the ellipses on the top left of your screen. Click databases, and then click on the database we created earlier.
From there, hit the settings option, find the Database ID then copy and paste it into your fetch call. What you’re looking for will look like the following:
Go ahead and repeat the same process for Project ID and Collection ID.
For your API endpoint on line 9, simply replace [HOSTNAME or IP] with localhost.
Finally, you’ll want to generate a secret API key that you’ll be able to use to access your database remotely. Head back to the dropdown menu and select API Keys. Add an API key, give it a name and select all the Read and Write scopes relevant to databases. This will determine the level of access the API key will grant to your Appwrite project.
Once you’ve got that done, copy and paste the API key into line 11. Remember, this is just for demo purposes so the API key pictured will no longer exist by the time this article is published. I would urge you to treat your API key the same way you would treat a credit card number and avoid making it publicly available.
When you’re done, your code should look similar to the following:
In your IDE’s terminal, run the the following command:
node read.cjs
You should get the following response:
Just like that, you’ve just successfully made your first read from an Appwrite Database. Whoo hoo!
Making your first Write
Now that we know how to read from our database, writing to it will be a breeze.
Let’s head back to the Appwrite Node SDK GitHub Repository and find the create-document example. Head over to sdk-for-node/docs/examples/databases/create-document.md.
For the sake of time, let’s go ahead and repeat the same steps we did last time. In the same project folder, create a write.cjs file.
Once you’ve copied and pasted the create-document sample code into your write.cjs file, it should look like this:
Go ahead and replace the Database ID, API endpoint, Project ID, API key, Collection ID the same way we did previously. Since our Document ID was an auto-generated ID, we’ll want to use ‘unique()’ as the value for that variable. This function will auto-generate a unique ID for us when we execute our API call.
Since our document only contains one attribute, writing a new Food_Type into the database should be relatively simple.
The empty brackets at the end of line 13 should contain your write request in JSON format.
Go ahead and input the following key value pair.
‘Food_Type’: ‘Hamburger’
Once you’re done, your code should look like this:
Execute the file by running the following command:
node write.cjs
You should receive a response similar to the one pictured:
Once you head back to your Appwrite console and click into your database collection, you should find that your new Food_Type is listed amongst the available documents!
Congratulations, you just successfully wrote to your Appwrite database! Amazing!
What’s next?
This is just a small example of how Appwrite can help save you some development time on your next hackathon project and beyond. There’s an entire suite of features for you to explore and a ton of different SDKs to fit your specific skill set. From Python, Ruby, PHP, Kotlin, Swift, and so much more, Appwrite’s open-source service was built with every programmer in mind.
Appwrite is also in the process of setting up a cloud-native service for those of you who want an always-available solution for your API needs. You can sign up for early access by going to https://hackp.ac/appwrite-cloud.
In Summary
Along with having a brand new Appwrite database setup, you should also know how to programmatically leverage that database using Node.JS. On top of that, you have access to an entire GitHub repository of code-snippets that should provide you with working examples of all the functionality Appwrite has to offer!
If you’re looking for more ways to leverage Appwrite in your projects, check out the resources linked below!
That’s all for now so until next time, Happy Hacking!
