or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

associations.mddata-types.mddatabase-connection.mderror-handling.mdhooks.mdindex.mdmodel-definition.mdquery-operators.mdquerying.mdtransactions.md
tile.json

tessl/npm-sequelize

Promise-based Node.js ORM tool for Postgres, MySQL, MariaDB, SQLite, Microsoft SQL Server, Amazon Redshift and Snowflake's Data Cloud with solid transaction support, relations, eager and lazy loading, read replication and more

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/sequelize@6.37.x

To install, run

npx @tessl/cli install tessl/npm-sequelize@6.37.0

index.mddocs/

Sequelize

Sequelize is a promise-based Node.js ORM tool for Postgres, MySQL, MariaDB, SQLite, Microsoft SQL Server, Amazon Redshift and Snowflake's Data Cloud. It features solid transaction support, relations, eager and lazy loading, read replication and more.

Package Information

  • Package Name: sequelize
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install sequelize

Core Imports

import { Sequelize, Model, DataTypes, Op } from "sequelize";

For CommonJS:

const { Sequelize, Model, DataTypes, Op } = require("sequelize");

Basic Usage

import { Sequelize, Model, DataTypes } from "sequelize";

// Initialize database connection
const sequelize = new Sequelize("postgresql://user:pass@localhost:5432/database");

// Define a model
class User extends Model {}
User.init({
  firstName: DataTypes.STRING,
  lastName: DataTypes.STRING,
  email: DataTypes.STRING
}, { sequelize, modelName: 'user' });

// Sync models and perform operations
await sequelize.sync();

// Create a user
const user = await User.create({
  firstName: "John",
  lastName: "Doe", 
  email: "john@example.com"
});

// Find users
const users = await User.findAll({
  where: {
    firstName: "John"
  }
});

Architecture

Sequelize is built around several key components:

  • Sequelize Instance: Central connection manager and configuration hub
  • Model Class: Base class for defining database models with attributes, validations, and associations
  • DataTypes: Type system for defining column types with database-specific mappings
  • Query Interface: Database-agnostic interface for schema operations and raw queries
  • Transaction System: ACID-compliant transaction management with isolation levels
  • Association System: Relationship definitions (BelongsTo, HasOne, HasMany, BelongsToMany)
  • Migration System: Schema versioning and deployment management
  • Hook System: Lifecycle event system for extending model and query behavior

Capabilities

Database Connection & Configuration

Core database connection management, configuration, and instance-level operations for managing database connections across multiple supported dialects.

class Sequelize {
  constructor(database: string, username?: string, password?: string, options?: Options);
  constructor(uri: string, options?: Options);
  
  authenticate(): Promise<void>;
  sync(options?: SyncOptions): Promise<Sequelize>;
  close(): Promise<void>;
}

interface Options {
  dialect: 'mysql' | 'postgres' | 'sqlite' | 'mariadb' | 'mssql' | 'db2' | 'snowflake' | 'oracle';
  host?: string;
  port?: number;
  logging?: boolean | ((sql: string, timing?: number) => void);
  pool?: PoolOptions;
  timezone?: string;
  dialectOptions?: any;
}

Database Connection

Model Definition & Management

Model creation, configuration, and lifecycle management including attributes, validations, scopes, and schema operations.

class Model {
  static init(attributes: ModelAttributes, options: InitOptions): typeof Model;
  static sync(options?: SyncOptions): Promise<Model>;
  static drop(options?: DropOptions): Promise<void>;
  
  save(options?: SaveOptions): Promise<this>;
  destroy(options?: InstanceDestroyOptions): Promise<void>;
  reload(options?: FindOptions): Promise<this>;
}

interface ModelAttributes {
  [name: string]: DataType | ModelAttributeColumnOptions;
}

Model Definition

Querying & CRUD Operations

Data querying, creation, updating, and deletion operations with advanced filtering, ordering, and aggregation capabilities.

class Model {
  static findAll(options?: FindOptions): Promise<Model[]>;
  static findOne(options?: FindOptions): Promise<Model | null>;
  static findByPk(identifier: Identifier, options?: Omit<FindOptions, 'where'>): Promise<Model | null>;
  static create(values?: CreationAttributes, options?: CreateOptions): Promise<Model>;
  static update(values: Partial<Attributes>, options: UpdateOptions): Promise<[number, Model[]]>;
  static destroy(options: DestroyOptions): Promise<number>;
}

interface FindOptions {
  where?: WhereOptions;
  attributes?: FindAttributeOptions;
  include?: Includeable | Includeable[];
  order?: Order;
  group?: GroupOption;
  having?: WhereOptions;
  limit?: number;
  offset?: number;
}

Querying

Associations & Relationships

Model relationship definitions and operations including one-to-one, one-to-many, and many-to-many associations with eager loading.

class Model {
  static hasOne(target: ModelCtor, options?: HasOneOptions): HasOne;
  static belongsTo(target: ModelCtor, options?: BelongsToOptions): BelongsTo;
  static hasMany(target: ModelCtor, options?: HasManyOptions): HasMany;
  static belongsToMany(target: ModelCtor, options: BelongsToManyOptions): BelongsToMany;
}

interface HasOneOptions {
  foreignKey?: string | ForeignKeyOptions;
  sourceKey?: string;
  hooks?: boolean;
  as?: string | { singular: string; plural: string; };
  scope?: AssociationScope;
}

Associations

Data Types & Validation

Comprehensive data type system with database-specific mappings and validation rules for model attributes.

interface DataTypes {
  STRING(length?: number): DataType;
  TEXT: DataType;
  INTEGER: DataType;
  BIGINT: DataType;
  FLOAT: DataType;
  DECIMAL(precision?: number, scale?: number): DataType;
  DATE: DataType;
  BOOLEAN: DataType;
  JSON: DataType;
  UUID: DataType;
  ENUM(...values: string[]): DataType;
  ARRAY(type: DataType): DataType;
}

interface ModelAttributeColumnOptions {
  type: DataType;
  allowNull?: boolean;
  defaultValue?: any;
  primaryKey?: boolean;
  unique?: boolean | string;
  validate?: ModelValidateOptions;
}

Data Types

Transactions

Database transaction management with support for multiple isolation levels, savepoints, and automatic rollback on errors.

class Transaction {
  commit(): Promise<void>;
  rollback(): Promise<void>;
  afterCommit(fn: (transaction: Transaction) => void): void;
}

interface TransactionOptions {
  isolationLevel?: Transaction.ISOLATION_LEVELS;
  type?: Transaction.TYPES;
  deferrable?: Deferrable;
  readOnly?: boolean;
}

class Sequelize {
  transaction<T>(options: TransactionOptions, autoCallback: (t: Transaction) => PromiseLike<T>): Promise<T>;
  transaction(options?: TransactionOptions): Promise<Transaction>;
}

Transactions

Query Operators & Raw SQL

Advanced query operators for complex WHERE clauses and raw SQL execution for custom database operations.

interface OpTypes {
  eq: symbol;        // =
  ne: symbol;        // !=
  gt: symbol;        // >
  gte: symbol;       // >=
  lt: symbol;        // <
  lte: symbol;       // <=
  like: symbol;      // LIKE
  in: symbol;        // IN
  between: symbol;   // BETWEEN
  and: symbol;       // AND
  or: symbol;        // OR
}

const Op: OpTypes;

class Sequelize {
  query(sql: string, options?: QueryOptions): Promise<any>;
  fn(fn: string, ...args: any[]): Fn;
  col(col: string): Col;
  literal(val: string): Literal;
  where(attr: any, comparator: any, logic?: any): Where;
}

Query Operators

Hooks & Lifecycle Events

Lifecycle event system for extending model and query behavior with customizable hooks that execute at specific points during database operations.

interface ModelHooks {
  // Validation hooks
  beforeValidate: (instance: Model, options: ValidationOptions) => Promise<void> | void;
  afterValidate: (instance: Model, options: ValidationOptions) => Promise<void> | void;
  validationFailed: (instance: Model, options: ValidationOptions, error: ValidationError) => Promise<void> | void;
  
  // CRUD hooks
  beforeCreate: (instance: Model, options: CreateOptions) => Promise<void> | void;
  afterCreate: (instance: Model, options: CreateOptions) => Promise<void> | void;
  beforeUpdate: (instance: Model, options: UpdateOptions) => Promise<void> | void;
  afterUpdate: (instance: Model, options: UpdateOptions) => Promise<void> | void;
  beforeSave: (instance: Model, options: SaveOptions) => Promise<void> | void;
  afterSave: (instance: Model, options: SaveOptions) => Promise<void> | void;
  beforeDestroy: (instance: Model, options: InstanceDestroyOptions) => Promise<void> | void;
  afterDestroy: (instance: Model, options: InstanceDestroyOptions) => Promise<void> | void;
  
  // Query hooks
  beforeFind: (options: FindOptions) => Promise<void> | void;
  afterFind: (instances: Model | Model[] | null, options: FindOptions) => Promise<void> | void;
  
  // Bulk operation hooks
  beforeBulkCreate: (instances: Model[], options: BulkCreateOptions) => Promise<void> | void;
  afterBulkCreate: (instances: Model[], options: BulkCreateOptions) => Promise<void> | void;
  beforeBulkUpdate: (options: UpdateOptions) => Promise<void> | void;
  afterBulkUpdate: (options: UpdateOptions) => Promise<void> | void;
  beforeBulkDestroy: (options: DestroyOptions) => Promise<void> | void;
  afterBulkDestroy: (options: DestroyOptions) => Promise<void> | void;
}

/**
 * Add hook to model or sequelize instance
 */
addHook(hookType: string, name: string, fn: Function): void;
addHook(hookType: string, fn: Function): void;

/**
 * Remove hook from model or sequelize instance
 */
removeHook(hookType: string, name: string): boolean;

Hooks

Error Handling

Comprehensive error hierarchy for handling database-specific errors, validation failures, and connection issues.

class BaseError extends Error {
  name: string;
  message: string;
  stack?: string;
}

class ValidationError extends BaseError {
  errors: ValidationErrorItem[];
}

class DatabaseError extends BaseError {
  sql?: string;
  parameters?: any[];
}

class ConnectionError extends BaseError {}
class TimeoutError extends BaseError {}
class UniqueConstraintError extends ValidationError {}
class ForeignKeyConstraintError extends DatabaseError {}

Error Handling

Global Types

type Identifier = number | string | Buffer;
type Logging = boolean | ((sql: string, timing?: number) => void);

interface PoolOptions {
  max?: number;
  min?: number;
  idle?: number;
  acquire?: number;
  evict?: number;
}

interface SyncOptions {
  force?: boolean;
  alter?: boolean | SyncAlterOptions;
  logging?: Logging;
  schema?: string;
  searchPath?: string;
  hooks?: boolean;
}

type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;