Skuid Database

Contact your Skuid representative to access this feature.

Skuid Database is a data store that exists within your Skuid site. By using a Skuid database, you don’t need to connect to any external services to create and manage data for your Skuid apps.

A site’s Skuid database is managed within a Skuid workspace called the Database Console. From the Database Console you’ll build the structure of your database using objects and then making fields on those objects. Through its data grid interface it’s also possible to quickly populate records (though we don’t recommend using the Console as your primary means of data management).

A Skuid database can be used like any other data source in a Skuid page. You can use it in a Skuid model by selecting the Skuid Database data source type, and then selecting the name of your individual database.

Prerequisites

Before working with the Skuid Database data source type, there are a few important things to keep in mind:

  • Each Skuid environment can only contain one Skuid database

  • Skuid Database does not currently support the following:

    • Storing extremely sensitive data that requires encryption (like passwords)
    • Storing calculations and conversions for various types of data (primarily financial)

  • You cannot change a field’s data type once it is set. When creating your database take care to know what type of data you’ll be storing and carefully configuring your settings.

    • Only store data in the appropriate field type. For example, don’t store numerical data in Text fields or currency in number fields. Always check to see if there is a field type that correlates to the kind of data you’re storing.

  • Do not treat your database like a spreadsheet. Every cell on a row should relate to the record you are editing, which contrasts with the one-off calculations you might have in a spreadsheet cell. You can read more about how fields and records relate to each other in the Parts of a Skuid database section below.

  • Know which fields are required for your database before you create records. While it’s possible to create new required fields, or set fields to be required after they are created, doing so requires you enter a value to be applied to all existing records so the schema changes can be saved.

    Avoid the headache of updating all your records by determining which fields are required before you start entering data.

The parts of a Skuid database: Objects, fields, and records

Skuid database stores data in objects. These objects are configured with fields that describe the data. Users fill out those fields to create individual instances of data, which are called records.

As an example: An organization has an Account object. That object has fields, like Name and Account Owner, used to describe each individual account. Those individual accounts are stored as records.

Id Name Account Owner
1 Photon Factory Apollo Smith
2 Sandwich Truck Sara Sarasdottir

It’s not uncommon to hear your objects and fields referred to as metadata, or “data about your data” or schema, while your records are considered the true data of your database.

Objects

An object is a collection of settings, and fields that—when combined—describe a piece of data that should be stored in a database. Objects are often named after the data they’re describing, with individual instances of object data stored in records.

In the broader database world, objects are also referred to as tables, which is how they are represented visually.

Fields

A field is an attribute that describes your object. Name, description, phone number—all of these attributes are created as fields within an object. An object’s fields determine the type of data that can be stored within it as a record. Objects may also have relationships with other objects through reference fields, where users select another object’s record (represented by a chosen display field, usually Name) as a value for the current object’s field.

In the broader database world, fields are also referred to as columns, which is often how they are represented visually in a table.

Records

A record is a single instance of data described by an object’s fields. While objects and fields determine the rules of how data is entered, records contain the actual data described by those rules.

In the broader database world, records are sometimes referred to as rows, which is often how they are represented visually in a table.

Creating and Managing a Skuid Database in the Database Console

To create a Skuid database:

  1. Navigate to Data Sources.
  2. Under the Skuid database header, click Create.
  3. Provide a name for the database.

After this you’ll see the Database Console. This workspace is made up of three primary areas:

  • The left panel is primarily for navigation. You’ll use this to create objects and navigate between them, as well as their subsections.
  • The center area updates to reflect the part of your database you are currently configuring. When editing the records of your database, you’ll see a data grid. The top of this grid will display all the fields you’ve created. It’s possible to create new Fields by clicking the top button, or to create new records by clicking the bottom left button. For more information on record-level control, see the Working with the Console’s data grid section.
  • The right panel is for setting properties for your selected database element, similar to the Properties pane in the Composer. You’ll most often be setting the properties of new fields or updating existing field properties here.

You’ll click between these three areas often while constructing the structure of your database.

Saving your changes

Metadata changes, like changing your objects and fields, requires confirmation by pressing Create or Apply.

Changes to data are autosaved whenever you move away from a cell unless there is a validation error in the record. You’ll need to correct any validation errors or discard the problematic changes before proceeding. If you navigate away from the page while a record has validation errors that record will not be saved.

If you add a new required field you must enter a value that is applied to all existing fields. You can adjust each record’s field value later if needed.

Keyboard shortcuts

Mac [[]]

  • CMD + SHIFT + O: When in the Objects tab of the left panel, creates a new object

  • CMD + SHIFT + F: When an object is selected, creates a new field

  • CMD + ENTER: Creates a new record

  • CMD + /: Focuses on the search bar of the current screen, searching fields within the Fields and data tab and searching permission sets within the Access control tab.

  • Pressing Escape undoes object and field creation and unfocuses the search bar.

    • Pressing Escape does not undo record creation.

Windows [[]]

  • CTRL + SHIFT + O: When in the Objects tab of the left panel, creates a new object

  • CTRL + SHIFT + F: When an object is selected, creates a new field

  • CTRL + ENTER: Creates a new record

  • CTRL + /: Focuses on the search bar of the current screen, searching fields within the Fields and data tab and searching permission sets within the Access control tab.

  • Pressing Escape undoes object and field creation and unfocuses the search bar.

    • Pressing Escape does not undo record creation.

Managing objects

Objects are created and managed from the Database Console. Once you’ve created an object, the following tabs are available:

  • Fields: A view for creating and viewing all previously created fields for an object, as well as system-generated “audit fields” that describe who created or updated a record and when
  • Data: A data grid view that allows for both field and record creation within the object
  • Access control: A view for assigning object access and object conditions to site permission sets
  • Conditions: A view for creating object conditions, which determine how and when a user can view and interact with a record.

Creating objects

Creating new objects can be done by clicking Create when no objects exist, or clicking add New object in the left panel when no objects are selected.

When creating objects, enter the following properties:

  • Label: The user-facing name for the field that will appear in Skuid components connected to this database.

  • Label plural: The user-facing name for the field when it must be pluralized in the UI.

  • Object Id: The internal API name for the field—which is used by page XML and Skuid’s APIs to refer to the field. This is autopopulated based on the field’s label.

    You typically won’t be interacting with your field IDs unless you’ll be extending Skuid with code. But unlike labels, IDs cannot be changed once a field is created. Be sure the ID accurately reflects the field before saving.

  • Description: Describes the intended purpose and use of the object.

Updating objects

  1. Click the object’s name in the left panel’s Objects list. If you have a different object selected, you’ll need to click the chevron-small-left Back icon first to return to the Object list.
  2. Click dots-vertical More options.
  3. Click Configure.

You can update all object properties except the object’s Id.

You can also set an object’s display field, after creating at least one field. This is the field whose value is displayed when referenced from another object. An object’s display field is almost always its Name field.

For example, a Song object will probably have an Artist reference field. The Artist object’s display field should be Name, so that the name of the artist displays on the song record—in contrast to the Artist object’s Genre or Country fields.

Deleting objects

  1. Click the object’s name in the left panel’s Objects list. If you have a different object selected, you’ll need to click the chevron-small-left Back icon first to return to the Object list.
  2. Click dots-vertical More options.
  3. Click Delete.

At this point, Skuid checks for any dependencies on the object—references from other objects that rely on this object.

For data integrity, objects cannot be deleted if they’re referenced from another object in your database, such as a reference field. You’ll need to either update or delete all reference fields that refer to this object.

Fields and Data

Creating fields

  1. Navigate to the object you wish to create a field on.

  2. It’s possible to create fields in the Fields tab or the Data tab.

    • From the Fields tab: If no fields have been created, click Create. If some fields already exist, click New field.
    • From the Data tab: Click add-column New field in the center header above the data grid.

  3. Set the field’s properties:

    • Type: Determines the type of data that can be stored in this field. Be sure to select a type appropriate for the information you wish to store in this field.

      Warning

      You cannot change a field’s type later. If you find a field needs a different type, you’ll need to recreate the field and all field values manually. Be certain of your chosen field type.

      Be particularly wary of relying on Text or Textarea field types. There could be better, more specific field types to use instead.

    • Label: The user-facing name for the field that will appear in Skuid components connected to this database

    • Field ID: The internal API name for the field—which is used by page XML and Skuid’s APIs to refer to the field. This is autopopulated based on the field’s label.

      You typically won’t be interacting with your field IDs unless you’re extending Skuid with code. But unlike labels, IDs cannot be changed once a field is created. Be sure the ID accurately reflects the field before saving.

    • Required: Indicates that a record cannot be saved unless this field has a value entered.

      Warning

      Be wary of making a new required field in a database that already has many records of data. If a database already has records, you must set values for these required fields for all records on creation to save the field.

    • Read-only: Indicates that users cannot input a value in this field through the UI.

      This field property is not a permissioning feature, but a client-side experience. Users can still perform actions that will update the field’s value—typically via an action or an insert/update object condition.

    • Default value: Sets the value that prefills the field once the user creates a new record. Value options vary depending on the field type.

    • Description: Describes the purpose of the field, only visible to those managing Skuid database.

    • Help text: A tooltip indicator appears beside this field in Skuid components. When hovered over, that tooltip displays this field’s help text. This text should help guide users on what data they should enter in this field.

  4. Set any additional field properties based on the field’s type.

  5. Click Create.

Deleting fields

Before you delete a field, you must update or delete any references to that field within your database. If other objects reference the field via a reference field, or if the field is used in an object condition, you must update or delete those references first.

And while Skuid will not prevent you from deleting a field used in your Skuid pages, you’ll need to manually update those pages to prevent builder errors in the Composer and runtime errors for end users.

  1. Navigate to the object you wish to delete a field on.
  2. Click Fields and data.
  3. Click the column header of the field you wish to delete.
  4. Click Delete field.

Working with the Console’s data grid in the Data tab

When editing objects in the Database Console, the Data tab’s center section shows a spreadsheet-like interface that takes advantage of the Table component’s data grid mode. You can quickly create and update both data and fields from this tab. When you select more than one row, the standard cell options turn into the mass actions available—delete and mass edit.

For information on the keyboard interactions and general controls of this interface, see the Data grid documentation.

Access Control

The Access Control tab provides an overview of how much access your site’s permission sets have to an object, with each permission set displayed as a card. The top of each permission set’s card displays an estimate of how much access it has (No access, Some access, and Full access).

Note

  • Only site permission sets appear as a card on this tab. App-specific access should be set within the app’s permission sets.
  • It’s important to note that Skuid admins have full permissions to newly created objects by default. You’ll need to manually go in and disconnect those permissions.

Within each permission set card, you can choose between basic permissions or advanced permissions:

  • Basic: Permissioning is set at the object level, applying equally to all fields.
  • Advanced: Permissioning can be set at the field level, with specific operations only possible on configured fields

Warning

You are making a binary choice between basic and advanced permissions, as they handle permissions in different ways. Because of this, be wary of switching back and forth between the two:

  • If you switch from Basic to Advanced, then all field-level level permissions will be checked if their object permission is checked. This means that you’ll uncheck the permissions you wish to take away.

    If you enable the Update object permission, and then switch to advanced permissioning, all fields will have the update permission applied.

  • If you switch from Advanced to Basic, then all field-level settings are discarded and permissions revert to the object permissions.

    If you enable the Update object permission, uncheck several fields to remove a permission set’s update access to a field, and then revert back to basic permissioning, all fields will be updateable once again because the Update object permission will apply again.

Basic permissions

With basic permissions, a permission set has the same level of access to all fields. This is most useful for objects without stringent security needs, as it allows you to quickly configure access.

For example, allowing Read and Update on an permission set would allow all owners of that permission set to read and update all fields within that particular app.

Advanced permissions

Advanced permissioning allows field-level security, making it possible to create a variety of access configurations:

  • Allow users to read records but prevent them from creating records
  • Allow users to read all fields but only update certain fields

This is accomplished by setting object permissions and field permissions separately. Object permissions determine whether or not a field permission can even be granted—they do not directly control whether or not users can do the action. Once an object permission is enabled, it’s then possible to set field permissions.

Note

Fields marked as read-only cannot be created/updated and appear disabled in the advanced permissions screen.

Conditions

Object conditions are used to either limit data returned to the user or to enforce certain data values before doing an operation based on a field’s value.

Note

Because condition needs can vary depending on the user, conditions have no effect until they are assigned to permission sets. See the Assigning conditions to permission sets section.

The type of condition determines its behavior once assigned to a permission set:

  • Query conditions: Limit the data returned to the user based on a field value
  • Update conditions: Only allows record updates when field values meet certain criteria
  • Insert conditions: Enforces field values when new records are created
  • Delete conditions: Only allows record deletion when field values meet certain criteria

Update, insert, and delete conditions all have assumed AND logic, meaning that every condition of that type must be true.

Assigning conditions to permission sets

Conditions can be assigned to site permission sets from the Access control tab. Click the Conditions dropdown menu and select one or more conditions to apply to the permission set.

Conditions can be applied to app permission sets by navigating to the Data source access tab of the app permission set’s details and clicking to configure the Skuid database’s permissions.

Importing data

It’s possible to import CSV data on a per-object basis, allowing you to create fields based on your CSV data—or map the columns to existing fields.

Prerequisites

Before you begin, be aware of the following:

  • Imports are done per-object. It’s not possible to import multiple objects via a CSV file.
  • The import process assumes the CSV has a header.
  • Reference fields are not currently supported. Any imported reference fields that are mapped to a field are treated as strings.
  • CSV files cannot be larger than 1MB. Larger files may result in errors.

Most errors in the import process occur because imported field values don’t match the format Skuid expects. Check the following:

  • Any imported required fields must have a value.

  • Any imported checkbox values must be TRUE or FALSE.

  • Any imported date or datetime values must be formatted as Skuid expects:

  • Any number-related fields (currency, number, percent) can only contain numerical characters.

  • Any email fields are in email format, like example@example.com.

  • For picklist data you wish to import, create picklist options before starting the import.

    Note

    Because multi-picklist fields can accept “none” as a value, this step is not necessary for that field type. Regardless, setting up picklist options first is recommended.

Uploading a CSV file to import

To begin importing records from a CSV file:

  1. Create a new object or navigate to an existing one.

  2. Click dots-vertical More options.

  3. Click Import data. A file upload modal appears.

  4. Drag the file from your file explorer into the upload area or click the upload area to browse your files—confirming your selection once you’ve found the file.

    Note

    The upload process may take a moment. Do not close the modal or browser window until the upload is complete.

  5. After the file has uploaded, click Continue. The field mapping screen appears.

If there was an error in your CSV file, you’ll be prompted to download an annotated CSV and fix those errors before proceeding. For more information, see the Handling import errors section.

Import options

Create missing picklist options

When enabled, this auto-creates any picklist values that aren’t already an option for the field.

For example, assume a field named Sandwich has 5 picklist options:

  • Cow
  • Chicken
  • Sprouts
  • Mushroom
  • Cheese

When importing a CSV file with a row containg Spinach as the Sandwich field’s value, enabling the Create missing picklist options property would result in a new picklist value being creating for the field in Skuid Database. The field’s picklist values would then look like this:

  • Cow
  • Chicken
  • Sprouts
  • Mushroom
  • Cheese
  • Spinach

Import header row as data

When enabled, the first row of the imported CSV is treated as data instead of a column header. This can be useful for CSV import data split across multiple files, where headers may not be present in all files.

Mapping CSV columns to fields

After uploading the CSV, you’ll use the field mapping screen to map CSV columns to fields that exist in your database—or create new fields as needed.

This screen includes the following:

  • A preview of your imported data

    This is only a reference view of the first few rows. It displays the CSV data as Skuid understands it from your imported file—including all columns. You won’t make changes in this area.

  • The Field mapping panel. Here you’ll select the columns to import as fields. Any unmapped columns won’t be imported into your database.

  • A right panel, which updates to display a selected field’s properties

  • A header with the option to Import records or Cancel

    The Import records button updates to display the total number of records that’ll be created by an import. So if you are importing a CSV file with 100 correctly formatted rows, the button says Import 100 records.

    If the number within this button does not match the expected number of records, ensure your CSV file is properly formatted.

    Note

    The Import records button will not enable until at least one field has been mapped.

To import a column as a field:

  1. Click the toggle beside the CSV column name. This enables the Field selector.

  2. Click the dropdown list under the Field selector.

  3. Select a pre-existing field or click Create new field.

    • If Skuid detects a CSV column name that matches an existing field, it automaps that field.

    • If creating a new field, the standard create field panel appears on the right side of the browser window. When finished, click Create.

      Note

      Fields created from this screen persist even if the import is canceled.

    • If selecting a pre-existing field, you can click Configure to adjust that field’s properties. This can be useful if you need to adjust some field behaviors to account for your imported data.

    Note

    If your Skuid Database object has a required field, you must map a CSV column to that required field.

Once you’ve completed field mapping, click Import records to begin the import. Confirm the import by clicking Import in the modal that appears.

Warning

Do not navigate away from the import page once an import has begun. This could cause incomplete data to be imported.

Handling import errors

When Skuid detects an error in an imported CSV file, the import process may fail. Errors may be caused by bad syntax within the CSV file itself or a mismatch between the field’s values and the type of data Skuid expects from a mapped CSV column.

If you have a malformed CSV file: The upload will be canceled, and you’ll see a toast message saying Error reading CSV file. The import process does run and it does not return an annotated CSV. You’ll need to diagnose the CSV issues in an external editor. Common culprits include unsupported uses of quotation marks (' or "), new line characters, or commas ( , ) within field values.

If the CSV file has no syntax errors: You’ll proceed to the field mapping screen to continue the import. If field format mismatches are found, a modal appears with a link to download an annotated version of your CSV. Use this CSV to diagnose and correct issues, then re-upload this CSV. Your previous field mappings will be saved.

To download the annotated CSV and resolve errors:

  1. In the Import failed modal, click Download CSV.
  2. Open the CSV in your spreadsheet program of choice.
  3. Observe the Errors column.

The Errors column lists any issues a row raised during the import process. These are often field mapping issues, where the field format Skuid Database expects (based on the field’s properties) does not match the imported CSV file’s field values.

Most errors in the import process occur because imported field values don’t match the format Skuid expects. Check the following:

  • Any imported required fields must have a value.

  • Any imported checkbox values must be TRUE or FALSE.

  • Any imported date or datetime values must be formatted as Skuid expects:

  • Any number-related fields (currency, number, percent) can only contain numerical characters.

  • Any email fields are in email format, like example@example.com.

  • For picklist data you wish to import, create picklist options before starting the import.

    Note

    Because multi-picklist fields can accept “none” as a value, this step is not necessary for that field type. Regardless, setting up picklist options first is recommended.

While you may need to adjust the formatting of a column’s fields in some cases, most errors occur because of incorrect mapping. In that case, Delete the Errors column in the annotated CSV and attempt the import again.

When you attempt to re-import the CSV, Skuid remembers the previously mapped fields. If your error was related to field mapping, be sure to adjust these settings.

Exporting data

It’s possible to export a single object as a CSV file or multiple objects as a ZIP archive of CSV files. These CSV files can be used as backups or as a means to transfer data into a different Skuid Database or another storage service.

To export a single object as a CSV:

  1. Navigate to the object to export.
  2. Click dots-vertical More options.
  3. Click Export data.

The CSV file downloads to your local machine.

To export multiple objects as a ZIP archive of CSV files:

  1. Click the Objects view.
  2. Click Export to CSV at the bottom of the left panel.
  3. Check the box beside each object you wish to export. The Export button updates to reflect the number of chosen objects.
  4. Click Export CSV.

The ZIP file downloads to your local machine.

Export options

When exporting objects, you can enable the Sanitize field values option within the Advanced section, which helps prevents malicious formulas from running in other applications.

This option prepends all field values with a single quote and wraps them in double quotes to ensure these values are treated as strings.

So this value:

=A4+'PotentiallyMaliciousFormula'+@

Becomes this value in the exported CSV:

"'=A4+'PotentiallyMaliciousFormula'+@"