{"id":13341,"library":"ipfs-repo-migrations","title":"IPFS Repository Migrations","description":"ipfs-repo-migrations is a crucial framework for managing schema evolution within the js-ipfs repository structure, enabling users to transition seamlessly as underlying IPFS technologies, algorithms, and data structures are updated. Currently stable at version 15.0.0, this package provides a robust and versioned approach to migrating IPFS repositories to different expected specifications. It defines a clear API for both forward and backward migrations, handles repository locking and unlocking, and offers detailed progress reporting, significantly simplifying the adaptation process. The project maintains a consistent release cadence, frequently aligning with major updates to core IPFS dependencies like `multiformats`, which often introduce breaking changes that necessitate new migration paths. Its key differentiators include broad environment compatibility (supporting both Node.js >=16.0.0 and browser environments via bundlers) and a streamlined process for creating and integrating new migration scripts, drawing inspiration from the `go-ipfs` migration tool.","status":"active","version":"15.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/ipfs/js-ipfs-repo","tags":["javascript","IPFS","libp2p","migrations","typescript"],"install":[{"cmd":"npm install ipfs-repo-migrations","lang":"bash","label":"npm"},{"cmd":"yarn add ipfs-repo-migrations","lang":"bash","label":"yarn"},{"cmd":"pnpm add ipfs-repo-migrations","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for handling CIDs, multicodecs, and other foundational IPFS data structures. Breaking changes in this library often necessitate new repo migrations.","package":"multiformats","optional":false},{"reason":"Dependencies related to InterPlanetary Linked Data (IPLD) components, which define how data is structured and linked within the IPFS ecosystem. Changes here can affect repo structure.","package":"@ipld/*","optional":false}],"imports":[{"note":"This package is primarily designed for ESM consumption, targeting Node.js >=16.0.0. While bundlers can resolve CJS environments, direct `require()` calls in Node.js may lead to incompatibility issues.","wrong":"const migrations = require('ipfs-repo-migrations')","symbol":"default","correct":"import migrations from 'ipfs-repo-migrations'"},{"note":"For TypeScript projects, import the `Migrations` interface to accurately type the default exported `migrations` object, providing full API autocompletion and type safety.","symbol":"Migrations","correct":"import type { Migrations } from 'ipfs-repo-migrations'"},{"note":"The `migrate` function is a method of the default exported `migrations` object, not a named export from the module itself. Access it via the imported `migrations` object.","wrong":"import { migrate } from 'ipfs-repo-migrations'","symbol":"migrate","correct":"import migrations from 'ipfs-repo-migrations'; await migrations.migrate(...)"}],"quickstart":{"code":"import migrations from 'ipfs-repo-migrations';\nimport { MemoryDatastore } from 'datastore-core/memory';\nimport { FsDatastore } from 'datastore-fs'; // Requires 'datastore-fs' package for Node.js\n\nasync function runRepoMigration() {\n  const repoPath = './my-ipfs-repo'; // Define your IPFS repository path\n  // Choose an appropriate datastore implementation based on your environment.\n  // FsDatastore is common for Node.js, MemoryDatastore for testing or browsers.\n  const datastore = process.env.NODE_ENV === 'test'\n    ? new MemoryDatastore() \n    : new FsDatastore(repoPath); // Ensure 'datastore-fs' is installed for Node.js\n\n  const repoOptions = {\n    path: repoPath, // The path to the repository, often used by the datastore\n    datastore: datastore, // The underlying storage backend for the repository\n    root: datastore // The root datastore instance for the IPFS repository\n  };\n\n  try {\n    // In a real application, you would read the current version from the repo config.\n    const currentRepoVersion = 7; \n    const latestVersion = migrations.getLatestMigrationVersion();\n\n    console.log(`Current repository version: ${currentRepoVersion}`);\n    console.log(`Latest available migration version: ${latestVersion}`);\n\n    if (currentRepoVersion < latestVersion) {\n      console.log('Outdated repository detected! Initiating migration...');\n      await migrations.migrate(repoPath, repoOptions, latestVersion, {\n        ignoreLock: false, // Set to true with caution; generally, allow locking to prevent corruption\n        onProgress: (version: number, percent: number, message: string) => {\n          console.log(`Migration [v${version}]: ${message} (${percent.toFixed(2)}%)`);\n        },\n        isDryRun: false // Set to true to simulate the migration without applying changes\n      });\n      console.log(`Repository successfully migrated to version ${latestVersion}.`);\n    } else {\n      console.log('Repository is already up-to-date or newer. No migration needed.');\n    }\n  } catch (error) {\n    console.error('An error occurred during migration:', error);\n    // Implement error handling, potentially logging details or attempting a rollback\n  } finally {\n    // Ensure that any open datastore connections are properly closed.\n    if (datastore.close) {\n      await datastore.close();\n    }\n  }\n}\n\nrunRepoMigration();","lang":"typescript","description":"This quickstart demonstrates how to use `ipfs-repo-migrations` to check the current repository version and perform a migration to the latest available version using a mock datastore."},"warnings":[{"fix":"Ensure your project's `multiformats` dependency is updated to `v11.x.x` or compatible versions. Review `multiformats` changelog for specific API changes if direct usage exists.","message":"Version 15.0.0 (and related ipfs-repo v17.0.0) introduced a breaking change by updating the `multiformats` dependency to `v11.x.x`. This may require downstream applications to update their `multiformats` usage.","severity":"breaking","affected_versions":">=15.0.0"},{"fix":"Upgrade `multiformats` to `v10.x.x` and review `@ipld/*` package versions. Re-encode or re-validate CIDs if your application interacts directly with their internal structure.","message":"Version 14.0.0 (and related ipfs-repo v16.0.0) included a breaking change updating `multiformats` to `v10.x.x` and all `@ipld/*` dependencies. This could impact CID handling and data serialization.","severity":"breaking","affected_versions":">=14.0.0 <15.0.0"},{"fix":"Upgrade your Node.js environment to version 16.0.0 or newer. Use `nvm` or a similar tool to manage Node.js versions.","message":"This package requires Node.js version 16.0.0 or higher. Running in older Node.js environments may lead to compatibility issues or unexpected errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always back up your IPFS repository before running any migration. Consider using the `isDryRun: true` option to test the migration process without committing changes first.","message":"Migrations for `js-ipfs-repo` often involve significant data transformations. Performing migrations on a live or actively used repository without proper backups can lead to data loss or corruption.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure no other IPFS processes are running that might be accessing the repository. If you are certain no other process is active, you can try passing `{ ignoreLock: true }` to the migration function, but exercise extreme caution as this can lead to data corruption if another process is indeed active.","cause":"The IPFS repository is currently in use by another IPFS daemon or application, which has placed a lock file to prevent concurrent access and potential data corruption.","error":"Error: The repo is locked, likely because it is open in another process!"},{"fix":"Ensure you are using the correct ESM import syntax: `import migrations from 'ipfs-repo-migrations'`. If using CommonJS, ensure your bundler correctly handles the import or consider restructuring to use ESM.","cause":"This usually indicates that the `ipfs-repo-migrations` module was imported incorrectly, or the imported `migrations` object is not the expected API object.","error":"TypeError: Cannot read properties of undefined (reading 'migrate')"},{"fix":"Convert your project or relevant files to use ES Modules with `import` statements. Alternatively, if staying with CommonJS, ensure your `package.json` specifies `\"type\": \"module\"` for relevant files or use a transpiler like Babel.","cause":"Attempting to `require()` an ES Module (ESM) in a CommonJS context without proper configuration or transpilation. `ipfs-repo-migrations` is primarily an ESM package.","error":"ERR_REQUIRE_ESM: require() of ES Module .../node_modules/ipfs-repo-migrations/dist/index.js from ... not supported."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}