DataStores

A DataStore is a module's storage for its items: blog posts, audio files, profiles. It stores keys and values, not fixed columns, so any module can add keys to another module's items without changing tables. Tags, ratings and Form Designer fields are all stored this way.

Each module has at most one DataStore. Every item gets system keys automatically: _item_id, _profile_id, _user_id, _created and _updated. All other keys start with the module's DataStore prefix.

In schema.php:

function xxFoo_db_schema()
{
    jrCore_db_create_datastore('xxFoo', 'foo');
    return true;
}

The prefix is foo, so the module's keys are foo_title, foo_text and so on. Run an Integrity Check to create the tables.

Don't write SQL for a DataStore. Use the functions:

// Create: returns the new item ID
$id = jrCore_db_create_item('xxFoo', array(
    'foo_title' => 'My first foo',
    'foo_color' => 'red'
));

// Read: the item's keys, plus keys other modules add
$_it = jrCore_db_get_item('xxFoo', $id);

// Update: changes these keys, adds new ones, leaves the rest
jrCore_db_update_item('xxFoo', $id, array('foo_color' => 'blue'));

// Delete
jrCore_db_delete_item('xxFoo', $id);

// Search
$_rt = jrCore_db_search_items('xxFoo', array(
    'search'   => array('foo_color = blue'),
    'order_by' => array('_created' => 'numerical_desc'),
    'limit'    => 10
));
// $_rt['_items'] holds the items

jrCore_db_search_items() takes the same options as the {jrCore_list} template function: see {jrCore_list}. The docblocks in modules/jrCore/lib/datastore.php describe every function and option.

• Fetch by ID when you can. jrCore_db_get_item() and jrCore_db_get_multiple_items() stay fast on very large DataStores.
• Avoid like '%text%' searches on large DataStores: they can't use an index. Use the Search module's index for free text.
• Pass 'exclude_jrProfile_quota_keys' => true to a search when you don't need the profile's quota settings in the result.

A module can also have ordinary tables, created with jrCore_db_verify_table() in schema.php. Use them for data that isn't items, such as logs. See Module File Structure.

Admins can look at any module's items with the DataStore Browser on its Tools tab.