Insites Docs Developers guide Data and UsersDatabase ItemsPersisting Data With Database Items

Persisting Data With Database Items

Last updated on June 26, 2024.

This document uses a real-world example to explain what happens at each stage of the Table definition life cycle.

Important

Most of the steps outlined in this article, particularly step #2 - #6, can be done with the help of the Instance Admin. This article merely demonstrates how the steps are done via code for educational purposes. You may visit the following documentation links to learn how to use the Instance Admin to execute the steps discussed in this article:


Step 1: Outlining your requirements

Let's take the example of a user who wants to store their to-do list on Insites. We can use a rudimentary table structure for the first step:

Todo list:

Task Priority
Clean apartment Low
Do homework High

Step 2: Defining a database file

Create a file in your project repository that will describe the database:

Step 3: Defining a database

Define the database. The code below is the description of properties that a Record will accept. It also contains the name of the Table object used to identify it.

Note

Please visit the Field Types and UI Elements documentation for a refresher on the approved list of types that you can use in your databases.

Step 4: Syncing/Deploying the database definition.

When you deploy, insites-cli asks the Insites backend if a Database (Table) object with the name already exists. If so, it updates with the given definition; otherwise, a new object is created.

You can verify this step with GraphQL query:

The result for that query, depending on the state of your Instance, should be similar to:

Step 5: Creating a database item

Create a database item using the Instance Admin by following the steps outlined in the Managing Database Items documentation. A summary of the steps involved are as follows:

  1. Select Databases on the main menu.
  2. Find the database you want to add a database item to and click on its Items row action link.
  3. Click on the ADD ITEM button at the top of the page. Fill out the fields on the form.
  4. Select SAVE when done adding items. This action takes you back to the page that displays all database items in a list. Alternatively, click the dropdown icon () on the SAVE button and select Save and add another. This saves your input and displays a new form for you to fill out instead of taking you back to the database items list.
Important

Each database item has a size limit of 2GB. Please get in touch with support@insites.io should you have more clarifications or need help optimising your project.

Step 6: Making changes to your database

As previously discussed, Database Items (Records) and Database (Table) objects are strictly related as the definition of database fields allows storing data in the Insites backend.

Once you have data persisted within a Database Item, you need to be aware of how changes in a Database (Table) can affect your Database Item (Record) objects:

  • Deleting a database definition

    You can only delete your Database Table if there are no related Database Items. Use the records_delete_all mutation to delete all the related Record objects.

    If you try to deploy with an orphaned Database Item, you will get the following message:

  • Changing the name of a database

    Insites detects a Table definition using its name. Changing it is equivalent to adding a new Table. Please note that Record objects are not automatically migrated and will be treated as orphaned with the next deploy attempt, as described in the error message above.

  • Adding a new field to a database

    Adding new database fields is a valid change that does not need additional actions; the data remains untouched.

  • Deleting a field from a database

    Deleting a database field is a valid change. Data stored in related Database Item properties will remain in the database but are rendered inaccessible. Use migrations to remove the data before the change.

  • Editing a database field

    Editing a database field is a valid change equivalent to removing a database field with an old name and subsequent creation of a new database field; the data is not migrated.

Step 7: Mutations

Steps #2, #3, and #4 can be done via the Insites Admin or with an admin_table_create mutation. The result would be exactly the same in your Instance.

Have a suggestion for this page?

Didn't quite find what you are looking for or have feedback on how we can make the content better then we would love to hear from you. Please provide us feedback and we will get back to you shortly.