2 |
3 | # Sails MySQL Transactional ORM with replication support
4 |
5 | `sails-mysql-transaction` is a Sails ORM Adapter for MySQL with transaction and replication cluster support.
6 |
7 | This adapter essentially __wraps__ around the popular `sails-mysql` adapter and provides additional API to perform
8 | operations that ties around a database transaction. It also provides to read from a cluster of read-replicas in a
9 | load-balanced fashion.
10 |
11 | ## Installation
12 |
13 | 1. Add `sails-mysql-transactions` to your application’s `package.json`. Do not run install directly if `sails` is not
14 | already installed in your package.
15 |
16 |
17 | 2. If you already have `sails-mysql` installed, it might interfere with operations of this module. Remove it from your
18 | `package.json` and uninstall the same using `npm remove sails-mysql`.
19 |
20 | 3. This package installs successfully only when sails is already installed in the package. If the package is already
21 | installed, then simply run `npm install sails-mysql-transactions --save`, otherwise run `npm install` and it will take
22 | care of rest.
23 |
24 | ## Safe install using postinstall script
25 |
26 | If `npm install` seems erratic to install dependencies in order, you could add the following in your `package.json` as
27 | a [postinstall script of npm](https://docs.npmjs.com/misc/scripts). This would ensure that this module is installed after
28 | sails has been completely installed. Note that in this method, you would not need to add `sails-mysql-transactions` as a
29 | dependency in your package.json
30 |
31 | ```
32 | {
33 | "scripts": {
34 | "postinstall": "npm install sails-mysql-transactions"
35 | }
36 | }
37 | ```
38 |
39 | ### Installation Notes:
40 |
41 | This package overwrites the `waterline` module inside Sails with a fork of Waterline maintained by Postman. As such,
42 | if you ever re-install or update sails, ensure you re-install this adapter right after it.
43 |
44 | Do check SailsJS compatibility list before upgrading your Sails version while already using this adapter.
45 |
46 | ## Quick Start
47 |
48 | The integration test Sails App located in `tests/integration/app` directory of this repository has a fully functional
49 | installation. Simply run `npm install` within `test/integration/app` directory.
50 |
51 | ### Sails config/local.js
52 |
53 | ```js
54 | module.exports = {
55 | /* your other config stay as is */
56 |
57 | connections: {
58 | mySQLT: {
59 | adapter: 'sails-mysql-transactions',
60 | host: '{{your-db-host}}',
61 | user: '{{your-db-username}}',
62 | password: '{{your-db-password}}',
63 | database: '{{your-db-tablename}}',
64 |
65 | transactionConnectionLimit: 10,
66 | rollbackTransactionOnError: true,
67 | queryCaseSensitive: false,
68 |
69 | /* this section is needed only if replication feature is required */
70 | replication: {
71 | enabled: true,
72 | inheritMaster: true,
73 | canRetry: true,
74 | removeNodeErrorCount: 5,
75 | restoreNodeTimeout: 1000 * 60 * 5,
76 | defaultSelector: 'RR', // 'RANDOM' or 'ORDER'
77 | sources: {
78 | readonly: {
79 | enabled: true,
80 | host: '{{replica-1-host}}',
81 | user: '{{replica-1-user}}',
82 | password: '{{replica-1-password}}'
83 | }
84 | }
85 | }
86 | }
87 | },
88 |
89 | models: {
90 | connection: 'mySQLT'
91 | }
92 | }
93 | ```
94 |
95 | ### Use Transaction in your controllers
96 |
97 | ```javascript
98 | var Transaction = require('sails-mysql-transactions').Transaction;
99 |
100 | module.exports = {
101 | create: function (req, res) {
102 | // start a new transaction
103 | Transaction.start(function (err, transaction) {
104 | if (err) {
105 | // the first error might even fail to return a transaction object, so double-check.
106 | transaction && transaction.rollback();
107 | return res.serverError(err);
108 | }
109 |
110 | OneModel.transact(transaction).create(req.params.all(), function (err, modelInstance) {
111 | if (err) {
112 | transaction.rollback();
113 | return res.serverError(err);
114 | }
115 |
116 | // using transaction to update another model and using the promises architecture
117 | AnotherModel.transact(transaction).findOne(req.param('id')).exec(function (err, anotherInstance) {
118 | if (err) {
119 | transaction.rollback();
120 | return res.serverError(err);
121 | }
122 |
123 | // using update and association changes
124 | modelInstance.someAssociatedModel.remove(req.param('remove_id'));
125 |
126 | // standard .save() works when in transaction
127 | modelInstance.save(function (err, savedModel) {
128 | if (err) {
129 | transaction.rollback();
130 | return res.serverError(err);
131 | }
132 |
133 | // finally commit the transaction before sending response
134 | transaction.commit();
135 | return res.json({
136 | one: savedModel,
137 | another: anotherInstance
138 | });
139 | });
140 | });
141 | });
142 | });
143 | }
144 | };
145 | ```
146 |
147 | #### List of available transactional operations:
148 |
149 | ```javascript
150 | route = function (req, res) {
151 | Transaction.start(function (err, transaction) {
152 | OneModel.transact(transaction).create(/* ... */);
153 | OneModel.transact(transaction).update(/* ... */);
154 | OneModel.transact(transaction).find(/* ... */);
155 | OneModel.transact(transaction).findOrCreate(/* ... */);
156 | OneModel.transact(transaction).findOne(/* ... */);
157 | OneModel.transact(transaction).destroy(/* ... */);
158 | OneModel.transact(transaction).count(/* ... */);
159 | });
160 | };
161 | ```
162 |
163 | Other than those, `update`, `save` and association operations on instance methods work within transaction provided they
164 | were either stemmed from the same transaction or wrapped (`transaction.wrap(instance)`) by a transaction.
165 |
166 |
167 | ### Exceptions where transactions may fail
168 |
169 | In cases where you are performing model instance opertaions such as `save`, `destroy`, etc on instances that has been
170 | stemmed from a `.populate`, transaction might fail. In such scenarios, performing a `transaction.wrap(instance);` before
171 | doing instance operations should fix such errors.
172 |
173 | If you want to selectively intercept errors from this module, compare using `instanceof Transaction.AdapterError`.
174 |
175 | Note that this adapter adds an additional auto column called `transactionId`. If you do not want to use transaction on
176 | a particular model, you can turn off creation of this column by setting `autoTK: false` in your model.
177 |
178 |
179 | ## Support for Read Replicas
180 |
181 | When one or more read replica sources are provded, the following API can be used to access data from one of the defined
182 | replication source databases. This distributes your database workloads across multiple systems.
183 |
184 | Readonly still works without read replica using the normal non-transactional connection set.
185 |
186 | ```javascript
187 | action = function (req, res) {
188 | OneModel.readonly().find();
189 | OneModel.readonly().findOne();
190 | OneModel.readonly().count();
191 | };
192 | ```
193 |
194 | ## Support to retrieve changesets during update operations
195 |
196 | Since `sails-mysql` makes a `SELECT` query before every update; it makes sense that the query results can be utilised to
197 | return the changeset when a model is updated. The third parameter of `.update` returns an array having objects that
198 | contain only the fields that have changed and that too with their original values.
199 |
200 | ## Additional Configurations and Features
201 |
202 | 1. `queryCaseSensitive` when set to true, disables the feature where waterline performs case insensitive queries. (Note
203 | that it ises `wlNext` options for waterline-sequel.)
204 |
205 | 2. The bundled waterline adds additional feature to do the following
206 | - `Model.
50 | 54 | Forbidden 55 |
56 |57 | <% if (typeof error !== 'undefined') { %> 58 | <%= error %> 59 | <% } else { %> 60 | You don't have permission to see the page you're trying to reach. 61 | <% } %> 62 |
63 |64 | Why might this be happening? 65 |
66 |<%= __('Welcome to PencilPals!') %>
23 |<%= i18n('Hello %s, how are you today?', 'Pencil Maven') %>
24 |<%= i18n('That\'s right-- you can use either i18n() or __()') %>
25 | ``` 26 | 27 | ## Configuration 28 | Localization/internationalization config can be found in `config/i18n.js`, from where you can set your supported locales. 29 | -------------------------------------------------------------------------------- /tests/integration/app/config/locales/de.json: -------------------------------------------------------------------------------- 1 | { 2 | "Welcome": "Willkommen", 3 | "A brand new app.": "Eine neue App." 4 | } 5 | -------------------------------------------------------------------------------- /tests/integration/app/config/locales/en.json: -------------------------------------------------------------------------------- 1 | { 2 | "Welcome": "Welcome", 3 | "A brand new app.": "A brand new app." 4 | } 5 | -------------------------------------------------------------------------------- /tests/integration/app/config/locales/es.json: -------------------------------------------------------------------------------- 1 | { 2 | "Welcome": "Bienvenido", 3 | "A brand new app.": "Una aplicación de la nueva marca." 4 | } 5 | -------------------------------------------------------------------------------- /tests/integration/app/config/locales/fr.json: -------------------------------------------------------------------------------- 1 | { 2 | "Welcome": "Bienvenue", 3 | "A brand new app.": "Une toute nouvelle application." 4 | } 5 | -------------------------------------------------------------------------------- /tests/integration/app/config/log.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Built-in Log Configuration 3 | * (sails.config.log) 4 | * 5 | * Configure the log level for your app, as well as the transport 6 | * (Underneath the covers, Sails uses Winston for logging, which 7 | * allows for some pretty neat custom transports/adapters for log messages) 8 | * 9 | * For more information on the Sails logger, check out: 10 | * http://sailsjs.org/#/documentation/concepts/Logging 11 | */ 12 | 13 | module.exports.log = { 14 | 15 | /*************************************************************************** 16 | * * 17 | * Valid `level` configs: i.e. the minimum log level to capture with * 18 | * sails.log.*() * 19 | * * 20 | * The order of precedence for log levels from lowest to highest is: * 21 | * silly, verbose, info, debug, warn, error * 22 | * * 23 | * You may also set the level to "silent" to suppress all logs. * 24 | * * 25 | ***************************************************************************/ 26 | 27 | // level: 'info' 28 | 29 | }; 30 | -------------------------------------------------------------------------------- /tests/integration/app/config/models.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Default model configuration 3 | * (sails.config.models) 4 | * 5 | * Unless you override them, the following properties will be included 6 | * in each of your models. 7 | * 8 | * For more info on Sails models, see: 9 | * http://sailsjs.org/#/documentation/concepts/ORM 10 | */ 11 | 12 | module.exports.models = { 13 | 14 | /*************************************************************************** 15 | * * 16 | * Your app's default connection. i.e. the name of one of your app's * 17 | * connections (see `config/connections.js`) * 18 | * * 19 | ***************************************************************************/ 20 | // connection: 'localDiskDb', 21 | 22 | /*************************************************************************** 23 | * * 24 | * How and whether Sails will attempt to automatically rebuild the * 25 | * tables/collections/etc. in your schema. * 26 | * * 27 | * See http://sailsjs.org/#/documentation/concepts/ORM/model-settings.html * 28 | * * 29 | ***************************************************************************/ 30 | // migrate: 'alter' 31 | 32 | }; 33 | -------------------------------------------------------------------------------- /tests/integration/app/config/policies.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Policy Mappings 3 | * (sails.config.policies) 4 | * 5 | * Policies are simple functions which run **before** your controllers. 6 | * You can apply one or more policies to a given controller, or protect 7 | * its actions individually. 8 | * 9 | * Any policy file (e.g. `api/policies/authenticated.js`) can be accessed 10 | * below by its filename, minus the extension, (e.g. "authenticated") 11 | * 12 | * For more information on how policies work, see: 13 | * http://sailsjs.org/#/documentation/concepts/Policies 14 | * 15 | * For more information on configuring policies, check out: 16 | * http://sailsjs.org/#/documentation/reference/sails.config/sails.config.policies.html 17 | */ 18 | 19 | 20 | module.exports.policies = { 21 | 22 | /*************************************************************************** 23 | * * 24 | * Default policy for all controllers and actions (`true` allows public * 25 | * access) * 26 | * * 27 | ***************************************************************************/ 28 | 29 | // '*': true, 30 | 31 | /*************************************************************************** 32 | * * 33 | * Here's an example of mapping some policies to run before a controller * 34 | * and its actions * 35 | * * 36 | ***************************************************************************/ 37 | // RabbitController: { 38 | 39 | // Apply the `false` policy as the default for all of RabbitController's actions 40 | // (`false` prevents all access, which ensures that nothing bad happens to our rabbits) 41 | // '*': false, 42 | 43 | // For the action `nurture`, apply the 'isRabbitMother' policy 44 | // (this overrides `false` above) 45 | // nurture : 'isRabbitMother', 46 | 47 | // Apply the `isNiceToAnimals` AND `hasRabbitFood` policies 48 | // before letting any users feed our rabbits 49 | // feed : ['isNiceToAnimals', 'hasRabbitFood'] 50 | // } 51 | }; 52 | -------------------------------------------------------------------------------- /tests/integration/app/config/routes.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Route Mappings 3 | * (sails.config.routes) 4 | * 5 | * Your routes map URLs to views and controllers. 6 | * 7 | * If Sails receives a URL that doesn't match any of the routes below, 8 | * it will check for matching files (images, scripts, stylesheets, etc.) 9 | * in your assets directory. e.g. `http://localhost:1337/images/foo.jpg` 10 | * might match an image file: `/assets/images/foo.jpg` 11 | * 12 | * Finally, if those don't match either, the default 404 handler is triggered. 13 | * See `api/responses/notFound.js` to adjust your app's 404 logic. 14 | * 15 | * Note: Sails doesn't ACTUALLY serve stuff from `assets`-- the default Gruntfile in Sails copies 16 | * flat files from `assets` to `.tmp/public`. This allows you to do things like compile LESS or 17 | * CoffeeScript for the front-end. 18 | * 19 | * For more information on configuring custom routes, check out: 20 | * http://sailsjs.org/#/documentation/concepts/Routes/RouteTargetSyntax.html 21 | */ 22 | 23 | module.exports.routes = { 24 | 25 | /*************************************************************************** 26 | * * 27 | * Make the view located at `views/homepage.ejs` (or `views/homepage.jade`, * 28 | * etc. depending on your default view engine) your home page. * 29 | * * 30 | * (Alternatively, remove this and add an `index.html` file in your * 31 | * `assets` directory) * 32 | * * 33 | ***************************************************************************/ 34 | 35 | '/': { 36 | view: 'homepage' 37 | } 38 | 39 | /*************************************************************************** 40 | * * 41 | * Custom routes here... * 42 | * * 43 | * If a request to a URL doesn't match any of the custom routes above, it * 44 | * is matched against Sails route blueprints. See `config/blueprints.js` * 45 | * for configuration options and examples. * 46 | * * 47 | ***************************************************************************/ 48 | 49 | }; 50 | -------------------------------------------------------------------------------- /tests/integration/app/config/session.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Session Configuration 3 | * (sails.config.session) 4 | * 5 | * Sails session integration leans heavily on the great work already done by 6 | * Express, but also unifies Socket.io with the Connect session store. It uses 7 | * Connect's cookie parser to normalize configuration differences between Express 8 | * and Socket.io and hooks into Sails' middleware interpreter to allow you to access 9 | * and auto-save to `req.session` with Socket.io the same way you would with Express. 10 | * 11 | * For more information on configuring the session, check out: 12 | * http://sailsjs.org/#/documentation/reference/sails.config/sails.config.session.html 13 | */ 14 | 15 | module.exports.session = { 16 | 17 | /*************************************************************************** 18 | * * 19 | * Session secret is automatically generated when your new app is created * 20 | * Replace at your own risk in production-- you will invalidate the cookies * 21 | * of your users, forcing them to log in again. * 22 | * * 23 | ***************************************************************************/ 24 | secret: '200f282943850a87c6568ca740409999', 25 | 26 | 27 | /*************************************************************************** 28 | * * 29 | * Set the session cookie expire time The maxAge is set by milliseconds, * 30 | * the example below is for 24 hours * 31 | * * 32 | ***************************************************************************/ 33 | 34 | // cookie: { 35 | // maxAge: 24 * 60 * 60 * 1000 36 | // }, 37 | 38 | /*************************************************************************** 39 | * * 40 | * In production, uncomment the following lines to set up a shared redis * 41 | * session store that can be shared across multiple Sails.js servers * 42 | ***************************************************************************/ 43 | 44 | // adapter: 'redis', 45 | 46 | /*************************************************************************** 47 | * * 48 | * The following values are optional, if no options are set a redis * 49 | * instance running on localhost is expected. Read more about options at: * 50 | * https://github.com/visionmedia/connect-redis * 51 | * * 52 | * * 53 | ***************************************************************************/ 54 | 55 | // host: 'localhost', 56 | // port: 6379, 57 | // ttl:
48 |
74 |
75 |
76 |
77 |
--------------------------------------------------------------------------------
/tests/integration/app/views/homepage.ejs:
--------------------------------------------------------------------------------
1 |
2 |
3 |
7 |
12 |
13 |
49 | 
50 |
51 |
52 |
50 |
53 |
67 |
68 | 54 | Something's fishy here. 55 |
56 |57 | <% if (typeof error!== 'undefined') { %> 58 | <%= error %> 59 | <% } else { %> 60 | The page you were trying to reach doesn't exist. 61 | <% } %> 62 |
63 |64 | Why might this be happening? 65 |
66 |
69 |
70 | 
71 |
72 |
73 |
71 |
72 |
14 |
75 |
--------------------------------------------------------------------------------
/tests/integration/app/views/layout.ejs:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
15 | You're looking at:
17 |
18 | <%= __('A brand new app.') %>
16 |You're looking at: <%= view.pathFromApp + '.' +view.ext %>
17 |
19 |
21 |
74 | -
22 |
-
23 | 24 | 25 |30 |
Generate a REST API.
26 |27 | Run
29 |sails generate api user. This will create two files: a modelapi/models/User.jsand a controllerapi/controllers/UserController.js. 28 |
31 | -
32 | 33 | 34 |41 |
35 | Lift your app. 36 |
37 |38 | Run
40 |sails liftto start up your app server. If you visithttp://localhost:1337/userin your browser, you'll see a WebSocket-compatible user API. 39 |
42 | -
43 | 44 | 45 |51 |
46 | Dive in. 47 |
48 |Blueprints are just the beginning. You'll probably also want to learn how to customize your app's routes, set up security policies, configure your data sources, and build custom controller actions. For more help getting started, check out the links on this page.
49 | 50 |
52 |
54 |
55 |
73 | -
56 |
57 |
- App Structure 59 |
- Reference 60 |
- Supported Databases 61 | 62 |
- Sails 101 64 | 65 |
- StackOverFlow 67 |
- GitHub 68 |
- Google Group 69 |
- IRC (#sailsjs on freenode) 70 | 71 |