You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Oct 1, 2021. It is now read-only.
@@ -45,7 +45,7 @@ This package is inspired by the [go-ipfs repo migration tool](https://github.com
45
45
## Background
46
46
47
47
48
-
As js-ipfs evolves and new technologies, algorithms and data structures are incorporated it is necessary to
48
+
As js-ipfs evolves and new technologies, algorithms and data structures are incorporated it is necessary to
49
49
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) ).
50
50
So the IPFS repo is versioned, and this package provides a framework to create migrations to transition
51
51
from one version of IPFS repo to the next/previous version.
To migrate your repository using the CLI, see the [how to run migrations](./run.md) tutorial.
97
+
To migrate your repository using the CLI, see the [how to run migrations](./run.md) tutorial.
98
98
99
99
## API
100
100
@@ -111,9 +111,9 @@ Executes a forward migration to a specific version, or to the latest version if
111
111
*`options.repoOptions` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
112
112
*`options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
113
113
*`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.
@@ -128,26 +128,26 @@ Executes backward migration to a specific version.
128
128
**Arguments:**
129
129
130
130
*`path` (string, mandatory) - path to the repo to be reverted
131
-
*`toVersion` (int, mandatory) - version to which the repo should be reverted to.
131
+
*`toVersion` (int, mandatory) - version to which the repo should be reverted to.
132
132
*`options` (object, optional) - options for the reversion
133
133
*`options.ignoreLock` (bool, optional) - if true will not lock the repo when applying migrations. Use with caution.
134
134
*`options.repoOptions` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
135
135
*`options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
136
136
*`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.
137
-
137
+
138
138
### `getLatestMigrationVersion() -> int`
139
139
140
140
Return the version of the latest migration.
141
141
142
142
## CLI
143
143
144
-
The CLI is a NodeJS binary named `jsipfs-repo-migrations`.
144
+
The CLI is a NodeJS binary named `jsipfs-repo-migrations`.
145
145
It has several commands:
146
146
147
147
*`migrate` - performs forward/backward migration to specific or latest version.
148
148
*`status` - check repo for migrations that should be run.
149
149
*`add` - bootstraps new migration.
150
-
150
+
151
151
For further details see the `--help` pages.
152
152
153
153
## Creating a new migration
@@ -161,15 +161,15 @@ Migrations are one of those things that can be extremely painful on users. At th
161
161
162
162
If your migration has several parts, it should be fail-proof enough that if one part of migration fails the previous changes
163
163
are reverted before propagating the error. If possible then the outcome should be consistent repo so it migration could
164
-
be run again.
164
+
be run again.
165
165
166
166
### Architecture of a migration
167
167
168
168
All migrations are placed in the `/migrations` folder. Each folder there represents one migration that follows the migration
169
169
API.
170
170
171
171
All migrations are collected in `/migrations/index.js`, which should not be edited manually. It is regenerated on
172
-
every run of `jsipfs-migrations add` (manual changes should follow the same style of modifications).
172
+
every run of `jsipfs-migrations add` (manual changes should follow the same style of modifications).
173
173
**The order of migrations is important and migrations must be sorted in ascending order**.
174
174
175
175
Each migration must follow this API. It must export an object in its `index.js` that has following properties:
@@ -186,7 +186,7 @@ _Do not confuse this function with the `require('ipfs-repo-migrations').migrate(
186
186
Arguments:
187
187
*`repoPath` (string) - absolute path to the root of the repo
188
188
*`repoOptions` (object, optional) - object containing `IPFSRepo` options, that should be used to construct a datastore instance.
189
-
189
+
190
190
#### `.revert(repoPath, repoOptions)`
191
191
192
192
_Do not confuse this function with the `require('ipfs-repo-migrations').revert()` function that drives the whole backward migration process!_
@@ -208,17 +208,17 @@ Then add entry in `package.json` to the `browser` field as follow:
208
208
In browser environments then `index.js` will be replaced with `index_browser.js`.
209
209
210
210
Simple migrations should not need to distinguish between
211
-
these environments as the datastore implementation will handle the main differences.
211
+
these environments as the datastore implementation will handle the main differences.
212
212
213
213
There are currently two main datastore implementations:
214
214
1.[`datastore-fs`](https://github.com/ipfs/js-datastore-fs) that is backed by file system and is used mainly in the NodeJS environment
215
-
2.[`datastore-level`](https://github.com/ipfs/js-datastore-level) that is backed by LevelDB and is used mainly in the browser environment
216
-
217
-
Both implementations share the same API and hence are interchangeable.
215
+
2.[`datastore-idb`](https://github.com/ipfs/js-datastore-idb) that is backed by LevelDB and is used mainly in the browser environment
216
+
217
+
Both implementations share the same API and hence are interchangeable.
218
218
219
-
When the migration is run in a browser environment, `datastore-fs` is automatically replaced with `datastore-level` even
220
-
when it is directly imported (`require('datastore-fs')` will return `datastore-level` in a browser).
221
-
So with simple migrations you shouldn't worry about the difference between `datastore-fs` and `datastore-level`
219
+
When the migration is run in a browser environment, `datastore-fs` is automatically replaced with `datastore-idb` even
220
+
when it is directly imported (`require('datastore-fs')` will return `datastore-idb` in a browser).
221
+
So with simple migrations you shouldn't worry about the difference between `datastore-fs` and `datastore-idb`
222
222
and by default use the `datastore-fs` package (as the replace mechanism does not work vice versa).
223
223
224
224
### Guidelines
@@ -229,8 +229,8 @@ The recommended way to write a new migration is to first bootstrap a dummy migra
229
229
> npm run new-migration
230
230
```
231
231
232
-
A new folder is created with the bootstrapped migration. You can then simply fill in the required fields and
233
-
write the rest of the migration!
232
+
A new folder is created with the bootstrapped migration. You can then simply fill in the required fields and
233
+
write the rest of the migration!
234
234
235
235
### Integration with js-ipfs
236
236
@@ -251,7 +251,7 @@ you will have to plug the tests into `browser.js`/`node.js` if they require spec
251
251
252
252
### Empty migrations
253
253
254
-
For interop with go-ipfs it might be necessary just to bump a version of a repo without any actual
254
+
For interop with go-ipfs it might be necessary just to bump a version of a repo without any actual
255
255
modification as there might not be any changes needed in the JS implementation. For that purpose you can create an "empty migration".
256
256
257
257
The easiest way to do so is with the CLI:
@@ -270,7 +270,7 @@ This will create an empty migration with the next version.
270
270
271
271
## Developer
272
272
273
-
### Module versioning notes
273
+
### Module versioning notes
274
274
275
275
In order to have good overview of what version of package contains what kind of migration, to every release there
276
276
should be appended version's metadata in format `migr-<versionOfLatestMigration>`. If for releasing is used `aegir`
0 commit comments