⚡️ umzug-hyper-storage ⚡️

umzug-hyper-storage is a zero-dependency Storage Adapter for Umzug
that uses a Hyper Data Service to track migrations

---

Table of Contents

- Install
- Getting Started
- Documentation
- License

---

Install

``sh
npm install umzug-hyper-storage
`

Getting Started

umzug-hyper-storage is a zero-dependency Storage Adapter for
Umzug that uses a
Hyper Data Service to track
migrations.

It works great as a tool to track and run migrations of your data stored in a
Hyper Data Service. It's also a great generalized script runner, not just for
running migrations.

To instantiate, provide an instance of
hyper-connect
that connects to your data service you would like to use to track your scripts.

`ts
import { Umzug } from 'umzug'
import { HyperStorage } from 'umzug-storage-adapter'
import { connect } from 'hyper-connect'

const hyper = connect(process.env.HYPER)

const umzug = new Umzug({
storage: new HyperStorage({ hyper }),
// optionally pass a hyper-connect instance to each of your scripts
context: {
hyper
}
...
})

await umzug.up() // run migrations
`

This will create a document in your Hyper Data Service in the follow shape:

`js
{
_id: 'hyper-scripts-meta',
type: '__scripts',
migrations: [
// array of scripts that have been ran
],
createdAt: '2022-04-27T20:30:40.688Z',
updatedAt: '2022-04-27T20:30:40.688Z'
}
`

As scripts are ran, their names are appended to the migrations array in this
document. If scripts are rolled back, their names are removed from the
migrations array, following normal Umzug rules.

This is how Umzug will track which scripts to run, rollback, or have been
previously executed.

Documentation

See Umzug Docs for Umzug usage.

A hyper-connect
instance connecting to your Hyper Data Service is required upon instantiation.

You may also pass a doc argument which dictates the shape of the document
added to hyper data service:

`ts
interface HyperStorageDocArgs {
// the _id of the meta document. Defaults to 'hyper-scripts-meta'
id?: string;
// the type of the meta document. Defaults to '__scripts'
type?: string;
/**
* the field on the meta document to use to store the document type
* ie. 'docType'. Defaults to 'type'
*/
typeField?: string;
/**
* the field on the meta document to store the time
* the meta document was created. Defaults to 'createdAt'
*/
createdField?: string;
/**
* the field on the meta document to store the time
* the meta document was last updated. Defaults to 'updatedAt'
*
* This field is updated each time migrations are ran or rolled back
*/
updatedField?: string;
}
`

$3

`ts
import { Umzug } from 'umzug'
import { HyperStorage } from 'umzug-storage-adapter'
import { connect } from 'hyper-connect'

const hyper = connect(process.env.HYPER)

const umzug = new Umzug({
storage: new HyperStorage({
hyper,
doc: {
type: 'umzug-scripts',
createdField: 'created_at',
updatedField: 'updated_at'
}
}),
...
})
`

$3

Chances are you are running scripts against a Hyper Data Service or
Hyper Cloud Application Services. You can
use Umzug context to pass
an instance of hyper-connect to each script ran.

By using context to _inject_ hyper-connect, this will make your scripts
easier to unit test.

`ts
import { Umzug } from 'umzug'
import { HyperStorage } from 'umzug-storage-adapter'
import { connect } from 'hyper-connect'

const hyper = connect(process.env.HYPER)

const umzug = new Umzug({
storage: new HyperStorage({ hyper }),
context: { hyper }
...
})

// then in your script:
const migration = {
name: '01-awesome-migration',
async up ({ context: { hyper }}) {
... // use hyper-connect to perform migration
},
async down ({ context: { hyper }}) {
... // use hyper-connect to perform rollback
}
}
``

---

License

Apache 2.0