Skip to content
This repository was archived by the owner on Oct 1, 2021. It is now read-only.

fix: require passing repo options to migrator #30

Merged
merged 4 commits into from
Aug 6, 2020
Merged

fix: require passing repo options to migrator #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2148c6b
fix: require passing repo options to migrator
achingbrain Aug 6, 2020
2940dac
chore: remove cli as it is not used anywhere
achingbrain Aug 6, 2020
954b447
chore: pr comments
achingbrain Aug 6, 2020
47b43ca
chore: remove extraneous file and dep
achingbrain Aug 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 0 additions & 7 deletions .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,13 +37,6 @@ jobs:
firefox: latest
script: npx aegir test -t browser -- --browsers FirefoxHeadless

- stage: test
name: sharness
os:
- linux
- osx
script: cd ./test/sharness && make

- stage: test
name: electron-main
os: osx
Expand Down
32 changes: 21 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Migration tool for JS IPFS Repo
# Migration tool for JS IPFS Repo <!-- omit in toc -->

[![Travis CI](https://flat.badgen.net/travis/ipfs/js-ipfs-repo-migrations)](https://travis-ci.com/ipfs/js-ipfs-repo-migrations)
[![codecov](https://codecov.io/gh/ipfs/js-ipfs-repo-migrations/branch/master/graph/badge.svg)](https://codecov.io/gh/ipfs/js-ipfs-repo-migrations)
Expand All @@ -15,36 +15,41 @@

This package is inspired by the [go-ipfs repo migration tool](https://github.com/ipfs/fs-repo-migrations/)

## Lead Maintainer
## Lead Maintainer <!-- omit in toc -->

[Adam Uhlíř](https://github.com/auhau/)

## Table of Contents
## Table of Contents <!-- omit in toc -->

- [Background](#background)
- [Install](#install)
- [npm](#npm)
- [Use in Node.js](#use-in-nodejs)
- [Use in a browser with browserify, webpack or any other bundler](#use-in-a-browser-with-browserify-webpack-or-any-other-bundler)
- [Use in a browser Using a script tag](#use-in-a-browser-using-a-script-tag)
- [Usage](#usage)
- [API](#api)
- [`.migrate(path, toVersion, {ignoreLock, repoOptions, onProgress, isDryRun}) -> Promise<void>`](#migratepath-toversion-ignorelock-repooptions-onprogress-isdryrun---promisevoid)
- [`onProgress(migration, counter, totalMigrations)`](#onprogressmigration-counter-totalmigrations)
- [`.revert(path, toVersion, {ignoreLock, repoOptions, onProgress, isDryRun}) -> Promise<void>`](#revertpath-toversion-ignorelock-repooptions-onprogress-isdryrun---promisevoid)
- [`getLatestMigrationVersion() -> int`](#getlatestmigrationversion---int)
- [CLI](#cli)
- [Creating a new migration](#creating-a-new-migration)
- [Architecture of a migration](#architecture-of-a-migration)
- [`.migrate(repoPath, repoOptions)`](#migraterepopath-repooptions)
- [`.revert(repoPath, repoOptions)`](#revertrepopath-repooptions)
- [Browser vs. NodeJS environments](#browser-vs-nodejs-environments)
- [Guidelines](#guidelines)
- [Integration with js-ipfs](#integration-with-js-ipfs)
- [Tests](#tests)
- [Empty migrations](#empty-migrations)
- [Migrations matrix](#migrations-matrix)
- [Developer](#developer)
- [Module versioning notes](#module-versioning-notes)
- [Module versioning notes](#module-versioning-notes)
- [Contribute](#contribute)
- [License](#license)

## Background


As js-ipfs evolves and new technologies, algorithms and data structures are incorporated it is necessary to
enable users to transition between versions. Different versions of js-ipfs may expect a different IPFS repo structure or content (see: [IPFS repo spec](https://github.com/ipfs/specs/tree/master/repo), [JS implementation](https://github.com/ipfs/js-ipfs-repo) ).
So the IPFS repo is versioned, and this package provides a framework to create migrations to transition
Expand Down Expand Up @@ -87,10 +92,15 @@ const migrations = require('ipfs-repo-migrations')
const repoPath = 'some/repo/path'
const currentRepoVersion = 7
const latestVersion = migrations.getLatestMigrationVersion()
const repoOptions = {
... // the same storage backend/storage options passed to `ipfs-repo`
}
Copy link

@jacobheun jacobheun Aug 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is repoOptions still optional and we just need to make sure to pass it through if provided?

Copy link
Member Author

@achingbrain achingbrain Aug 6, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's been passed through by ipfs-repo since migrations were added.

Copy link

@jacobheun jacobheun Aug 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The readme api methods mention repoOptions as always optional, this is not the case as this change will throw errors. This doesn't matter for ipfs-repo since it is providing passing repoOptions to migrate and revert, but we should remove the optional jsdocs/readme as this is required.

Copy link
Member Author

@achingbrain achingbrain Aug 6, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've removed the optional notes in the readme. Which is a bit odd because it makes the options object mandatory, but I think that's ok for now as we are the only consumer of this module and we pass an options object. When I re-PR this against master I'll move the repo options out of the options object to make the options optional again.


if(currentRepoVersion < latestVersion){
// Old repo! Lets migrate to latest version!
await migrations.migrate(repoPath, latestVersion)
await migrations.migrate(repoPath, latestVersion, {
repoOptions
})
}
```

Expand All @@ -106,9 +116,9 @@ Executes a forward migration to a specific version, or to the latest version if

* `path` (string, mandatory) - path to the repo to be migrated
* `toVersion` (int, mandatory) - version to which the repo should be migrated.
* `options` (object, optional) - options for the migration
* `options` (object, mandatory) - options for the migration
* `options.ignoreLock` (bool, optional) - if true will not lock the repo when applying migrations. Use with caution.
* `options.repoOptions` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
* `options.repoOptions` (object, mandatory) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
* `options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
* `options.isDryRun` (bool, optional) - flag that indicates if it is a dry run that should give the same output as running a migration but without making any actual changes.

Expand All @@ -129,9 +139,9 @@ Executes backward migration to a specific version.

* `path` (string, mandatory) - path to the repo to be reverted
* `toVersion` (int, mandatory) - version to which the repo should be reverted to.
* `options` (object, optional) - options for the reversion
* `options` (object, mandatory) - options for the reversion
* `options.ignoreLock` (bool, optional) - if true will not lock the repo when applying migrations. Use with caution.
* `options.repoOptions` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
* `options.repoOptions` (object, mandatory) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
* `options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
* `options.isDryRun` (bool, optional) - flag that indicates if it is a dry run that should give the same output as running a migration but without making any actual changes.

Expand Down
9 changes: 2 additions & 7 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,9 @@
"main": "src/index.js",
"browser": {
"./src/repo/lock.js": "./src/repo/lock-memory.js",
"./src/repo/default-root-options.js": "./src/repo/ldefault-root-options.browser.js",
"datastore-fs": "datastore-level"
},
"bin": {
"jsipfs-migrations": "./src/cli.js"
},
"repository": {
"type": "git",
"url": "https://github.com/ipfs/js-ipfs-repo-migrations.git"
Expand All @@ -45,17 +43,14 @@
},
"dependencies": {
"buffer": "^5.6.0",
"chalk": "^4.0.0",
"cids": "^0.8.3",
"datastore-core": "^1.1.0",
"datastore-fs": "^1.0.0",
"datastore-level": "^1.1.0",
"debug": "^4.1.0",
"interface-datastore": "^1.0.2",
"multibase": "^1.0.1",
"proper-lockfile": "^4.1.1",
"yargs": "^15.3.1",
"yargs-promise": "^1.1.0"
"proper-lockfile": "^4.1.1"
},
"devDependencies": {
"aegir": "^23.0.0",
Expand Down
62 changes: 0 additions & 62 deletions src/cli.js
View file
Open in desktop

This file was deleted.

165 changes: 0 additions & 165 deletions src/commands.js
View file
Open in desktop

This file was deleted.

15 changes: 15 additions & 0 deletions src/errors.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,18 @@ class InvalidValueError extends Error {

InvalidValueError.code = 'ERR_INVALID_VALUE'
exports.InvalidValueError = InvalidValueError

/**
* Exception raised when config is not passed.
*/
class MissingRepoOptionsError extends Error {
constructor (message) {
super(message)
this.name = 'MissingRepoOptionsError'
this.code = 'ERR_MISSING_REPO_OPTIONS'
this.message = message
}
}

MissingRepoOptionsError.code = 'ERR_MISSING_REPO_OPTIONS'
exports.MissingRepoOptionsError = MissingRepoOptionsError
Loading