---
sidebar_position: 0
sidebar_label: Getting Started
description: 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.
---

# TinyORM: Getting Started

- [Introduction](#introduction)
- [TinyORM Model Conventions](#tinyorm-model-conventions)
    - [Table Names](#table-names)
    - [Primary Keys](#primary-keys)
    - [Timestamps](#timestamps)
    - [Database Connections](#database-connections)
    - [Default Attribute Values](#default-attribute-values)
- [Retrieving Models](#retrieving-models)
    - [Containers](#containers)
    - [Advanced Subqueries](#advanced-subqueries)
- [Retrieving Single Models](#retrieving-single-models)
    - [Retrieving Or Creating Models](#retrieving-or-creating-models)
- [Inserting & Updating Models](#inserting-and-updating-models)
    - [Inserts](#inserts)
    - [Updates](#updates)
    - [Mass Assignment](#mass-assignment)
- [Deleting Models](#deleting-models)
    - [Truncate Table](#truncate-table)
- [Comparing Models](#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.

:::note
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](database/getting-started.mdx#configuration).
:::

## TinyORM Model Conventions

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

    #pragma once
    #ifndef FLIGHT_HPP
    #define FLIGHT_HPP

    #include <orm/tiny/model.hpp>

    using Orm::Tiny::Model;

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

        using Model::Model;
    };

    #endif // FLIGHT_HPP

### 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/model.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/model.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/model.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;
    };

:::caution
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/model.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/model.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/model.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 these static constants non-inline and initialize them in the cpp file.
:::

:::tip
You may also use `Orm::CREATED_AT` and `Orm::UPDATED_AT` string constants instead of `QStringLiteral("created_at")`.
:::

### 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/model.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/model.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](database/query-builder.mdx) 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](database/query-builder.mdx), 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](database/query-builder.mdx). 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 the 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](https://en.cppreference.com/w/cpp/language/range-for), [STL-Style Iterators](https://doc.qt.io/qt-5/containers.html#stl-style-iterators), [Java-Style Iterators](https://doc.qt.io/qt-5/containers.html#java-style-iterators) or [Ranges](https://www.walletfox.com/course/quickref_range_v3.php).

    #include <QDebug>

    #include "models/flight.hpp"

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

:::note
An `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`, and on the `Orm::Query::Builder` alias `QueryBuilder`.
:::

### Advanced Subqueries

#### Subquery Selects

TinyORM also offers advanced subquery support, which allows you to pull information from related tables in a single query. For example, let's imagine that we have a table of flight `destinations` and a table of `flights` to destinations. The `flights` table contains an `arrived_at` column which indicates when the flight arrived at the destination.

Using the subquery functionality available to the query builder's `select` and `addSelect` methods, we can select all of the `destinations` and the name of the flight that most recently arrived at that destination using a single query:

    #include "models/destination.hpp"
    #include "models/flight.hpp"

    return Destination::addSelect(
            Flight::select("name")
                ->whereColumnEq("destination_id", "destinations.id")
                .orderByDesc("arrived_at")
                .limit(1)
                .toBase(), "last_flight")
        ->get();

#### Subquery Ordering

In addition, the query builder's `orderBy` function supports subqueries. Continuing to use our flight example, we may use this functionality to sort all destinations based on when the last flight arrived at that destination. Again, this may be done while executing a single database query:

    return Destination::orderByDesc(
            Flight::select("arrived_at")
                ->whereColumnEq("destination_id", "destinations.id")
                .orderByDesc("arrived_at")
                .limit(1)
                .toBase())
        ->get();

## 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 vector 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 {#inserting-and-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 TinyORM models are protected against mass assignment vulnerabilities by default. To learn more about mass assignment, please consult the [mass assignment documentation](#mass-assignment).

### 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/model.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/model.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 the 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` and `isNot` methods may be used to quickly verify two models have the same primary key, table, and database connection:

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