Databases Introduction

Databases are where your site keeps its own data. A database is a table. Each table has properties, which are its fields, and each row you store is a record. You define tables in code, read and write records with GraphQL, and see them in the admin under Databases.

Check a module first

Before you create a table, check whether an Insites module already stores that data. Contacts, companies, activities, tasks, opportunities, orders, products, events and locations all have tables and controllers. If you rebuild one by hand, you lose the admin screens, the validation and the API that come with it.

Define a table

name: enquiry
metadata:
  label: "Website Enquiries"
properties:
  - name: full_name
    type: string
  - name: message
    type: string
  - name: answered
    type: boolean

Syncing the file creates or updates the table. A full deploy is not needed for a schema change.

Give each table that people open in the admin a label, field groups and a tooltip on every field. Then the next person knows what each field holds.

Example: list the tables on an instance

{
  admin_tables(per_page: 3) {
    total_entries
    results { name }
  }
}

{
  "data": {
    "admin_tables": {
      "total_entries": 28,
      "results": [
        { "name": "ds_page_feedback" },
        { "name": "ds_promo" },
        { "name": "ds_search_event" }
      ]
    }
  }
}

This ran read-only on the docs.insites.io instance on 1 November 2026. Across its 28 tables, the property types in use were string, boolean, upload, integer and date.

Common mistakes

• Renaming a property that already holds data. Rows keep the old name, so their values are orphaned.
• Sorting by a number stored as a string. It sorts as text, so 10 comes before 2.
• Expecting a deleted record to vanish at once. record_delete keeps it for 30 days.

• Database fields and tablesEvery property type and option.
• Querying your databasesRead records with GraphQL.
• ArraysStore lists in one property.