How to use [data.*]

This page is part of the magic.data.common documentation.

All of the [data.xxx] slots are actually just polymorphistically evaluating your specialised adapter’s slots, such as for instance [data.connect], that will invoke [mysql.connect] if this is your default database. However, all of these slots can also be given an explicit [database-type] argument, being for instance “mssql”, allowing you to choose a database type explicitly as you invoke it.

If you don’t provide an explicit [database-type] argument to these slots, the default database type will be retrieved from your “appsettings.json” file, from the magic:databases:default value, and substitute the “data” parts with the value found from your configuration setting, to invoke your specialised implementation. For instance, if you’re using MySQL as your default database type, and you invoke for instance [data.connect], this will transform into an invocation to [mysql.connect], allowing you to use generic database slot invocations, ignoring your database type, creating the correct SQL dialect for you automagically.

The following CRUD slots are documented in their own sections below.

  • [data.create] - Inserts a new row into the current open database connection
  • [data.update] - Updates rows in the current open database connection, use [where] to constrain which rows are affected
  • [data.scan] - Scans rows from the current open database connection

Database transactions

Although you should be careful with database transactions, sometimes you really need them. For those cases you can use the following 3 slots to create, rollback, and/or commit transactions towards your underlying database.

  • [data.transaction.create] - Creates a new database transaction
  • [data.transaction.commit] - Commits an existing open transaction
  • [data.transaction.rollback] - Roll back an existing open transaction

Notice - The default logic for a database transaction, is that unless it’s explicitly committed before leaving scope, it will roll back by default. Below is an example of a transaction that will rollback, since it’s not explicitly committed before leaving scope.

data.connect:sakila
   data.transaction.create
      data.execute:delete from film_actor

      /*
       * If you uncomment the line below the
       * transaction will be committed, resulting
       * in that everything from your film_actor
       * table will be deleted.
       */
      //data.transaction.commit

data.connect:sakila

   /*
    * Notice, this still returns 5462 items, since
    * transaction was implicitly rolled back above.
    */
   data.scalar:select count(*) from film_actor

A transaction typically follows your connection, implying to count items after the transaction has been rolled back, we’ll need a new connection, as the above example illustrates.

all of magic.data.common Aggregate results →