sails-hook-orm
v4.0.3
Published
The ORM hook from Sails core.
Downloads
79,045
Readme
sails-hook-orm
Implements support for Waterline ORM in Sails.
This is a core hook in the Sails.js framework. You can override or disable it using your sailsrc file or environment variables. See Concepts > Configuration for more information.
Dependencies
In order for this hook to load, the following other hooks must have already finished loading:
- moduleloader
- userconfig
Dependents
If this hook is disabled, in order for Sails to load, the following other core hooks must also be disabled:
- blueprints
- pubsub
Purpose
This hook's responsibilities are:
Load adapters
When Sails loads, this hook calls out to sails.modules.loadAdapters()
(exposed by the moduleloader
), loading any custom adapters defined within the app. It also loads adapters which are installed as dependencies of the app itself (i.e. in its node_modules/
folder). These adapters are used when instantiating Waterline.
Load and hydrate models, then expose them as sails.models.*
When Sails loads, this hook calls out to sails.modules.loadModels()
(exposed by the moduleloader
), loading model files from the app's models folder.
Prompt about auto-migration
Since instantiating Waterline currently has the effect of auto-migrating existing data (dependending on the migrate
configuration), the orm hook shows a prompt before instantiating Waterline if no migrate
setting is explicitly configured.
Instantiate Waterline
As mentioned above, since all configuration, models, and adapters are loaded, this hook can safely instantiate Waterline.
Expose hydrated models as sails.models
It then passes them to Waterline to turn them into Model instances with all the expected methods like .create()
, and then exposes them as sails.models
. Conventionally this models folder is api/models/
, but it can be configured in sails.config.paths
.
- Note that the set of hydrated models in the
sails.models
also includes Waterline models which were implicitly created as junctors (i.e. for anycollection
associations whosevia
does not point at amodel
association). - Also note that models are exposed on
sails.models
are keyed by their identities. That is, if you have a model fileWolf.js
, it will be available assails.models.wolf
.
Expose global variable for each model
If enabled (sails.config.globals.models
set to true), use the inferred globalId
of each model to expose it as a global variable.
Implicit Defaults
This hook sets the following implicit default configuration on sails.config
:
| Property | Type | Default |
|------------------------------------------------|:-------------:|-----------------|
| sails.config.globals.models
| ((boolean)) | true
|
| sails.config.models.datastore
| ((string)) | default
|
| sails.config.datastores.default.adapter
| ((ref)) | require('sails-disk')
|
i.e.
{
globals: {
adapters: true,
models: true
},
// Default model properties
models: {
// This default datastore for the app will be used for
// each model unless otherwise specified.
datastore: 'default'
},
// Connections to data sources, web services, and external APIs.
// Can be attached to models and/or accessed directly.
datastores: {
// Built-in disk persistence
// (by default, creates the file: `.tmp/localDiskDb.db`)
default: {
adapter: 'sails-disk'
}
}
}
Events
hook:orm:loaded
Emitted when this hook has been automatically loaded by Sails core, and triggered the callback in its initialize
function.
hook:orm:reload
This event is no longer emitted by this hook. This event will likely be replaced by making .reload()
a public function.
This event is experimental and is likely to change in a future release.
hook:orm:reloaded
Emitted when a reload is complete. This event will likely be replaced by expecting a callback in .reload()
.
This event is experimental and is likely to change in a future release.
Methods
sails.hooks.orm.reload()
Reload the ORM hook, reloading models and adapters from disk, and reinstantiating Waterline.
- Note that this does not automatically reload dependent hooks (such as blueprints).
- Also note that there is currently no callback.
sails.hooks.orm.reload();
API: Private
- Please do not use this method in userland (i.e. in your app or even in a custom hook or other type of Sails plugin).
- Because it is a private API of a core hook, if you use this method in your code it may stop working or change without warning, at any time.
- If you would like to see a version of this method made public and its API stabilized, please open a proposal.
sails.hooks.orm.teardown()
Call the teardown()
method for adapters which have one, and which were previously loaded by the ORM hook.
sails.hooks.orm.teardown(cb);
Usage
| | Argument | Type | Details | --- | --------------------------- | ------------------- | ---------------------------------------------------------------------------------- | 1 | cb | ((function)) | Optional. Fires when the teardown process for the hook is complete.
API: Private
- Please do not use this method in userland (i.e. in your app or even in a custom hook or other type of Sails plugin).
- Because it is a private API of a core hook, if you use this method in your code it may stop working or change without warning, at any time.
- If you would like to see a version of this method made public and its API stabilized, please open a proposal.
FAQ
If you have a question about this hook that isn't covered here, please feel free to send a PR adding it to this section (even if you don't have the answer, a core maintainer will merge your PR and add an answer as soon as possible)
What is this?
This repo contains a hook, one of the building blocks Sails is made out of.
What version of Sails is this for?
This hook is a dependency of Sails core as of Sails v0.12, in Sails v1, and beyond.
Can I disable this hook?
Yes. To disable this hook, merge the following JSON into your project's .sailsrc
file:
{
"hooks": {
"orm": false
}
}
Can I override this hook to use a different ORM like Mongoose or Bookshelf instead of Waterline?
Yes. To override this hook, define your replacement hook with identity: orm
in your .sailsrc
file or your app's api/hooks/
directory.
Help
If you have further questions or are having trouble, click here.
Bugs ![NPM version](https://badge.fury.io/js/sails-hook-orm.svg)
To report a bug, click here.
Contributing
Please observe the guidelines and conventions laid out in the Sails project contribution guide when opening issues or submitting pull requests.
License
The Sails framework is free and open-source under the MIT License.