Migrate to Data Rules

If your app is currently using sync rules v2, this document outlines how to migrate your app to data rules.

Note: New apps created after 26 July 2022 will automatically have data rules enabled. The below migration steps are not applicable for these apps.

Important Note

Data rules is an advanced feature where implementation details can have a significant impact on app performance and in certain cases, app functionality. Further details are presented below.

Please be sure to understand the implications of implementing to data rules before deploying them to an environment with active users.

Migration process

Migrating from sync rules v1

If your app still uses sync rules v1, it is necessary to upgrade your app to sync rules v2 before migrating to data rules.

For apps using sync rules v2, a "Migrate to Data Rules" button will be visible at the top-right corner of the sync_rules.xml file in OXIDE. Alternatively, you can call the Migrate to Data Rules action via the command palette.

Migrate to Data Rules button

Once you confirm the migration by following the on-screen prompts, the following will occur automatically in the background:

• Your app's sync_rules.xml file will be replaced with a data_rules.xml file.

• Your existing sync rules will remain unchanged, however additional data rules will automatically be added to your data_rules.xml file to continue to support existing functionality in your app. Please see more details below.

• "Sync rules"/"sync bucket" terminology will be updated to "data rules"/"data bucket" throughout OXIDE. For example, to open the data rules XML file, type "data_rules" into the command palette.

A dialog will appear when the migration is completed. Deploy your app to testing to test the data rules.

Known limitation

Currently, comments in sync_rules.xml (e.g. <!-- This is a comment -->) will not be migrated to the data_rules.xml file. We suggest that you keep a copy of the sync rules file prior to migrating to data rules, and then manually adding back the comments afterwards.

Reverting the data rules migration

It is safe to revert the data rules migration in your app by reverting to a previous revision, or by discarding your draft or individual file changes in git-enabled apps.

Automatically created data rules

Certain data rules are automatically created when migrating your app from sync rules to data rules. Namely, these are rules to support OnlineDB queries and write operations, to mimic the previous behavior of sync rules. See the following sections for details about these implications when implementing data rules:

• OnlineDB access is disabled by default

• Object writes are only performed if the user has access before and after an update

The data rules migration will add a global-bucket with read="online" and write="any" rules for all models in your app.

For example, taking an app with the following data model:

schema.xml

<?xml version="1.0" encoding="UTF-8"?>
<data-model>
    <model name="user" label="User">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="district" />

        <display>{name}</display>
    </model>

    <model name="country" label="Country">
        <field name="name" label="Name" type="text:name"/>

        <has-many model="district" name="districts" />
        
        <display>{name}</display>
    </model>

    <model name="district" label="District">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="country" />
        <has-many model="customer" name="customers" />
        <has-many model="contact" name="contacts" />
        
        <display>{name}</display>
    </model>

    <model name="customer" label="Customer">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="district" />
        <has-many model="contact" name="contacts" />
        
        <display>{name}</display>
    </model>

    <model name="contact" label="Contact">
        <field name="name" label="Name" type="text:name"/>

        <belongs-to model="customer" />
        <belongs-to model="district" />

        <display>{name}</display>
    </model>

</data-model>

And the following sync rules:

sync_rules.xml

<?xml version="1.0" encoding="UTF-8"?>
<sync version="2">
    <!-- Sync the user object itself, required to access 'user' in the app. -->
    <bucket via="self" />
    
    <bucket via="self/district">
        <has-many name="customers" />
        <has-many name="contacts" condition="name != null"/>
    </bucket>

    <global-bucket>
        <model name="country" />
    </global-bucket>

</sync>

After the migration, the app's data rules will look as follows:

data_rules.xml

<?xml version="1.0" encoding="UTF-8"?>
<data-rules version="3">
    <bucket via="self"/>
    
    <bucket via="self/district">
        <has-many name="customers"/>
        <has-many name="contacts" condition="name != null"/>
    </bucket>
    
    <global-bucket>
        <model name="country"/>
    </global-bucket>
    
    <!-- Created during data rules migration: -->
    <global-bucket>        
        <model name="user" read="online" write="any"/>
        <model name="country" read="online" write="any"/>
        <model name="district" read="online" write="any"/>
        <model name="customer" read="online" write="any"/>
        <model name="contact" read="online" write="any"/>
    </global-bucket>
    
</data-rules>

The data rules migration created global OnlineDB access and explicitly added unrestricted write permissions for all models in the app: user, country (in this case, a rule was already defined for country, so it was left unchanged), district, customer, contact. You can remove or update these rules as necessary.

Notes:

• Having two global buckets defined in data rules, such as in the example above, has no functional impact. Feel free to merge the rules into one global-bucket.

• Data rules are "additive", meaning all sync/read/write rules will be applied. In the example above, the data rules migration created an essentially duplicate rule for country - the automatically created rule would be safe to remove in this case, as the existing rule is already allows unrestricted access to the country model.