Skip to content

Models ​

Model template ​

js
/**
 * Article model
 */
export default (sequelize, DataTypes) => {
  const Article = sequelize.define(
    'Article',
    {
      id: {
        type: DataTypes.BIGINT,
        primaryKey: true,
        autoIncrement: true
      },
      user_id: {
        type: DataTypes.BIGINT,
        allowNull: false,
        field: 'user_id',
        comment: 'author user id'
      },
      title: {
        type: DataTypes.STRING(200),
        allowNull: false,
        comment: 'title'
      },
      content: {
        type: DataTypes.TEXT,
        comment: 'body'
      },
      status: {
        type: DataTypes.TINYINT,
        defaultValue: 1,
        comment: '1 published, 0 draft, -1 deleted'
      },
      delete_version: {
        type: DataTypes.BIGINT,
        allowNull: false,
        defaultValue: 0,
        comment: 'soft-delete marker'
      }
    },
    {
      tableName: 'myapp_article',
      timestamps: true,
      paranoid: true,
      indexes: [{ fields: ['user_id'], name: 'idx_article_user' }],
      comment: 'articles'
    }
  );

  Article.associate = models => {
    Article.belongsTo(models.User, {
      foreignKey: 'user_id',
      as: 'author',
      onDelete: 'CASCADE'
    });
  };

  return Article;
};

Conventions ​

RuleDetail
File namePascalCase, identical to the first argument of sequelize.define()
Locationsrc/models/{app_name}/
Exporta factory (sequelize, DataTypes) => Model
Relationsdeclared via Model.associate = (models) => {}
Soft deleteneeds paranoid: true plus a delete_version column
Timestampsalways timestamps: true
Table name{app_name}_{feature}

Auto-registration ​

The model loader scans src/models/{app_name}/ and registers each model as app.db.{app_name}.ModelName:

js
// during loader startup (where the app instance is available)
const article = await app.db.myapp.Article.findByPk(1);

At request time you usually only hold request; take models through getModel() (model names are globally unique):

js
import { getModel } from '../../../framework/persistence/db/index.js';

const article = await getModel('Article').findByPk(1);
const user = await getModel('User').findByPk(article.user_id);

app.db is decorated onto the Fastify instance during the loader phase. Business code (routes / services / DAOs) must use getModel('ModelName') and never rely on an app variable being in scope.

Domain split (DDD) ​

DomainDirectoryModelsQuestion it answers
Identitymodels/user/User, UserIdentity"who are you?"
Access controlmodels/iam/Role, UserRole, InlinePolicy"what may you do?"
Delegated authzmodels/oauth21/OauthClient, OauthToken, OauthApproval"what may a third party do?"
Sessionsmodels/session/UserSession, SessionToken, SessionLog"where are you signed in?"
Infrastructuremodels/notice/EmailCode, NoticeConfigsystem configuration

Sequelize queries ​

js
// basic reads
const user = await User.findByPk(1);
const users = await User.findAll({ where: { status: 1 }, limit: 20 });

// create
const user = await User.create({ username: 'alice', email: 'alice@example.com' });

// update
await user.update({ username: 'bob' });
await User.update({ status: 0 }, { where: { id: 1 } });

// delete
await User.destroy({ where: { id: 1 } });               // soft delete
await User.destroy({ where: { id: 1 }, force: true });  // hard delete

// complex queries
import { Op } from 'sequelize';
const users = await User.findAll({
  where: {
    status: 1,
    email: { [Op.like]: '%@example.com' },
    created_at: { [Op.gte]: new Date('2026-01-01') }
  },
  order: [['created_at', 'DESC']],
  limit: 10
});

// transactions
const result = await sequelize.transaction(async t => {
  const user = await User.create({ username: 'alice' }, { transaction: t });
  await UserIdentity.create({ user_id: user.id }, { transaction: t });
  return user;
});

Released under the GPL-3.0 license