Persisting Data With Database Items

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

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:

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.

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.

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.