sequelize
Version:
Multi dialect ORM for Node.JS/io.js
498 lines (461 loc) • 47.4 kB
HTML
<html>
<head>
<meta charset="utf-8">
<base data-ice="baseUrl" href="../../">
<title data-ice="title">Tutorial</title>
<link type="text/css" rel="stylesheet" href="css/style.css">
<link type="text/css" rel="stylesheet" href="css/prettify-tomorrow.css">
<script src="script/prettify/prettify.js"></script>
<script src="script/manual.js"></script>
<link data-ice="userStyle" rel="stylesheet" href="user/css/0-style.css">
</head>
<body class="layout-container manual-root" data-ice="rootContainer">
<header>
<a href="./">Home</a>
<a href="identifiers.html">Reference</a>
<a href="source.html">Source</a>
<a data-ice="repoURL" href="https://github.com/sequelize/sequelize.git" class="repo-url-github">Repository</a>
<div class="search-box">
<span>
<img src="./image/search.png">
<span class="search-input-edge"></span><input class="search-input"><span class="search-input-edge"></span>
</span>
<ul class="search-result"></ul>
</div>
</header>
<nav class="navigation" data-ice="nav"><div class="manual-toc-root">
<div data-ice="manual" data-toc-name="installation">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-installation" data-section-count="■■" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html" data-ice="link">Getting started</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html#installation" data-ice="link">Installation</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html#setting-up-a-connection" data-ice="link">Setting up a connection</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html#test-the-connection" data-ice="link">Test the connection</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html#your-first-model" data-ice="link">Your first model</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html#your-first-query" data-ice="link">Your first query</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html#application-wide-model-options" data-ice="link">Application wide model options</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/installation/getting-started.html"><a href="manual/installation/getting-started.html#promises" data-ice="link">Promises</a></li>
</ul>
</div>
<div data-ice="manual" data-toc-name="tutorial">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■■" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html" data-ice="link">Model definition</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#data-types" data-ice="link">Data types</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#range-types" data-ice="link">Range types</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#special-cases" data-ice="link">Special Cases</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#deferrable" data-ice="link">Deferrable</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#getters-setters" data-ice="link">Getters & setters</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#defining-as-part-of-a-property" data-ice="link">Defining as part of a property</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#defining-as-part-of-the-model-options" data-ice="link">Defining as part of the model options</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#helper-functions-for-use-inside-getter-and-setter-definitions" data-ice="link">Helper functions for use inside getter and setter definitions</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#validations" data-ice="link">Validations</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#validators-and-allownull-" data-ice="link">Validators and allowNull</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#model-validations" data-ice="link">Model validations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#configuration" data-ice="link">Configuration</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#import" data-ice="link">Import</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#optimistic-locking" data-ice="link">Optimistic Locking</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#database-synchronization" data-ice="link">Database synchronization</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#expansion-of-models" data-ice="link">Expansion of models</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-definition.html"><a href="manual/tutorial/models-definition.html#indexes" data-ice="link">Indexes</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■■" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html" data-ice="link">Model usage</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#data-retrieval-finders" data-ice="link">Data retrieval / Finders</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#find-search-for-one-specific-element-in-the-database" data-ice="link">find - Search for one specific element in the database</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#findorcreate-search-for-a-specific-element-or-create-it-if-not-available" data-ice="link">findOrCreate - Search for a specific element or create it if not available</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#findandcountall-search-for-multiple-elements-in-the-database-returns-both-data-and-total-count" data-ice="link">findAndCountAll - Search for multiple elements in the database, returns both data and total count</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#findall-search-for-multiple-elements-in-the-database" data-ice="link">findAll - Search for multiple elements in the database</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#complex-filtering-or-not-queries" data-ice="link">Complex filtering / OR / NOT queries</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#manipulating-the-dataset-with-limit-offset-order-and-group" data-ice="link">Manipulating the dataset with limit, offset, order and group</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#raw-queries" data-ice="link">Raw queries</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#count-count-the-occurrences-of-elements-in-the-database" data-ice="link">count - Count the occurrences of elements in the database</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#max-get-the-greatest-value-of-a-specific-attribute-within-a-specific-table" data-ice="link">max - Get the greatest value of a specific attribute within a specific table</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#min-get-the-least-value-of-a-specific-attribute-within-a-specific-table" data-ice="link">min - Get the least value of a specific attribute within a specific table</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#sum-sum-the-value-of-specific-attributes" data-ice="link">sum - Sum the value of specific attributes</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#eager-loading" data-ice="link">Eager loading</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#including-everything" data-ice="link">Including everything</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#including-soft-deleted-records" data-ice="link">Including soft deleted records</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#ordering-eager-loaded-associations" data-ice="link">Ordering Eager Loaded Associations</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/models-usage.html"><a href="manual/tutorial/models-usage.html#nested-eager-loading" data-ice="link">Nested eager loading</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html" data-ice="link">Querying</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#attributes" data-ice="link">Attributes</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#where" data-ice="link">Where</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#basics" data-ice="link">Basics</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#operators" data-ice="link">Operators</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#range-operators" data-ice="link">Range Operators</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#combinations" data-ice="link">Combinations</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#jsonb" data-ice="link">JSONB</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#nested-object" data-ice="link">Nested object</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#nested-key" data-ice="link">Nested key</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#containment" data-ice="link">Containment</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#relations-associations" data-ice="link">Relations / Associations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#pagination-limiting" data-ice="link">Pagination / Limiting</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/querying.html"><a href="manual/tutorial/querying.html#ordering" data-ice="link">Ordering</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html" data-ice="link">Instances</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#building-a-non-persistent-instance" data-ice="link">Building a non-persistent instance</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#creating-persistent-instances" data-ice="link">Creating persistent instances</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#updating-saving-persisting-an-instance" data-ice="link">Updating / Saving / Persisting an instance</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#destroying-deleting-persistent-instances" data-ice="link">Destroying / Deleting persistent instances</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#working-in-bulk-creating-updating-and-destroying-multiple-rows-at-once-" data-ice="link">Working in bulk (creating, updating and destroying multiple rows at once)</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#values-of-an-instance" data-ice="link">Values of an instance</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#reloading-instances" data-ice="link">Reloading instances</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#incrementing-certain-values-of-an-instance" data-ice="link">Incrementing certain values of an instance</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/instances.html"><a href="manual/tutorial/instances.html#decrementing-certain-values-of-an-instance" data-ice="link">Decrementing certain values of an instance</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■■■" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html" data-ice="link">Associations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#one-to-one-associations" data-ice="link">One-To-One associations</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#belongsto" data-ice="link">BelongsTo</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#foreign-keys" data-ice="link">Foreign keys</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#target-keys" data-ice="link">Target keys</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#hasone" data-ice="link">HasOne</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#difference-between-hasone-and-belongsto" data-ice="link">Difference between HasOne and BelongsTo</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#one-to-many-associations" data-ice="link">One-To-Many associations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#belongs-to-many-associations" data-ice="link">Belongs-To-Many associations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#scopes" data-ice="link">Scopes</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#1-m" data-ice="link">1:m</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#n-m" data-ice="link">n:m</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#naming-strategy" data-ice="link">Naming strategy</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#associating-objects" data-ice="link">Associating objects</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#check-associations" data-ice="link">Check associations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#foreign-keys" data-ice="link">Foreign Keys</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#enforcing-a-foreign-key-reference-without-constraints" data-ice="link">Enforcing a foreign key reference without constraints</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#creating-with-associations" data-ice="link">Creating with associations</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#creating-elements-of-a-belongsto-has-many-or-hasone-association" data-ice="link">Creating elements of a "BelongsTo", "Has Many" or "HasOne" association</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#creating-elements-of-a-belongsto-association-with-an-alias" data-ice="link">Creating elements of a "BelongsTo" association with an alias</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/associations.html"><a href="manual/tutorial/associations.html#creating-elements-of-a-hasmany-or-belongstomany-association" data-ice="link">Creating elements of a "HasMany" or "BelongsToMany" association</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html" data-ice="link">Transactions</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#managed-transaction-auto-callback-" data-ice="link">Managed transaction (auto-callback)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#throw-errors-to-rollback" data-ice="link">Throw errors to rollback</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#automatically-pass-transactions-to-all-queries" data-ice="link">Automatically pass transactions to all queries</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#concurrent-partial-transactions" data-ice="link">Concurrent/Partial transactions</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#without-cls-enabled" data-ice="link">Without CLS enabled</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#isolation-levels" data-ice="link">Isolation levels</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#unmanaged-transaction-then-callback-" data-ice="link">Unmanaged transaction (then-callback)</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#options" data-ice="link">Options</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/transactions.html"><a href="manual/tutorial/transactions.html#usage-with-other-sequelize-methods" data-ice="link">Usage with other sequelize methods</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■" data-link="manual/tutorial/scopes.html"><a href="manual/tutorial/scopes.html" data-ice="link">Scopes</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/scopes.html"><a href="manual/tutorial/scopes.html#definition" data-ice="link">Definition</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/scopes.html"><a href="manual/tutorial/scopes.html#usage" data-ice="link">Usage</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/scopes.html"><a href="manual/tutorial/scopes.html#merging" data-ice="link">Merging</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/scopes.html"><a href="manual/tutorial/scopes.html#associations" data-ice="link">Associations</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html" data-ice="link">Hooks</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#order-of-operations" data-ice="link">Order of Operations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#declaring-hooks" data-ice="link">Declaring Hooks</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#removing-hooks" data-ice="link">Removing hooks</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#global-universal-hooks" data-ice="link">Global / universal hooks</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#sequelize-options-define-default-hook-" data-ice="link">Sequelize.options.define (default hook)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#sequelize-addhook-permanent-hook-" data-ice="link">Sequelize.addHook (permanent hook)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#instance-hooks" data-ice="link">Instance hooks</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#model-hooks" data-ice="link">Model hooks</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#associations" data-ice="link">Associations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#a-note-about-transactions" data-ice="link">A Note About Transactions</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/hooks.html"><a href="manual/tutorial/hooks.html#internal-transactions" data-ice="link">Internal Transactions</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■" data-link="manual/tutorial/raw-queries.html"><a href="manual/tutorial/raw-queries.html" data-ice="link">Raw queries</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/raw-queries.html"><a href="manual/tutorial/raw-queries.html#replacements" data-ice="link">Replacements</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/raw-queries.html"><a href="manual/tutorial/raw-queries.html#bind-parameter" data-ice="link">Bind Parameter</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-tutorial" data-section-count="■■■■" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html" data-ice="link">Migrations</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#the-cli" data-ice="link">The CLI</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#skeleton" data-ice="link">Skeleton</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#functions" data-ice="link">Functions</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#createtable-tablename-attributes-options-" data-ice="link">createTable(tableName, attributes, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#droptable-tablename-options-" data-ice="link">dropTable(tableName, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#dropalltables-options-" data-ice="link">dropAllTables(options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#renametable-before-after-options-" data-ice="link">renameTable(before, after, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#showalltables-options-" data-ice="link">showAllTables(options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#describetable-tablename-options-" data-ice="link">describeTable(tableName, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#addcolumn-tablenameoroptions-attributename-datatypeoroptions-options-" data-ice="link">addColumn(tableNameOrOptions, attributeName, dataTypeOrOptions, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#removecolumn-tablenameoroptions-attributename-options-" data-ice="link">removeColumn(tableNameOrOptions, attributeName, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#changecolumn-tablename-attributename-datatypeoroptions-options-" data-ice="link">changeColumn(tableName, attributeName, dataTypeOrOptions, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#renamecolumn-tablename-attrnamebefore-attrnameafter-options-" data-ice="link">renameColumn(tableName, attrNameBefore, attrNameAfter, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#addindex-tablename-attributes-options-" data-ice="link">addIndex(tableName, attributes, options)</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#removeindex-tablename-indexnameorattributes-options-" data-ice="link">removeIndex(tableName, indexNameOrAttributes, options)</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/tutorial/migrations.html"><a href="manual/tutorial/migrations.html#programmatic-use" data-ice="link">Programmatic use</a></li>
</ul>
</div>
<div data-ice="manual" data-toc-name="advanced">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-advanced" data-section-count="■■" data-link="manual/advanced/legacy.html"><a href="manual/advanced/legacy.html" data-ice="link">Working with legacy tables</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/advanced/legacy.html"><a href="manual/advanced/legacy.html#tables" data-ice="link">Tables</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/advanced/legacy.html"><a href="manual/advanced/legacy.html#fields" data-ice="link">Fields</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/advanced/legacy.html"><a href="manual/advanced/legacy.html#primary-keys" data-ice="link">Primary keys</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/advanced/legacy.html"><a href="manual/advanced/legacy.html#foreign-keys" data-ice="link">Foreign keys</a></li>
</ul>
</div>
<div data-ice="manual" data-toc-name="reference">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-reference" data-section-count="■■■■■" data-link="identifiers.html"><a href="identifiers.html" data-ice="link">Reference</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="identifiers.html"><a href="identifiers.html#class" data-ice="link">Class</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="identifiers.html"><a href="identifiers.html#variable" data-ice="link">Variable</a></li>
</ul>
</div>
<div data-ice="manual" data-toc-name="faq">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-faq" data-section-count="■" data-link="manual/faq/whos-using.html"><a href="manual/faq/whos-using.html" data-ice="link">Who's using sequelize?</a></li>
<li data-ice="manualNav" class="indent-h1 manual-color manual-color-faq" data-section-count="■" data-link="manual/faq/imprint.html"><a href="manual/faq/imprint.html" data-ice="link">Imprint</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/faq/imprint.html"><a href="manual/faq/imprint.html#author-s-" data-ice="link">AUTHOR(S)</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/faq/imprint.html"><a href="manual/faq/imprint.html#inhaltliche-verantwortung" data-ice="link">INHALTLICHE VERANTWORTUNG</a></li>
</ul>
</div>
</div>
</nav>
<div class="content" data-ice="content"><div class="github-markdown">
<div class="manual-breadcrumb-list">
<a href="./manual/./index.html">Manual</a>
<span>»</span>
<span data-ice="title">Tutorial</span>
</div>
<div data-ice="content"><h1 id="hooks">Hooks</h1>
<p>Hooks (also known as callbacks or lifecycle events), are functions which are called before and after calls in sequelize are executed. For example, if you want to always set a value on a model before saving it, you can add a <code>beforeUpdate</code> hook.</p>
<p>For a full list of hooks, see <a href="/api/hooks">Hooks API</a>.</p>
<h2 id="order-of-operations">Order of Operations</h2>
<pre><code><code class="source-code prettyprint">(1)
beforeBulkCreate(instances, options, fn)
beforeBulkDestroy(options, fn)
beforeBulkUpdate(options, fn)
(2)
beforeValidate(instance, options, fn)
(-)
validate
(3)
afterValidate(instance, options, fn)
- or -
validationFailed(instance, options, error, fn)
(4)
beforeCreate(instance, options, fn)
beforeDestroy(instance, options, fn)
beforeUpdate(instance, options, fn)
beforeSave(instance, options, fn)
beforeUpsert(values, options, fn)
(-)
create
destroy
update
(5)
afterCreate(instance, options, fn)
afterDestroy(instance, options, fn)
afterUpdate(instance, options, fn)
afterSave(instance, options, fn)
afterUpsert(created, options, fn)
(6)
afterBulkCreate(instances, options, fn)
afterBulkDestroy(options, fn)
afterBulkUpdate(options, fn)</code>
</code></pre><h2 id="declaring-hooks">Declaring Hooks</h2>
<p>Arguments to hooks are passed by reference. This means, that you can change the values, and this will be reflected in the insert / update statement. A hook may contain async actions - in this case the hook function should return a promise.</p>
<p>There are currently three ways to programmatically add hooks:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">// Method 1 via the .define() method
var User = sequelize.define('user', {
username: DataTypes.STRING,
mood: {
type: DataTypes.ENUM,
values: ['happy', 'sad', 'neutral']
}
}, {
hooks: {
beforeValidate: function(user, options) {
user.mood = 'happy'
},
afterValidate: function(user, options) {
user.username = 'Toni'
}
}
})
// Method 2 via the .hook() method
User.hook('beforeValidate', function(user, options) {
user.mood = 'happy'
})
User.hook('afterValidate', function(user, options) {
return sequelize.Promise.reject("I'm afraid I can't let you do that!")
})
// Method 3 via the direct method
User.beforeCreate(function(user, options) {
return hashPassword(user.password).then(function (hashedPw) {
user.password = hashedPw;
});
})
User.afterValidate('myHookAfter', function(user, options, fn) {
user.username = 'Toni'
})</code>
</code></pre>
<h2 id="removing-hooks">Removing hooks</h2>
<p>Only a hook with name param can be removed.</p>
<pre><code class="lang-js"><code class="source-code prettyprint">var Book = sequelize.define('book', {
title: DataTypes.STRING
})
Book.addHook('afterCreate', 'notifyUsers', function(book, options) {
// ...
})
Book.removeHook('afterCreate', 'notifyUsers')</code>
</code></pre>
<h2 id="global-universal-hooks">Global / universal hooks</h2>
<p>Global hooks are hooks which are run for all models. They can define behaviours that you want for all your models, and are especially useful for plugins. They can be defined in two ways, which have slightly different semantics:</p>
<h3 id="sequelize-options-define-default-hook-">Sequelize.options.define (default hook)</h3>
<pre><code class="lang-js"><code class="source-code prettyprint">var sequelize = new Sequelize(..., {
define: {
hooks: {
beforeCreate: function () {
// Do stuff
}
}
}
});</code>
</code></pre>
<p>This adds a default hook to all models, which is run if the model does not define its own <code>beforeCreate</code> hook:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">var User = sequelize.define('user');
var Project = sequelize.define('project', {}, {
hooks: {
beforeCreate: function () {
// Do other stuff
}
}
});
User.create() // Runs the global hook
Project.create() // Runs its own hook (because the global hook is overwritten)</code>
</code></pre>
<h3 id="sequelize-addhook-permanent-hook-">Sequelize.addHook (permanent hook)</h3>
<pre><code class="lang-js"><code class="source-code prettyprint">sequelize.addHook('beforeCreate', function () {
// Do stuff
});</code>
</code></pre>
<p>This hooks is always run before create, regardless of whether the model specifies its own <code>beforeCreate</code> hook:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">var User = sequelize.define('user');
var Project = sequelize.define('project', {}, {
hooks: {
beforeCreate: function () {
// Do other stuff
}
}
});
User.create() // Runs the global hook
Project.create() // Runs its own hook, followed by the global hook</code>
</code></pre>
<p>Local hooks are always run before global hooks.</p>
<h3 id="instance-hooks">Instance hooks</h3>
<p>The following hooks will emit whenever you're editing a single object</p>
<pre><code><code class="source-code prettyprint">beforeValidate
afterValidate or validationFailed
beforeCreate / beforeUpdate / beforeDestroy
afterCreate / afterUpdate / afterDestroy</code>
</code></pre><pre><code class="lang-js"><code class="source-code prettyprint">// ...define ...
User.beforeCreate(function(user) {
if (user.accessLevel > 10 && user.username !== "Boss") {
throw new Error("You can't grant this user an access level above 10!")
}
})</code>
</code></pre>
<p>This example will return an error:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">User.create({username: 'Not a Boss', accessLevel: 20}).catch(function(err) {
console.log(err) // You can't grant this user an access level above 10!
})</code>
</code></pre>
<p>The following example would return successful:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">User.create({username: 'Boss', accessLevel: 20}).then(function(user) {
console.log(user) // user object with username as Boss and accessLevel of 20
})</code>
</code></pre>
<h3 id="model-hooks">Model hooks</h3>
<p>Sometimes you'll be editing more than one record at a time by utilizing the <code>bulkCreate, update, destroy</code> methods on the model. The following will emit whenever you're using one of those methods.</p>
<pre><code><code class="source-code prettyprint">beforeBulkCreate / beforeBulkUpdate / beforeBulkDestroy
afterBulkCreate / afterBulkUpdate / afterBulkDestroy</code>
</code></pre><p>If you want to emit hooks for each individual record, along with the bulk hooks you can pass <code>individualHooks: true</code> to the call.</p>
<pre><code class="lang-js"><code class="source-code prettyprint">Model.destroy({ where: {accessLevel: 0}, individualHooks: true})
// Will select all records that are about to be deleted and emit before- + after- Destroy on each instance
Model.update({username: 'Toni'}, { where: {accessLevel: 0}, individualHooks: true})
// Will select all records that are about to be updated and emit before- + after- Update on each instance</code>
</code></pre>
<p>Some model hooks have two or three parameters sent to each hook depending on it's type.</p>
<pre><code class="lang-js"><code class="source-code prettyprint">Model.beforeBulkCreate(function(records, fields) {
// records = the first argument sent to .bulkCreate
// fields = the second argument sent to .bulkCreate
})
Model.bulkCreate([
{username: 'Toni'}, // part of records argument
{username: 'Tobi'} // part of records argument
], ['username'] /* part of fields argument */)
Model.beforeBulkUpdate(function(attributes, where) {
// attributes = first argument sent to Model.update
// where = second argument sent to Model.update
})
Model.update({gender: 'Male'} /*attributes argument*/, { where: {username: 'Tom'}} /*where argument*/)
Model.beforeBulkDestroy(function(whereClause) {
// whereClause = first argument sent to Model.destroy
})
Model.destroy({ where: {username: 'Tom'}} /*whereClause argument*/)</code>
</code></pre>
<p>If you use <code>Model.bulkCreate(...)</code> with the <code>updatesOnDuplicate</code> option, changes made in the hook to fields that aren't given in the <code>updatesOnDuplicate</code> array will not be persisted to the database. However it is possible to change the updatesOnDuplicate option inside the hook if this is what you want.</p>
<pre><code><code class="source-code prettyprint">// Bulk updating existing users with updatesOnDuplicate option
Users.bulkCreate([{ id: 1, isMemeber: true},
{ id: 2, isMember: false}],
{ updatesOnDuplicate: ['isMember']})
User.beforeBulkCreate(function (users, options) {
users.forEach(function (user) {
if (user.isMember) {
user.memberSince = new Date()
}
})
// Add memberSince to updatesOnDuplicate otherwise the memberSince date wont be
// saved to the database
options.updatesOnDuplicate.push('memberSince')
})</code>
</code></pre><h2 id="associations">Associations</h2>
<p>For the most part hooks will work the same for instances when being associated except a few things</p>
<ol>
<li>When using add/set functions the beforeUpdate/afterUpdate hooks will run.</li>
<li>The only way to call beforeDestroy/afterDestroy hooks are on associations with <code>onDelete: 'cascade'</code> and the option <code>hooks: true</code>. For instance:</li>
</ol>
<pre><code class="lang-js"><code class="source-code prettyprint">var Projects = sequelize.define('projects', {
title: DataTypes.STRING
})
var Tasks = sequelize.define('tasks', {
title: DataTypes.STRING
})
Projects.hasMany(Tasks, { onDelete: 'cascade', hooks: true })
Tasks.belongsTo(Projects)</code>
</code></pre>
<p>This code will run beforeDestroy/afterDestroy on the Tasks table. Sequelize, by default, will try to optimize your queries as much as possible. When calling cascade on delete, Sequelize will simply execute a</p>
<pre><code class="lang-sql"><code class="source-code prettyprint">DELETE FROM `table` WHERE associatedIdentifier = associatedIdentifier.primaryKey</code>
</code></pre>
<p>However, adding <code>hooks: true</code> explicitly tells Sequelize that optimization is not of your concern and will perform a <code>SELECT</code> on the associated objects and destroy each instance one by one in order to be able to call the hooks with the right parameters.</p>
<p>If your association is of type <code>n:m</code>, you may be interested in firing hooks on the through model when using the <code>remove</code> call. Internally, sequelize is using <code>Model.destroy</code> resulting in calling the <code>bulkDestroy</code> instead of the <code>before/afterDestroy</code> hooks on each through instance.</p>
<p>This can be simply solved by passing <code>{individualHooks: true}</code> to the <code>remove</code> call, resulting on each hook to be called on each removed through instance object.</p>
<h2 id="a-note-about-transactions">A Note About Transactions</h2>
<p>Note that many model operations in Sequelize allow you to specify a transaction in the options parameter of the method. If a transaction <em>is</em> specified in the original call, it will be present in the options parameter passed to the hook function. For example, consider the following snippet:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">// Here we use the promise-style of async hooks rather than
// the callback.
User.hook('afterCreate', function(user, options) {
// 'transaction' will be available in options.transaction
// This operation will be part of the same transaction as the
// original User.create call.
return User.update({
mood: 'sad'
}, {
where: {
id: user.id
},
transaction: options.transaction
});
});
sequelize.transaction(function(t) {
User.create({
username: 'someguy',
mood: 'happy',
transaction: t
});
});</code>
</code></pre>
<p>If we had not included the transaction option in our call to <code>User.update</code> in the preceding code, no change would have occurred, since our newly created user does not exist in the database until the pending transaction has been committed.</p>
<h3 id="internal-transactions">Internal Transactions</h3>
<p>It is very important to recognize that sequelize may make use of transactions internally for certain operations such as <code>Model.findOrCreate</code>. If your hook functions execute read or write operations that rely on the object's presence in the database, or modify the object's stored values like the example in the preceding section, you should always specify <code>{ transaction: options.transaction }</code>.</p>
<p>If the hook has been called in the process of a transacted operation, this makes sure that your dependent read/write is a part of that same transaction. If the hook is not transacted, you have simply specified <code>{ transaction: null }</code> and can expect the default behaviour.</p>
</div>
</div>
</div>
<footer class="footer">
Generated by <a href="https://esdoc.org">ESDoc<span data-ice="esdocVersion">(0.5.2)</span><img src="./image/esdoc-logo-mini-black.png"></a>
</footer>
<script src="script/search_index.js"></script>
<script src="script/search.js"></script>
<script src="script/pretty-print.js"></script>
<script src="script/inherited-summary.js"></script>
<script src="script/test-summary.js"></script>
<script src="script/inner-link.js"></script>
<script src="script/patch-for-local.js"></script>
</body>
</html>