Welcome to your comprehensive guide to Nut, a powerful and user-friendly Object-Relational Mapping (ORM) framework designed for your Qt5 applications. Whether you’re managing databases or handling complex data structures, Nut makes it effortless. In the following sections, we’ll walk through setting up your first database and tackling common issues you may encounter along the way.

Features of Nut

• Easy to use
• Support for PostgreSQL, MySQL, SQLite, and Microsoft SQL Server
• Automatically create and update databases
• IDE autocomplete support—no hard-coding needed
• Automatic detection of table joins
• Support for both common C++ and Qt-specific types (Full list)
• Bulk insertion capabilities

Quick Start

Let’s dive into the practical side. Here’s a step-by-step process to create a table in Nut.

Create Your First Table

We will create a simple table called SampleTable. In your project, create two files: sampletable.h and sampletable.cpp.

sampletable.h

#ifndef SAMPLETABLE_H
#define SAMPLETABLE_H

#include 

class SampleTable : public Nut::Table
{
    Q_OBJECT
    Q_PROPERTY(int id READ id WRITE setId NOTIFY idChanged)
    Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)

    int m_id;
    QString m_name;

    BEGIN OF NUT MACROS
    NUT_PRIMARY_KEY(id)
    NUT_FIELD(int, id)
    NUT_FIELD(QString, name)
    END OF NUT MACROS

public:
    explicit SampleTable(QObject *parent = nullptr);
    int id() const;
    QString name() const;

public Q_SLOTS:
    void setId(int id);
    void setName(QString name);

Q_SIGNALS:
    void idChanged(int id);
    void nameChanged(QString name);
};

#endif // SAMPLETABLE_H

sampletable.cpp

#include "sampletable.h"

SampleTable::SampleTable(QObject *parent) : Nut::Table(parent)
{
    init();
}

int SampleTable::id() const
{
    return m_id;
}

QString SampleTable::name() const
{
    return m_name;
}

void SampleTable::setId(int id)
{
    if (m_id == id)
        return;
    m_id = id;
    Q_EMIT idChanged(m_id);
}

void SampleTable::setName(QString name)
{
    if (m_name == name)
        return;
    m_name = name;
    Q_EMIT nameChanged(m_name);
}

Creating the Database

Next, let’s establish a database. Create another file named sampledatabase.h.

sampledatabase.h

#ifndef SAMPLEDATABASE_H
#define SAMPLEDATABASE_H

#include 

class SampleTable;

class SampleDataBase : public NUT_WRAP_NAMESPACE(Database)
{
    Q_OBJECT
    NUT_DB_VERSION(1)
    NUT_DECLARE_TABLE(SampleTable, items)

public:
    SampleDataBase();
};

#endif // SAMPLEDATABASE_H

Implement Your Sample Database

#include "sampledatabase.h"
#include "sampletable.h"

SampleDataBase::SampleDataBase() : Nut::Database(), m_items(new Nut::TableSetSampleTable(this))
{
}

Using Queries

Here’s where the real magic happens. With Nut, querying your database is straightforward. Here’s an example of how you can select, insert, or delete data.

auto list = db.items()->query().toList(); // Add rows from database

// Select all the people named David
auto onlyDavids = db.items()->query().where(SampleTable::nameField() == "David").toList();
onlyDavids.at(0)->setName("John"); // Change his name to John
db.saveChanges(); // Save changes to the database

// Remove all Johns from the database
db.items()->query().where(SampleTable::nameField() == "John").remove();

// Select rows with IDs: 1, 4, 5, 6
db.items()->query().where(SampleTable::idField().in(1, 4, 5, 6));

Using an Analogy

Think of Nut as a highly skilled chef in a large restaurant (your application). The chef is familiar with multiple cuisines (the various database types like PostgreSQL, MySQL, etc.) and can prepare and modify dishes (data structures) with ease. The chef uses special knives (queries) that allow for quick preparations—chopping, mixing, or even creating entire new dishes from scratch without needing to hard-code recipes each time. Just like a creative chef, Nut offers you the freedom to adapt and modify data seamlessly.

Troubleshooting

Common issues could arise while working with Nut. Below are some troubleshooting tips:

• **Database not opening?** Make sure your database path is correct and that you have the necessary permissions.
• **Errors when creating tables or inserting data?** Check to ensure that the data types defined in your table match your inputs. Consistency is key!
• **Want to improve documentation?** If you can help us enhance the Nut docs, feel free to fork our repository!

For more insights, updates, or to collaborate on AI development projects, stay connected with **[fxis.ai](https://fxis.ai)**.

Final Thoughts

At **[fxis.ai](https://fxis.ai)**, we believe that such advancements are crucial for the future of AI as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.