In the last article on the Isar Database Package, we looked at the basics. Today we want to move away from the basics and understand more the concepts behind Isar. To do this, let’s look at the schema of the database.

Annotating classes

As we learned in the last article, you annotate normal classes with @Collection() so that Isar will find that class. Well, we didn't discuss that you can put two parameters in the parentheses.

The first parameter is **inheritance**. inheritance is a bool and defaults to true.

by default. But what does inheritance do? Well, let's say you have a parent class or a mixin. With this you can easily determine if these fields should be stored in Isar or not.

Okay, but what is the second parameter? This is **accessor**. With accessor you can specify the default collection accessor. Okay okay, that sounds complicated now. But it is not. Let's say you have a class called Contact. To access it with Isar you write isar.contacts. But what if you want to use isar.myContacts for example? Well, then you set the accessor parameter to myContacts.

Id

Every object in Isar needs an id to identify the object. This should preferably be an int. If one of your properties is already named id, Isar recognizes this automatically. But now our property should be called contactId. In this case Isar will not recognize that it is the id. Therefore you have to annotate this property with @Id(). Now Isar knows exactly that this property is your id.

If you now create an object, which you might later add to your database, you don’t have to specify the id separately. Isar does this for you. However, you still have the option to specify the id yourself or use Isar.autoIncrement to increment the id automatically. This will do exactly the same as not setting the id at all.

Supported types

Last time we created a contact database. There we once had the property nameof type string. We also had the property phone of type int. But which data types can I also use?

• bool
• int
• double
• DateTime
• String
• Uint8List
• List<bool>
• List<int>
• List<double>
• List<DateTime>
• List<String>

It’s very important that you understand how nullability works in Isar. Number types do not have a dedicated **null** representation. A specific value will be used instead.

For ints, there will be used int.MIN in VM and -Infinity on the web.

For doubles, there will be used double.NaN in VM and -Infinity on the web.

bool, String, and List have separate null representations.

This null behavior allows Isar to make large performance improvements. This “also allows you to change the nullability of your fields freely without requiring migration or special code to handle nulls."

On the web, NaN is not supported. This is due to IndexedDB. IndexedDB is, in short, a programming interface to store data in the browser.

Ignoring fields

It is set by default that any public field that is in a class will be in the Isar database. However, if you don’t want a field to be included, you can annotate it with **@Ignore()**. However, it is not a good practice to store information in an Isar object that is not observed by Isar.

Renaming classes and fields

You can annotate classes and fields with **@Name()** to name them differently in the database than you did in your code. In the brackets you put the new name as string argument. If you change the class name or field without @Name(), it will just be dropped and recreated.

The contact class in Dart might now look like this, but the generated code will follow the exact same pattern as the other code:

Schema migration

If you want to change schemas between releases of your app, you can do so without issue. However, Isar has a few rules that you should be sure to follow:

You are allowd to:

• Add & remove collections
• Add & remove fields
• Change the nullability of a field (e.g. int -> int? or List<String?>? -> List<String>)
• Add and remove indexes
• Add and remove links
• Switching between Link<MyCol> and Links<MyCol> (no data will be lost)

You should be careful with:

• Renaming a field or collection that is not commented with @Name(). The field or collection will be deleted and recreated

You must not:

• Recreate deleted fields with a different type
• Change the type of fields in existing collections (even in previously deleted ones)
• Create a unique index for a property with duplicate values

Conclusion

Today you have learned about the schemas of Isar database. You now know how to annotate classes for Isar, what datatatypes Isar supports, and how to migrate schemas.

In the next few articles, we’ll take a closer look at the database’s Create, Read, Update, and Delete objects.

If you don’t want to miss all this, be sure to follow me!

Thanks for reading, have a nice day.

Note: This article is based on Isar’s documentation. The purpose behind it is to better understand the different parts of the code. In today’s article, “scheme” was referred to. The original version can be found here: https://isar.dev/schema.html