Operations in Transactions

In this section, we will explore the various operations that can be performed within transactions in NimbusDB.

We’ll use this schema and the items model and catalog as an example:

GML

var schema = {
    id: {
        type: NIMBUSDB_DATA_TYPE.INTEGER,
        const: NIMBUSDB_CONSTRAINT.PRIMARY_KEY
    },
    name: NIMBUSDB_DATA_TYPE.STRING,
    price: {
        type: NIMBUSDB_DATA_TYPE.NUMBER,
        validator: function(data, value) {
            return value >= 0;
        },
        default_value: 0
    },
    is_locked: {
        type: NIMBUSDB_DATA_TYPE.BOOLEAN,
        const: NIMBUSDB_CONSTRAINT.OPTIONAL,
        default_value: false
    }
};

// `items` model
items = new NimbusDBModel("global", "items", schema, [
    { id: 1, name: "Apple", price: 5 },
    { id: 2, name: "Banana", price: 7.2 },
    { id: 3, name: "Cherry", price: 15 },
    { id: 4, name: "Date", price: 12.5 },
    { id: 5, name: "Elderberry", price: 8 },
    { id: 6, name: "Fig", price: 10 },
    { id: 7, name: "Grape", price: 6 },
    { id: 8, name: "Honeydew", price: 9 },
    { id: 9, name: "Kiwi", price: 4 },
    { id: 10, name: "Lemon", price: 3 }
]);

// `items` catalog
ctg_items = new NimbusDBCatalog("items", {
    model: items
});

CRUD Operations

Create (Insert)

The create operation allows you to add new records to a model within a transaction. You can use the .insert() method of the transaction object to perform this operation.

GML

items.transaction(function(tx) {
    tx.insert({ id: 11, name: "Mango", price: 7.5 });

    tx.insert([
        { id: 12, name: "Nectarine", price: 6.5 },
        { id: 13, name: "Orange", price: 5.5 }
    ]);

    tx.commit();
});

Tip

Read the Insert Operations section for more information about the .insert() method.

Read (Get)

The read operation allows you to retrieve records from a model within a transaction. You can use the .get() method or its derived methods (.get_by_index(), .get_by_primary(), .get_by_value(), and .get_by_function()) to perform this operation.

GML

items.transaction(function(tx) {
    var apple = tx.get({
        primary: 1,
        access: NIMBUSDB_DATA_ACCESS.LINKED
    });

    var banana = tx.get_by_index(1);

    var mango = tx.get_by_primary(11, {
        access: NIMBUSDB_DATA_ACCESS.LINKED
    });

    var nectarine = tx.get_by_value("name", "=", "Nectarine");

    var orange = tx.get_by_function(function(data) { return data.name == "Orange"; });

    tx.commit();
});

Tip

Read the Read Operations section for more information about the .get() method.

Update

The update operation allows you to modify existing records in a model within a transaction. You can use the .update() method or its derived methods (.update_by_index(), .update_by_primary(), .update_by_value(), and .update_by_function()) to perform this operation.

GML

items.transaction(function(tx) {
    tx.update({
        primary: 1
    }, {
        name: "Green Apple",
        price: 6.5
    });

    tx.update_by_index(1, {
        name: "Golden Banana",
        price: function(data) { return data.price + 2.3; }
    });

    tx.update_by_primary(11, {
        name: "Sour Mango",
        price: function(data) { return data.price - 0.5; },
        is_discount: true
    });

    tx.update_by_value("name", "Cherry", {
        name: "Twisted Cherry",
        price: 12.3
    });

    tx.update_by_function(
        function(data) { return data.price > 10; },
        {
            price: function(data) { return data.price * 0.9; }
        },
        {
            match_all: true
        }
    );

    tx.upsert([
        { id: 2, name: "Golden Banana", price: 12.6 },
        { id: 13, name: "Peach", price: 4.67 }
    ])

    tx.commit();
});

Tip

Read the Update Operations section for more information about the .update() method.

Delete (Remove)

The delete operation allows you to remove records from a model within a transaction. You can use the .remove() method or its derived methods (.remove_by_index(), .remove_by_primary(), .remove_by_value(), and .remove_by_function()) to perform this operation.

GML

items.transaction(function(tx) {
    tx.remove({
        primary: 1
    });

    tx.remove_by_index(1);

    tx.remove_by_primary(11);

    tx.remove_by_value("name", "Cherry");

    tx.remove_by_function(function(data) { return data.price > 10; });

    tx.commit();
});

Tip

Read the Remove Operations section for more information about the .remove() method.

Using External Variables Inside Transactions (Closures)

A closure is a function that has access to the outer (enclosing) function’s variables, allowing it to access and modify them. In NimbusDB, you can use closures to pass variables from the outside to the inside of a transaction.

If you hardcode the data like previous examples, there’s no point in using transactions in the first place, because it either always succeeds or always fails.

GML

Without Closures

items.transaction(function(tx) {
    tx.insert([
        { id: 11, name: "Mango", price: 7.5 },
        { id: 12, name: "Nectarine", price: 6.5 },
        { id: 13, name: "Orange", price: 5.5 }
    ]);

    tx.commit();
});

There’s no point in using transactions in the first place, because there’s no real “variable” value that may change when the game is running.

With Closures

// if you're using the transaction in any object event, you MUST NOT use the `var` keyword to define the variables
 var some_variable = 2.45;     // this will cause an error

// do this instead (note the `var` keyword)
mango = { id: 11, name: "Mango", price: some_var_defined_in_the_outer_scope };
item_12_name = "Nectarine";

items.transaction(function(tx) {
    tx.insert([
        mango,
        { id: 12, name: item_12_name, price: 6.5 },
        { id: 13, name: "Orange", price: var_defined_somewhere_else }
    ]);

    tx.commit();
});

// BUT, if you're using the transaction in a function, you can use the `var` keyword to define the variables
function some_function(model) {
    var some_variable = 2.45;

    model.transaction(function(tx) {
        tx.insert([
            { id: 11, name: "Mango", price: some_variable },
            { id: 12, name: "Nectarine", price: 6.5 },
            { id: 13, name: "Orange", price: 5.5 }
        ]);

        tx.commit();
    });
}

In this example, we’re using closures to pass variables from the outside to the inside of the transaction. This allows us to define the data we want to insert in a more dynamic way.

---

References

Transaction.insert()

See the Model.insert() section for the details.

Transaction.get()

See the Model.get() section for the details.

Transaction.get_by_index()

See the Model.get_by_index() section for the details.

Transaction.get_by_primary()

See the Model.get_by_primary() section for the details.

Transaction.get_by_value()

See the Model.get_by_value() section for the details.

Transaction.get_by_function()

See the Model.get_by_function() section for the details.

Transaction.remove()

See the Model.remove() section for the details.

Transaction.remove_by_index()

See the Model.remove_by_index() section for the details.

Transaction.remove_by_primary()

See the Model.remove_by_primary() section for the details.

Transaction.remove_by_value()

See the Model.remove_by_value() section for the details.

Transaction.remove_by_function()

See the Model.remove_by_function() section for the details.

Transaction.update()

See the Model.update() section for the details.

Transaction.update_by_index()

See the Model.update_by_index() section for the details.

Transaction.update_by_primary()

See the Model.update_by_primary() section for the details.

Transaction.update_by_value()

See the Model.update_by_value() section for the details.

Transaction.update_by_function()

See the Model.update_by_function() section for the details.

Transaction.upsert()

See the Model.upsert() section for the details.