DEV Community

loading...
Cover image for #30DaysOfAppwrite : Appwrite Database
Appwrite

#30DaysOfAppwrite : Appwrite Database

Christy Jacob
・5 min read

Intro

Appwrite is an open-source, self-hosted Backend-as-a-Service that makes app development easier with a suite of SDKs and APIs to accelerate app development. #30DaysOfAppwrite is a month long event focused at giving developers a walkthrough of all of Appwrite's features, starting from the basics to more advanced features like Cloud Functions! Alongside we will also be building a fully featured Medium Clone to demonstrate how these concepts can be applied when building a real world app. We also have some exciting prizes for developers who follow along with us!

Appwrite Database

Welcome to Day 15 👋. Today is finally the day to cover storing data in the Appwrite database. Appwrite offers an easy-to-use , document-based database API for storing your app's data. We built our NoSQL interface on top of MariaDB, inspired by Wix who did the same. MariaDB provides its battle-tested stability and performance, and you can manage Appwrite using existing, familiar database tools like MySQLWorkbench, phpMyAdmin, and more. Collections, documents, rules, and permissions can all be managed with the Appwrite console, or with any one of our SDKs. There's a lot to cover, so let's dive in.

A database refactor is underway to improve overall performance and add support for a variety of databases, including PostgreSQL, MongoDB, and more!

Glossary

Each database comes with its own set of technical jargon - before we get too far, let's go over ours.

  • Collection: A group of documents. Each collection has rules to define its document structure and permissions for read and write.
  • Document: A structured JSON object of keys and values, belonging to a collection. Keys and their types are defined in a collection rule.
  • Rules: The definition of each document attribute. It has a label, key, and rule type. Think of them as columns in a traditional relational database. Columns have a name, value and type
  • Permissions: Array of strings that define the access control to documents, collections, and files in storage.

Now, let's review each in more detail.

Collections and Documents

In short: collections hold documents. If you're a SQL veteran, you might know these better as tables and rows (and internally, that's technically correct). Each collection gets a unique, random collectionID and holds documents (in other words, the raw data). The kind of data that Appwrite accepts is governed by attribute rules defined for the collection.

Rules

Simply put, rules outline what your documents should look like. With this approach, Appwrite's rule validators ensure the data going into your database is the exact format you expect. So, for each key-value pair of our document, we provide:

  • a label, just for display
  • the name of the key
  • the rule type
  • the default value
  • if the key is required
  • if the value is an array

Here are the validators available for rule types:

Rule Type Description
text Any string value.
numeric Any integer or float value.
boolean Any boolean value.
wildcard Any value.
url Any valid URL.
email Any valid email address
ip Any valid IPv4 or IPv6 address

Permissions

To control access to resources, Appwrite offers developers a flexible permission system that is aware of Appwrite users and teams. Let's cover the most used permissions:

Permission Description
* Wildcard permission. Grants anyone read or write access.
user:[userID] Grants access to a specific user by userID.
team:[teamID] Grants access to any member of the specific team. Note: the user must be the team owner or have accepted a team invite to grant this access.
team:[teamID]/[role] Grants access to any member who possesses a specific role in a team. Roles can be assigned on invite.
member:[memberID] Grants access to a specific member of a team, only while they are still a member of the team.
role:guest Grants access to any guest user who isn't logged in.
role:member Grants access to any logged in user (a user with a valid session). Logged in users don't have access to role:guest resources.

Note: documents don't inherit permissions from its parent collection.

Filters

The listDocuments() accepts an array of filter strings so that you can extract just the documents you need from the Appwrite database. A filter is made up of the following:

  • The attribute to filter
  • A comparison operator: one of =, !=, >, <, <=, >=
  • The target value

Here are a few examples using our Books collection:

  • 'title=The Hobbit'
  • 'director!=Woody Allen'
  • 'published>=2000'

Putting it all together

As an example, let's create a collection of books in Appwrite. While some projects require creating collections programmatically, others are easier to create with the Appwrite console.

Create collection

A book has a title, author, and the year it was published. Let's add those, starting with title using the text rule type:

Add Title Rule

If you see, new rules are not required by default. Let's make title required:

Make Title Required

Now, we can do the same for author and published, using the numeric rule type for publication year, so we now have:

Add Published Rule

Permissions, by example

Now that our Books collection has the necessary rules, we can create documents and restrict access as necessary. Check out the following code:

let sdk = new Appwrite();
sdk
    .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
    .setProject('5df5acd0d48c2') // Your project ID
;

let promise = sdk.database.createDocument(
    '609bdea2f0f99', // collectionID for Books
    {'title': 'The Great Gatsby', 'author': 'F. Scott Fitzgerald', 'published': 1925},
    ['role:member'],
    ['team:5c1f88b87435e/owner', 'user:6095f2933a96f']);
Enter fullscreen mode Exit fullscreen mode

In this example, the new book from createDocument can be read by any logged in user, but only the owner of Team 5c1f88b87435e and User 6095f2933a96f have the permissions to write (or update) .

Nested Documents

There is one more rule type that I didn't mention until now: a nested document, for when you need to store one document inside another. This is best shown by example, so let's use our Books collection.

Say that we also had a collection for Authors to keep our data organized. Using the nested document rule, we can cross-reference the Authors collection when creating new books. Our document for "The Great Gatsby" that we created above would look like:

let promise = database.createDocument(
'609bdea2f0f99', // collectionID for Books
{
  'title': 'The Great Gatsby',
  'published': 1925,
  'author': {
      '$collection': '', // The actors collection unique ID
      '$permissions': {'read': ['role:member'], 'write': ['team:5c1f88b87435e/owner', 'user:6095f2933a96f']}, // Set document permissions
      'name': 'F. Scott Fitzgerald'
    }
  ]
},
['*'], // Read permissions
);
Enter fullscreen mode Exit fullscreen mode

Credits

We hope you liked this write up. You can follow #30DaysOfAppwrite on Social Media to keep up with all of our posts. The complete event timeline can be found here

Feel free to reach out to us on Discord if you would like to learn more about Appwrite, Aliens or Unicorns 🦄. Stay tuned for tomorrow's article! Until then 👋

Discussion (0)

Forem Open with the Forem app