TinyORM/docs/tinyorm.md

TinyORM: Getting Started

• Introduction
• TinyORM Model Conventions
  • Table Names
  • Primary Keys
  • Timestamps
  • Database Connections
  • Default Attribute Values
• Retrieving Models
  • Containers
• Retrieving Single Models
  • Retrieving Or Creating Models
• Inserting & Updating Models
  • Inserts
  • Updates
  • Mass Assignment
• Deleting Models
  • Truncate Table
• Comparing Models

Introduction

TinyORM is an object-relational mapper (ORM) that makes it enjoyable to interact with your database. When using TinyORM, each database table has a corresponding "Model" that is used to interact with that table. In addition to retrieving records from the database table, TinyORM models allow you to insert, update, and delete records from the table as well.

{tip} Before getting started, be sure to configure a database connection in your application. For more information on configuring your database, check out the database configuration documentation.

TinyORM Model Conventions

Let's examine a basic model class and discuss some of TinyORM's key conventions:

#ifndef FLIGHT_H
#define FLIGHT_H

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;

    using Model::Model;
};

#endif // FLIGHT_H

Table Names

After glancing at the example above, you may have noticed that we did not tell TinyORM which database table corresponds to our Flight model. By convention, the "snake case", plural name of the class will be used as the table name unless another name is explicitly specified. So, in this case, TinyOrm will assume the Flight model stores records in the flights table, while an AirTrafficOperator model would store records in an air_traffic_operators table.

If your model's corresponding database table does not fit this convention, you may manually specify the model's table name by defining the private u_table data member on the model:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! The table associated with the model. */
    QString u_table {"torrents"};
};

Primary Keys

TinyORM will also assume that each model's corresponding database table has a primary key column named id. If necessary, you may define a private u_primaryKey data member on your model to specify a different column that serves as your model's primary key:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! The primary key associated with the table. */
    QString u_primaryKey {"id"};
};

In addition, TinyORM assumes that the primary key is an incrementing integer value. If you wish to use a non-incrementing or a non-numeric primary key you must define a private u_incrementing data member on your model that is set to false:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! Indicates if the model's ID is auto-incrementing. */
    bool u_incrementing = false;
};

{note} Non-numeric primary keys are not currently implemented, u_incrementing code logic is fully implemented, but it is only one part to make it fully work.

"Composite" Primary Keys

TinyOrm requires each model to have at least one uniquely identifying "ID" that can serve as its primary key. "Composite" primary keys are not supported by TinyOrm models. However, you are free to add additional multi-column unique indexes to your database tables, in addition to the table's uniquely identifying primary key.

Timestamps

By default, TinyOrm expects created_at and updated_at columns to exist on your model's corresponding database table. TinyOrm will automatically set these column's values when models are created or updated. If you do not want these columns to be automatically managed by TinyOrm, you should define a private u_timestamps data member on your model with a value of false:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! Indicates if the model should be timestamped. */
    bool u_timestamps = false;
};

If you need to customize the format of your model's timestamps, set the private u_dateFormat data member on your model. This data member determines how date attributes are stored in the database, supported formats are described in the QDateTime documentation:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! The storage format of the model's date columns. */
    QString u_dateFormat {"yyyy-MM-dd HH:mm:ss"};
};

If you need to customize the names of the columns used to store the timestamps, you may define CREATED_AT and UPDATED_AT private static constants on your model:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! The name of the "created at" column. */
    inline static const QString CREATED_AT = QStringLiteral("created_at");
    /*! The name of the "updated at" column. */
    inline static const QString UPDATED_AT = QStringLiteral("updated_at");
};

{tip} You can make them non-inline and initialize them in the cpp file.

Database Connections

By default, all TinyOrm models will use the default database connection that is configured for your application. If you would like to specify a different connection that should be used when interacting with a particular model, you should define a u_connection private data member on the model:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! The database connection that should be used by the model. */
    QString u_connection {"sqlite"};
};

In special cases, when you want to query the database through a different connection, you can use Model::on method, which takes the connection name as the first argument:

auto user = User::on("sqlite")->find(1);

Default Attribute Values

By default, a newly instantiated model instance will not contain any attribute values. If you would like to define the default values for some of your model's attributes, you may define an u_attributes data member on your model, it has to be static and can be const:

#include <QDateTime>

#include <orm/tiny/basemodel.hpp>

using Orm::AttributeItem;
using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;
    using Model::Model;

private:
    /*! The model's default values for attributes. */
    inline static const QVector<AttributeItem> u_attributes {
        {"delayed",  false},
        {"progress", 0},
        {"added_on", QDateTime::currentDateTime()},
    };
};

Retrieving Models

Once you have created a model and its associated database table, you are ready to start retrieving data from your database. You can think of each TinyOrm model as a powerful query builder allowing you to fluently query the database table associated with the model. The model's all method will retrieve all of the records from the model's associated database table:

#include <QDebug>

#include "models/flight.hpp"

for (const auto &flight : Flight::all())
    qDebug() << flight["name"].toString();

Building Queries

The TinyOrm all method will return all of the results in the model's table. However, since each TinyOrm model serves as a query builder, you may add additional constraints to queries and then invoke the get method to retrieve the results:

auto flights = Flight::whereEq("active", 1)
           ->orderBy("name")
           .take(10)
           .get();

{tip} Since TinyOrm models are query builders, you should review all of the methods provided by TinyORM's query builder. You may use any of these methods when writing your TinyOrm queries.

{note} All the static methods defined on the Orm::Tiny::Model<Derived, AllRelations...> class, which start building queries like where, latest, oldest, with, ... return std::unique_ptr<TinyBuilder<Model>>, TinyBuilder = Orm::Tiny::Builder and Model template argument is queried model class.

Refreshing Models

If you already have an instance of an TinyOrm model that was retrieved from the database, you can "refresh" the model using the fresh and refresh methods. The fresh method will re-retrieve the model from the database. The existing model instance will not be affected:

auto flight = Flight::whereEq("number", "FR 900")->first();

auto freshFlight = flight->fresh();

The refresh method will re-hydrate the existing model using fresh data from the database. In addition, all of its loaded relationships will be refreshed as well:

auto flight = Flight::whereEq("number", "FR 900")->first();

flight->setAttribute("number", "FR 456");

flight->refresh();

flight->getAttribute("number"); // "FR 900"

Containers

As we have seen, TinyORM methods like all and get retrieve multiple records from the database. Since these methods return a QVector<Model>, you can iterate it like any other container with the Range-based for loop, STL-Style Iterators, Java-Style Iterators or Ranges.

#include <QDebug>

#include "models/flight.hpp"

for (const auto &flight : Flight::all())
    qDebug() << flight["name"].toString();

{note} all method is defined on the Orm::Tiny::Model<Derived, AllRelations...> class and get method is defined on the Orm::Tiny::Builder, may be also referred as TinyBuilder, it extends Orm::Query::Builder alias QueryBuilder.

Retrieving Single Models

In addition to retrieving all of the records matching a given query, you may also retrieve single records using the find, first, firstWhere, or firstWhereEq methods. Instead of returning a collection of models, these methods return a single model instance:

#include "models/flight.hpp"

// Retrieve a model by its primary key...
auto flight = Flight::find(1);

// Retrieve the first model matching the query constraints...
auto flight = Flight::whereEq("active", 1)->first();

// Alternative to retrieving the first model matching the query constraints...
auto flight = Flight::firstWhere("active", "=", 1);

// Alternative firstWhere method syntax
auto flight = Flight::firstWhereEq("active", 1);

Not Found Exceptions

Sometimes you may wish to throw an exception if a model is not found. The findOrFail and firstOrFail methods will retrieve the first result of the query; however, if no result is found, an Orm::Tiny::ModelNotFoundError will be thrown:

auto flight = Flight::findOrFail(1);

auto flight = Flight::where("legs", ">", 3)->firstOrFail();

Retrieving Or Creating Models

The firstOrCreate method will attempt to locate a database record using the given column / value pairs. If the model can not be found in the database, a record will be inserted with the attributes resulting from merging the first QVector<Orm::WhereItem> argument with the optional second QVector<Orm::AttributeItem> argument:

The firstOrNew method, like firstOrCreate, will attempt to locate a record in the database matching the given attributes. However, if a model is not found, a new model instance will be returned. Note that the model returned by firstOrNew has not yet been persisted to the database. You will need to manually call the save method to persist it:

#include "models/flight.hpp"

// Retrieve flight by name or create it if it doesn't exist...
auto flight = Flight::firstOrCreate({
    {"name", "London to Paris"}
});

// Retrieve flight by name or create it with the name, delayed, and arrival_time attributes...
auto flight = Flight::firstOrCreate(
    {{"name", "London to Paris"}},
    {{"delayed", 1}, {"arrival_time", "11:30"}}
);

// Retrieve flight by name or instantiate a new Flight instance...
auto flight = Flight::firstOrNew({
    {"name", "London to Paris"}
});

// Retrieve flight by name or instantiate with the name, delayed, and arrival_time attributes...
auto flight = Flight::firstOrNew(
    {{"name", "Tokyo to Sydney"}},
    {{"delayed", 1}, {"arrival_time", "11:30"}}
);

Inserting & Updating Models

Inserts

Of course, when using TinyOrm, we don't only need to retrieve models from the database. We also need to insert new records. Thankfully, TinyOrm makes it simple. To insert a new record into the database, you should instantiate a new model instance and set attributes on the model. Then, call the save method on the model instance:

#include "models/flight.hpp"

// Store a new flight in the database
Flight flight;
flight.setAttribute("name", "Slovakia to Czech");
flight.save();

In this example, we assign the name attribute of the Flight model instance. When we call the save method, a record will be inserted into the database. The model's created_at and updated_at timestamps will automatically be set when the save method is called, so there is no need to set them manually.

Alternatively, you may use the create method to "save" a new model using a single c++ statement. The inserted model instance will be returned to you by the create method:

#include "models/flight.hpp"

auto flight = Flight::create({
    {"name", "London to Paris"},
});

However, before using the create method, you will need to specify either a u_fillable or u_guarded static data member on your model class. These static data members are required because all Eloquent models are protected against mass assignment vulnerabilities by default. To learn more about mass assignment, please consult the mass assignment documentation.

Updates

The save method may also be used to update models that already exist in the database. To update a model, you should retrieve it and set any attributes you wish to update. Then, you should call the model's save method. Again, the updated_at timestamp will automatically be updated, so there is no need to manually set its value:

#include "models/flight.hpp"

auto flight = Flight::find(1);

flight->setAttribute("name", "Paris to London");

flight->save();

Mass Updates

Updates can also be performed against models that match a given query. In this example, all flights that are active and have a destination of San Diego will be marked as delayed:

Flight::whereEq("active", 1)
      ->whereEq("destination", "San Diego")
      .update({{"delayed", 1}});

The update method expects the QVector<Orm::UpdateItem> of column and value pairs representing the columns that should be updated.

Examining Attribute Changes

TinyOrm provides the isDirty, isClean, and wasChanged methods to examine the internal state of your model and determine how its attributes have changed from when the model was originally retrieved.

The isDirty method determines if any of the model's attributes have been changed since the model was retrieved. You may pass a specific attribute name to the isDirty method to determine if a particular attribute is dirty. The isClean will determine if an attribute has remained unchanged since the model was retrieved. This method also accepts an optional attribute argument:

#include "models/user.hpp"

auto user = User::create({
    {"first_name", "Silver"},
    {"last_name", "Zachara"},
    {"title", "Developer"},
});

user.setAttribute("title", "Painter");

user.isDirty(); // true
user.isDirty("title"); // true
user.isDirty("first_name"); // false

user.isClean(); // false
user.isClean("title"); // false
user.isClean("first_name"); // true

user.save();

user.isDirty(); // false
user.isClean(); // true

The wasChanged method determines if any attributes were changed after the model was last saved into the database. If needed, you may pass an attribute name to see if a particular attribute was changed:

auto user = User::create({
    {"first_name", "Silver"},
    {"last_name", "Zachara"},
    {"title", "Developer"},
});

user.setAttribute("title", "Painter");

user.wasChanged(); // false

user.save();

user.wasChanged(); // true
user.wasChanged("title"); // true
user.wasChanged("first_name"); // false

Mass Assignment

You may use the create method to "save" a new model using a single c++ statement. The inserted model instance will be returned to you by the method:

#include "models/flight.hpp"

auto flight = Flight::create({
    {"name", "London to Paris"},
});

However, before using the create method, you will need to specify either a u_fillable or u_guarded static data member on your model class. These data members are required because all TinyORM models are protected against mass assignment vulnerabilities by default.

A mass assignment vulnerability occurs when a user passes an unexpected HTTP request field and that field changes a column in your database that you did not expect. For example, a malicious user might send an is_admin parameter through an HTTP request, which is then passed to your model's create method, allowing the user to escalate themselves to an administrator.

So, to get started, you should define which model attributes you want to make mass assignable. You may do this using the u_fillable static data member on the model. For example, let's make the name attribute of our Flight model mass assignable:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;

    using Model::Model;

    /*! The attributes that are mass assignable. */
    inline static QStringList u_fillable {
        "name",
    };
};

Once you have specified which attributes are mass assignable, you may use the create method to insert a new record in the database. The create method returns the newly created model instance:

auto flight = Flight::create({{"name", "London to Paris"}});

If you already have a model instance, you may use the fill method to populate it with the vector of attributes:

flight.fill({{"name", "Amsterdam to Frankfurt"}});

Allowing Mass Assignment

If you would like to make all of your attributes mass assignable, you may define your model's u_guarded static data member as an empty vector. If you choose to unguard your model, you should take special care to always hand-craft the vectors passed to TinyORM's fill, create, and update methods:

#include <orm/tiny/basemodel.hpp>

using Orm::Tiny::Model;

class Flight final : public Model<Flight>
{
    friend Model;

    using Model::Model;

    /*! The attributes that aren't mass assignable. */
    inline static QStringList u_guarded {};
};

Deleting Models

To delete a model, you may call the remove, or an alias deleteRow method on the model instance:

#include "models/flight.hpp"

auto flight = Flight::find(1);

flight->remove();

Deleting An Existing Model By Its Primary Key

In the example above, we are retrieving the model from the database before calling the remove method. However, if you know the primary key of the model, you may delete the model without explicitly retrieving it by calling the destroy method. In addition to accepting the single primary key, the destroy method can accept multiple primary keys:

Flight::destroy(1);

Flight::destroy({1, 2, 3});

{note} The destroy method loads models from the database and calls the remove method on each model individually, the reason for this is future compatibility with events.

Deleting Models Using Queries

Of course, you may build an Eloquent query to delete all models matching your query's criteria. In this example, we will delete all flights that are marked as inactive:

auto deletedRows = Flight::whereEq("active", 0)->remove();

Truncate Table

You may call the truncate method to delete all of the model's associated database records. The truncate operation will also reset any auto-incrementing IDs on the model's associated table:

Flight::truncate();

Comparing Models

Sometimes you may need to determine if two models are the "same". The is method may be used to quickly verify two models have the same primary key, table, and database connection:

if (post.is(anotherPost)) {
    //
}