@balena/pinejs 15.0.0-true-boolean-7896b116c446d891d7a0d5e4085c02a13bc9c725 → 15.0.1-build-migrations-clarify-marking-sbvr-optional-d6d0ded8eccc6eadb2492f4697918cf0afd00215-1

package/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:16-alpine as runner
+
+WORKDIR /usr/src/pine
+
+COPY . ./
+RUN npm install
+
+
+FROM runner as sut
+CMD npm run mocha
+
+FROM runner
+
+

package/Gruntfile.ts

@@ -17,16 +17,13 @@ _.forEach(serverConfigs, (config) => {
 	config.optimization = {
 		minimizer: [
 			new TerserPlugin({
-				cache: true,
 				parallel: true,
-				sourceMap: true,
 				terserOptions: {
 					output: {
 						beautify: true,
 						ascii_only: true,
 					},
 					compress: {
-						warnings: true,
 						sequences: false,
 						unused: false, // We need this off for OMeta
 					},
@@ -59,9 +56,9 @@ export = (grunt: typeof Grunt) => {
 		},
 
 		concat: _.mapValues(serverConfigs, (config, task) => {
-			const defines = (config.plugins as Array<
-				WebpackPluginInstance & { definitions?: {} }
-			>).find((plugin) => plugin.definitions != null)!.definitions;
+			const defines = (
+				config.plugins as Array<WebpackPluginInstance & { definitions?: {} }>
+			).find((plugin) => plugin.definitions != null)!.definitions;
 			return {
 				options: {
 					banner: `

package/README.md

@@ -1,4 +1,13 @@
-# Pine.js
+
+<div align="center">
+  <img width="400" height="auto" src="https://raw.githubusercontent.com/balena-io/pinejs/master/pinejs.png">
+  <br>
+  <br>
+</div>
+
+[![npm version](https://badge.fury.io/js/@balena%2Fpinejs.svg)](https://badge.fury.io/js/@balena%2Fpinejs)
+
+
 Pine.js is a sophisticated rules-driven API engine that enables you to define rules in a structured subset of English. Those rules are used in order for Pine.js to generate a database schema and the associated [OData](http://www.odata.org/) API. This makes it very easy to rapidly create, update and maintain a backend while keeping the logic in an easily understood form, as well as providing the ability to update and maintain this logic going forward.
 
 Rules are described in *SBVR* format, which stands for "Semantics of Business Vocabulary and Business Rules". SBVR provides a way to capture specifications in natural language and represent them in formal logic, so they can be machine processed. 

package/VERSION

@@ -0,0 +1 @@
+15.0.1

package/build/browser.ts

@@ -18,7 +18,7 @@ config.plugins = config.plugins.concat(
 	new webpack.DefinePlugin({
 		'process.browser': true,
 		'process.env.CONFIG_LOADER_DISABLED': true,
-		'process.env.DEBUG': true,
+		'process.env.PINEJS_DEBUG': true,
 		'process.env.SBVR_SERVER_ENABLED': true,
 	}),
 );

package/build/config.ts

@@ -18,7 +18,6 @@ export = {
 	externals: {
 		bcrypt: true,
 		bcryptjs: true,
-		bluebird: true,
 		'body-parser': true,
 		child_process: true,
 		compression: true,

package/docker-compose.npm-test.yml

@@ -0,0 +1,11 @@
+version: "2.1"
+services:
+  postgres:
+    image: postgres:15-alpine
+    restart: always
+    environment:
+      POSTGRES_USER: docker
+      POSTGRES_PASSWORD: docker
+      POSTGRES_DB: postgres
+    ports:
+      - "5431:5432"

package/docs/AdvancedUsage.md

@@ -1,13 +1,15 @@
-# Advanced Pinejs use
+# Advanced Pine.js usage
 
-This guide assumes you have already read through the [getting started guide](./GettingStarted.md) and the [project configuration guide](./ProjectConfig.md). In this tutorial we will iterate on the previous model to add a custom validation step when creating a new device.
-To achieve this we can use (Hooks)[./Hooks.md], they allow us to execute custom server code whenever an API call is made.
+This guide assumes you have already read through the [getting started guide](./GettingStarted.md) and the [project configuration guide](./ProjectConfig.md).
+In this tutorial we will iterate on the previous model to add a custom validation step when creating a new device.
+To achieve this we can use [Hooks](./Hooks.md), they allow us to execute custom server code whenever an API call is made.
 
-## Custom Sever Code
+## Custom Server Code
 To add custom functionality to our module we will have to provide a setup function, this will be called during server startup, and will take care of initializing everything as we need it.
 
-After following the [getting started guide](./GettingStarted.md), we should have a `.sbvr` file with our model, and a `config.json` file with our configuration, the only change we have to do for now, is to add the name of the file where we will write our custom server code, to the configuration.
-Go ahead and make an empty `example.coffee` file, pine can load custom code written in both Javascript or CoffeeScript, however we will stick to CoffeeScript for this guide.
+After following the [getting started guide](./GettingStarted.md), we should have a `.sbvr` file with our model, and a `config.json` file with our configuration,
+the only change we have to do for now is to add the name of the file where we will write our custom server code, to the configuration.
+Go ahead and make an empty `src/example.js` file, Pine.js can load custom code written in both Javascript or CoffeeScript, however we will stick to JavaScript for this guide.
 
 This is how your files should look at the end of this step.
 
@@ -43,7 +45,7 @@ Fact Type: device has type
 			  "modelName": "Example",
 			  "modelFile": "example.sbvr",
 			  "apiRoot": "example",
-        "customServerCode": "example.coffee"
+			  "customServerCode": "example.js"
 	}],
 	"users": [{
 			 "username": "guest",
@@ -55,78 +57,90 @@ Fact Type: device has type
 
 Now that we have taken care of the necessary plumbing we can start to write some actual code.
 
-Lets assume we want to enforce that each device that is created, has a unique pair of name and devtype. This way we can have multiple devices with the same name as long as they correspond to different underlying dev types.
+Lets assume we want to enforce that each device that is created, has a unique pair of name and type. This way we can have multiple devices with the same name as long as they correspond to different underlying dev types.
 We could enforce this directly from the SBVR model, but we will do so with a custom hook just to show how easy and effective adding a hook can be.
 
-In our `example.coffee` file we will export a setup function with the following signature
+In our `example.js` file we will export a setup function with the following signature
 
-```coffee-script
-exports.setup = (app, sbvrUtils, db, callback) ->
+```javascript
+exports.setup = (app, sbvrUtils, db, callback) => {}
 ```
 
-This function will be called during pines initialization; inside the `setup` function we can run any custom code, in our case this will be a hook (refer to [Hooks](./Hooks.md) for more information). The last argument passed is a callback to signal the setup is complete; since the callback is wrapped into a promise, we also have to option to ignore it and directly return a promise from the `setup` function. The setup will fail if the returned promise resolves to an error and succeed otherwise.
-
-There are many options for when a hook must run, in our case, we want to run the validation step right after pine parses the request as this is the earliest moment we will have access to the information we will need.
-
-To do so, we can add a `POSTPARSE` hook: this hook should only run on `POST` requests which attempt to create devices.
-This translates to the following function
-
-```coffee-script
-sbvrUtils.addHook 'POST', 'example', 'device',
-  POSTPARSE: ({ req, request, api }) ->
-    validate(request, api)
+This function will be called during pines initialization; inside the `setup` function we can run any custom code, in our case this will be a hook (refer to [Hooks](./Hooks.md) for more information). 
+The last argument passed is a callback to signal the setup is complete; since the callback is wrapped into a promise, we also have the option to ignore it and directly return a promise from the `setup` function.
+The setup will fail if the returned promise resolves to an error and succeed otherwise.
+
+There are many options for when a hook must run, in this case we will add a `PRERUN` hook.
+This translates to the following function:
+```javascript
+sbvrUtils.addPureHook('POST', 'example', 'device', {
+  PRERUN: ({ request, api }) => {
+    validate(request, api);
+  }
+});
 ```
 
 Now we are just left with needing to define our own validation step: in general this can be either synchronous or asynchronous.
 In case our hook needs to perform an async action we simply return a promise from it, pine will take care of waiting for the result of this promise before processing a request further.
 
-Recall we want to enforce that, when creating a device, the pair of name and devtype, is unique to the device being created.
-To check for this condition we can directly query the device resource to see if any device comes up with the same pair of name and devtype.
-
-The api object that is passed in the `POSTPARSE` callback is a special object generated by pinejs. It can be used to query the model: here it will be bound to the model the hook is referring to and will automatically inherit the user privileges.
-
-We can use this to check if the model contains a device with the same name/devtype combination.
-
-```coffee-script
-validate = (request, api) ->
-    api.get
-      resource: request.resourceName
-      options:
-        $filter:
-          name: request.values.name
-          devtype: request.values.devtype
-    .then (result) ->
-      if result?.length > 0
-        throw new Error('Each device must have a different name/devtype pair')
+Recall we want to enforce that, when creating a device, the pair of name and type is unique to the device being created.
+To check for this condition we can directly query the device resource to see if any device comes up with the same pair of name and type.
+
+The `api` object that is passed in the `PRERUN` callback is a special object generated by Pine.js.
+It can be used to query the model: here it will be bound to the model the hook is referring to and will automatically inherit the user privileges.
+
+We can use this to check if the model contains a device with the same name/type combination.
+
+```javascript
+const validate = (request, api) => {
+    api.get({
+      resource: request.resourceName,
+      options: {
+        $filter: {
+          name: request.values.name,
+          type: request.values.type
+        }
+      }
+    }).then((result) => {
+      if (result && result.length && result.length > 0) {
+        throw new Error('Each device must have a different name/type pair');
+      }
+    });
+};
 ```
 
 `resourceName` will contain the name of the resource being accessed by the request, since we specified the hook to only run when requests are made against the `device` resource this will actually be fixed.
-The query we run will select all devices where name and devtype match the ones we found in the request values, if any result is found this means that the pair is already taken.
+The query we run will select all devices where name and type match the ones we found in the request values, if any result is found this means that the pair is already taken.
 To report this to the user we can simply throw an Error with the desired message and pine will relay it back to the end user with an appropriate status code.
 
 This is the full source code for the tutorial.
 
-```coffee-script
-exports.setup = (app, sbvrUtils, db, callback) ->
-
-  sbvrUtils.addHook 'POST', 'example', 'device',
-    POSTPARSE: ({ req, request, api }) ->
-      validate(request, api)
-
-  validate = (request, api) ->
-    api.get
-      resource: request.resourceName
-      options:
-        $filter:
-          name: request.values.name
-          devtype: request.values.devtype
-    .then (result) ->
-      if result?.length > 0
-        throw new Error('Each device must have a different name/devtype pair')
-
-  callback()
+```javascript
+const validate = (request, api) => {
+    api.get({
+        resource: request.resourceName,
+        options: {
+            $filter: {
+                name: request.values.name,
+                type: request.values.type
+            }
+        }
+    }).then((result) => {
+        if (result && result.length && result.length > 0) {
+            throw new Error('Each device must have a different name/type pair');
+        }
+    });
+};
+
+exports.setup = (_app, sbvrUtils) => {
+    sbvrUtils.addPureHook('POST', 'example', 'device', {
+        PRERUN: ({ request, api }) => {
+            validate(request, api);
+        }
+    });
+};
 ```
 
-### Where to go from here:
-* Learn about migrations that you can execute prior to Pine.js executing a given sbvr model: [Migrations.md](./Migrations.md)
-* Learn more about what you can do in the setup function from the documentation [CustomServerCode.md](./CustomServerCode.md)
+### Where to go from here
+* Learn about migrations that you can execute prior to Pine.js executing a given SBVR model: [Migrations.md](./Migrations.md)
+* Learn more about what you can do in the setup function: [CustomServerCode.md](./CustomServerCode.md)

package/docs/GettingStarted.md

@@ -1,37 +1,40 @@
 # Getting Started with Pine.js
 
-This guide assumes that you have already read the main [README](https://github.com/balena-io/pinejs/blob/master/README.md) file of this repo and you have understood the main concepts of Pine.js.
+This guide assumes that you have already read the main [README](../README.md) file of this repo and you have understood the main concepts of Pine.js.
 
 ## Initialize an example application
 
 Let's create a new Pine.js application. We will see that by defining our model rules in SBVR format, Pine.js will create the database schema and will provide out of the box an OData API, ready to use to interact with our database and resources.
 
-To begin with, you'll need to install PostgreSQL on your system, and configure a database and a user with read/write/metadata permissions on the database. In this guide, we will use `example` as the database name and `exampler` as the user name. Open your favorite terminal and type the following commands:
+To begin with, you'll need to install PostgreSQL on your system, and configure a database and a user with read/write/metadata permissions on the database.
+In this guide, we will use `example` as the database name and `exampler` as the user name. Open your favorite terminal and type the following commands:
 
-```
-$ createuser -W exampler
-$ createdb example -O exampler
+```sh
+createuser -W exampler
+createdb example -O exampler
 ```
 
-The above commands will create a user with name `exampler` and will prompt for a password, and then will set `exampler` as the database owner. You can also use your favorite tool to achieve the same result, such as pgAdmin.
+The above commands will create a user with name `exampler` and will prompt for a password, and then will set `exampler` as the database owner.
+You can also use your favorite tool to achieve the same result, such as pgAdmin.
 
 Next you'll need to install Pine.js as a dependency of your application. Go to a new directory that will use for your application. Let's say `pine-get-started` and type:
 
-```
-$ npm init
+```sh
+npm init
 ```
 
-Feel free to enter any information you like for your application when prompted, like application name, version, description, etc. The above command will initialize your application by creating the `package.json` file.
+Feel free to enter any information you like for your application when prompted, like application name, version, description, etc.
+The above command will initialize your application by creating the `package.json` file.
 
-```
-$ npm install --save @balena/pinejs
+```sh
+npm install @balena/pinejs
 ```
 
-The above commands will install pinejs as a dependency for your application, i.e. it will create the node_modules directory that amongst others will contain Pine.js, and will update the corresponding record in your `package.json` file.
+The above commands will install pinejs as a dependency for your application, i.e. it will create the `node_modules` directory that amongst others will contain Pine.js, and will update the corresponding record in your `package.json` file.
 
 Let's see what your directory looks like now:
 
-```
+```sh
 $ tree -L 3
 .
 ├── node_modules
@@ -42,9 +45,10 @@ $ tree -L 3
 
 Now, create a directory for our source files, `src` and enter that directory.
 
-First, we have to create a configuration file, `config.json` that will provide to Pine.js the necessary configuration regarding the resource model and the user permissions. Open your favorite editor and type the following into the `config.json` file:
+First, we have to create a configuration file, `config.json` that will provide to Pine.js the necessary configuration regarding the resource model and the user permissions.
+Open your favorite editor and type the following into the `config.json` file:
 
-```
+```json
 {
 	"models": [{
 			  "modelName": "Example",
@@ -59,7 +63,8 @@ First, we have to create a configuration file, `config.json` that will provide t
 }
 ```
 
-The above file states that Pine.js has to use the file `example.sbvr` to find the model definitions, and `/example` as the root path to access the model's API. You can read more about project configuration in [ProjectConfig](https://github.com/balena-io/pinejs/blob/master/docs/ProjectConfig.md).
+The above file states that Pine.js has to use the file `example.sbvr` to find the model definitions, and `/example` as the root path to access the model's API.
+You can read more about project configuration in [ProjectConfig](./ProjectConfig.md).
 
 Now, let's create the models. Again in your favorite editor, type the following in the `example.sbvr` file and save it under `src` folder.
 
@@ -87,19 +92,58 @@ Fact Type: device has type
 	 Necessity: each device has exactly one type.
 ```
 
-In this model we are defining an entity called `device`, this entity has some attributes such as `name`, `note` and `type`, along with some constraints, ensuring that a device must have exactly one device type, and at most one name and one note. The `Vocabulary` declaration is a convenient way for partitioning parts of larger sbvr files.
+In this model we are defining an entity called `device`, this entity has some attributes such as `name`, `note` and `type`, along with some constraints,
+ensuring that a device must have exactly one device type, and at most one name and one note. The `Vocabulary` declaration is a convenient way for partitioning parts of larger SBVR files.
+
+### Initialise a TypeScript project
 
 Now, let's create a small main file for our application that will call the Pine.js server. Let's install some basic dependencies:
+Create a small main file for our application that will call the Pine.js server. Let's install some basic dependencies:
 
+```sh
+npm install express body-parser
+npm install -D typescript ts-node @types/express
 ```
-$ npm install --save coffeescript
-$ npm install --save express
-$ npm install --save body-parser
+
+And inside your `src` folder, create a file `app.ts` with the following content:
+
+```typescript
+import express, { Request, Response } from 'express';
+import * as pine from '@balena/pinejs';
+
+const app = express();
+app.use(express.urlencoded({ extended: true }));
+app.use(express.json());
+
+app.use('/ping', (_req: Request, res: Response) => {
+	res.sendStatus(200);
+});
+
+pine.init(app).then(() => {
+    app.listen(1337, () => {
+        console.log('server started');
+    });
+});
 ```
 
-And inside your `src` folder, create a file `app.coffee` with the following content:
+Inside your `package.json` file enter the following line inside the section `scripts`:
 
 ```
+"start": "ts-node src/app.ts src"
+```
+
+### Initialise a CoffeeScript project
+
+Alternatively, here's an example of the same small application written in CoffeeScript.  
+Install some basic dependencies:
+
+```sh
+npm install coffeescript express body-parser
+```
+
+And inside your `src` folder, create a file `app.coffee` with the following content:
+
+```coffeescript
 pinejs = require '@balena/pinejs'
 express = require 'express'
 app = express()
@@ -118,7 +162,6 @@ pinejs.init(app)
 		console.info('Server started')
 ```
 
-
 Finally, inside your `package.json` file enter the following line inside the section `scripts`:
 
 ```
@@ -127,7 +170,7 @@ Finally, inside your `package.json` file enter the following line inside the sec
 
 Let's see what our application directory looks like now:
 
-```
+```sh
 $ tree -L 3
 .
 ├── node_modules
@@ -171,24 +214,28 @@ $ tree -L 3
 
 Assuming postgreSQL is running, execute the following command, replacing `[your_password]` with the password you set for the user `exampler`.
 
-```
-$ DATABASE_URL=postgres://exampler:[your_password]@localhost:5432/example npm start
+```sh
+DATABASE_URL=postgres://exampler:[your_password]@localhost:5432/example npm start
 ```
 
-Pine.js will connect to the `example` database and it will create the database schema and the associated API endpoints. Once the server is up, use your favourite tool, such as pgAdmin, to connect to the database and take a look inside. Among the other things, you will find that Pine.js has created a table called `device`, which will contain the devices we earlier specified in the model. By inspecting the structure of this table, you can see that the constraints specified in sbvr model get directly translated to constraints in the underlying database.
+Pine.js will connect to the `example` database and it will create the database schema and the associated API endpoints.
+Once the server is up, use your favourite tool, such as pgAdmin, to connect to the database and take a look inside.
+Among the other things, you will find that Pine.js has created a table called `device`, which will contain the devices we earlier specified in the model.
+By inspecting the structure of this table, you can see that the constraints specified in sbvr model get directly translated to constraints in the underlying database.
 
 Pine.js also generates users and permissions; the database will contain a `guest` user with access to all resources, these entities are created internally by Pine.js from the config file we provided.
 
 ## Accessing Resources
 
-Now that the server is up and running we are able to create, delete or update entities from the specified model. Recall that Pine.js provides access to the database through the associated [OData API](http://www.odata.org), this means that we can make requests to the database following the OData specification to manage our model.
+Now that the server is up and running we are able to create, delete or update entities from the specified model.
+Recall that Pine.js provides access to the database through the associated [OData API](http://www.odata.org), this means that we can make requests to the database following the OData specification to manage our model.
 
 We will use cURL to make these requests, so open up another terminal window and place it side by side to the one running the server.
 
 First of all we need to create a device. To do so type the following in the new window:
 
-```
-$ curl -X POST -d name=testdevice -d note=testnote -d type=raspberry http://localhost:1337/example/device
+```sh
+curl -X POST -d name=testdevice -d note=testnote -d type=raspberry http://localhost:1337/example/device
 ```
 
 If the creation succeeds the server will respond with an object representing the new entity, in this case it will look something like this:
@@ -201,14 +248,14 @@ Aside from `__metadata` which is used internally, the properties of this object
 
 If we ask the server for a list of devices we will see the one we just created:
 
-```
-$ curl -X GET http://localhost:1337/example/device
+```sh
+curl -X GET http://localhost:1337/example/device
 ```
 
 The server will respond with an array containing all the devices, if we want to access a specific one, it is sufficient to add the id at the end of the URL we pass.
 
-```
-$ curl -X GET http://localhost:1337/example/device(1)
+```sh
+curl -X GET 'http://localhost:1337/example/device(1)'
 ```
 
 The above cURL request will return the single entity with `id=1`.
@@ -216,24 +263,26 @@ The above cURL request will return the single entity with `id=1`.
 To modify the device we just created: the OData specification tells us that to do so we can make a `PUT` request to the endpoint that represents the entity.
 Lets try this:
 
-```
-$ curl -X PUT -d name=testdevice -d note=updatednote http://localhost:1337/example/device(1)
+```sh
+curl -X PUT -d name=testdevice -d note=updatednote 'http://localhost:1337/example/device(1)'
 
 ***
 Internal Server Error
 ```
 
-What went wrong here? Pine.js is simply preventing us from violating the constraints we had previously defined. One of these was that each device has exactly one type, but in the request we are forgot about this; luckily Pine.js can catch this kind of mistakes and will reject the update.
+What went wrong here? Pine.js is simply preventing us from violating the constraints we had previously defined.
+One of these was that each device has exactly one type, but in the request we forgot about this; luckily Pine.js can catch these kind of mistakes and will reject the update.
 
 To correctly modify the device we can try:
 
-```
-$ curl -X PUT -d name=testdevice -d note=updatednote -d type=raspberry http://localhost:1337/example/device(1)
+```sh
+curl -X PUT -d name=testdevice -d note=updatednote -d type=raspberry 'http://localhost:1337/example/device(1)'
 ```
 
-You can now try to delete this entity to restore the database to it’s initial state. Recall from the OData specification that this can be done by performing a DELETE request at the endpoint represented by the entity we intend to delete.
+You can now try to delete this entity to restore the database to it’s initial state.
+Recall from the OData specification that this can be done by performing a `DELETE` request at the endpoint represented by the entity we intend to delete.
 
 ### Where to go from here:
 * Follow the [advanced usage guide](./AdvancedUsage.md) that builds on top of this example to add some custom validation via hooks
-* Learn about migrations that you can execute prior to Pine.js executing a given sbvr model: [Migrations.md](https://github.com/balena-io/pinejs/blob/master/docs/Migrations.md)
-* Learn about [Hooks](https://github.com/balena-io/pinejs/blob/master/docs/Hooks.md) that you can implement in order to execute custom code when API calls are requested.
+* Learn about migrations that you can execute prior to Pine.js executing a given sbvr model: [Migrations.md](./Migrations.md)
+* Learn about [Hooks](./Hooks.md) that you can implement in order to execute custom code when API calls are requested.

package/docs/Migrations.md

@@ -46,4 +46,105 @@ Migrations which are Node modules should export a function which will be called
 
 You can execute SQL using `tx.executeSql(query)`, however note that the model for which the migration is running will *not* be available under `sbvrUtils.api`, as it has not executed yet.
 
-You should return a promise so pinejs can wait for completion/errors.
+You should return a promise so pinejs can wait for completion/errors.
+
+
+## Async Migrations
+
+Migrations that may lock tables for a long time, eg. migrating data between columns on large tables, can be run as async migrations.
+
+Async migrations are executed in small batches within individual transactions and run concurrently while Pine is serving requests. Async migrations are multi-instance safe. They are synchronized between instances via the `migration status` database table and the minimum interval between two migration executions is guaranteed across instances.
+
+When Pine starts and determines there are multiple async migrations to be run, it starts all migrations concurrently. These migrations however do not run in parallel: only one migration batch is executed at any given time, then another, and so on. Thus, migrations should not depend on the result a previous one.
+Once an async migration starts, it keeps running forever even after Pine instance restarts. The async migration will stop being executed when finalized with a dedicated flag in the async migration definition. This is to guarantee that new data inserted or updated at runtime can also be migrated. The status of running migrations can be checked in `migration status` table. The configured execution parameters and the execution metrics are stored and updated after each migration batch completes. 
+
+Each async migration needs to specify a pair of an async and a sync migration part, so that the sync migration statement closes the async migration and guarantees database consistency.
+
+Async migrations are stored in the migrations folder, alongside synchronous migrations. Their file names are significant and must contain the string `.async.` so they are treated as async migrations. They can only be Typescript / Javascript (with `.ts`/`.js` extensions) files.
+
+The async migration query must have a `LIMIT` statement to limit the maximum number of affected rows per batch.
+
+
+### Async migration procedure
+* Deployment 1
+	- Add new column (with independent sync migration) to contain new data and add code accessing the new column.
+	- Update the service's implementation to set both the old & new column on each write.
+	- The service's implementation should only read the old column since the async migration still migrates data from old column to new column.
+	- Async migrator runs forever.
+* Deployment 2
+	- Finalize async migration => only sync migration part gets executed.
+	- Sync migration migrates all left over data from old column to new column.
+	- Update the service's implementation to only read the new column, but still write the old one as well.
+	- Mark the old field as optional in the sbvr if it isn't, or set a default value for it.
+* Deployment 3
+	- Update the service's implementation to stop settings the old column and remove it from the sbvr.
+	- Make the old field NULLable if it isn't.
+* Deployment 4
+	- Delete the old column with a sync migration.
+
+### TS migration file format with SQL query string
+
+The placeholder `%%ASYNC_BATCH_SIZE%%` will be replaced with the value specified by asyncBatchSize parameter
+
+``` javascript
+export = {
+	asyncSql: `\
+	UPDATE "device"
+	SET "note" = "device"."name"
+	WHERE id IN (
+		SELECT id FROM "device"
+		WHERE  "device"."name" <> "device"."note" OR "device"."note" IS NULL
+		LIMIT %%ASYNC_BATCH_SIZE%%
+	);
+	`,
+	syncSql: `\
+	UPDATE "device"
+	SET "note" = "device"."name"
+	WHERE  "device"."name" <> "device"."note" OR "device"."note" IS NULL;
+	`,
+	delayMS: 100,
+	backoffDelayMS: 4000,
+	errorThreshold: 15,
+	asyncBatchSize: 1,
+	finalize: true,
+};
+```
+
+### TS migration file format with migrator function definition
+
+`${options.batchSize}` will be the value specified by asyncBatchSize parameter.
+
+``` javascript
+export = {
+	asyncFn: async (tx: any, options) => {
+		const staticSql = `\
+		UPDATE "device"
+		SET "note" = "device"."name"
+		WHERE id IN (
+			SELECT id FROM "device"
+			WHERE  "device"."name" <> "device"."note" OR "device"."note" IS NULL
+			LIMIT ${options.batchSize}
+		);
+		`;
+
+		return await tx.executeSql(staticSql);
+	},
+	syncFn: async (tx: any) => {
+		const staticSql = `\
+		UPDATE "device"
+		SET "note" = "device"."name"
+		WHERE  "device"."name" <> "device"."note" OR "device"."note" IS NULL;
+		`;
+
+		await tx.executeSql(staticSql);
+	},
+	asyncBatchSize: 1,
+	delayMS: 100,
+	backoffDelayMS: 4000,
+	errorThreshold: 15,
+	finalize: true,
+};
+
+```
+### SQL query file (plain text)
+Plain SQL files are not supported as they cannot bundle async and sync migration statements in one file. Moreover they cannot carry migration metadata.