{"id":13551396,"url":"https://github.com/ipfs/fs-repo-migrations","last_synced_at":"2025-04-04T17:10:37.545Z","repository":{"id":30192954,"uuid":"33743748","full_name":"ipfs/fs-repo-migrations","owner":"ipfs","description":"Migrations for the filesystem repository of ipfs clients","archived":false,"fork":false,"pushed_at":"2024-08-23T14:25:31.000Z","size":38611,"stargazers_count":58,"open_issues_count":21,"forks_count":42,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-28T16:11:09.734Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-10T18:19:33.000Z","updated_at":"2024-11-14T13:29:09.000Z","dependencies_parsed_at":"2023-01-14T16:45:37.441Z","dependency_job_id":"a497e134-43ff-4fd7-85a9-d0fb06bf226b","html_url":"https://github.com/ipfs/fs-repo-migrations","commit_stats":{"total_commits":291,"total_committers":28,"mean_commits":"10.392857142857142","dds":0.859106529209622,"last_synced_commit":"fdedf2129802ed5ce882a39eba56cbf78efff875"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Ffs-repo-migrations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Ffs-repo-migrations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Ffs-repo-migrations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Ffs-repo-migrations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs","download_url":"https://codeload.github.com/ipfs/fs-repo-migrations/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217222,"owners_count":20903009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:01:47.287Z","updated_at":"2025-04-04T17:10:37.525Z","avatar_url":"https://github.com/ipfs.png","language":"Go","funding_links":[],"categories":["Go","others"],"sub_categories":[],"readme":"# fs-repo-migrations\n\n[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai)\n[![](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech/)\n[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)\n\n\u003e Migrations for the filesystem repository of Kubo IPFS nodes\n\nThese are migrations for the filesystem repository of [Kubo](https://github.com/ipfs/kubo) IPFS nodes. Each migration builds a separate binary that converts a repository to the next version.  The `fs-repo-migrations` is a tool that downloads individual migrations from the ipfs distribution site and applies them in sequence to migrate the ipfs repository to the target version.  This tool is written in Go, and developed alongside [kubo](https://github.com/ipfs/kubo).\n\n## Table of Contents\n\n- [Install](#install)\n- [Usage](#usage)\n  - [When should I migrate](#when-should-i-migrate)\n  - [How to Run Migrations](#how-to-run-migrations)\n  - [Developing Migrations](#developing-migrations)\n- [Migration with Plugins](#migration-with-plugins)\n- [Contribute](#contribute)\n  - [Want to hack on IPFS?](#want-to-hack-on-ipfs)\n- [License](#license)\n\n## Install\n\n```sh\nmake install\n```\n\n## Usage\n\n### When should I migrate\n\nWhen you want to upgrade Kubo to a new version, you may need to migrate.\n\nHere is the table showing which repo version corresponds to which Kubo version:\n\n| ipfs repo version | Kubo versions    |\n| ----------------: | :--------------- |\n|                 1 | 0.0.0 - 0.2.3.   |\n|                 2 | 0.3.0 - 0.3.11   |\n|                 3 | 0.4.0 - 0.4.2    |\n|                 4 | 0.4.3 - 0.4.5    |\n|                 5 | 0.4.6 - 0.4.10   |\n|                 6 | 0.4.11 - 0.4.15  |\n|                 7 | 0.4.16 - 0.4.23  |\n|                 8 | 0.5.0 - 0.6.0    |\n|                 9 | 0.5.0 - 0.6.0    |\n|                10 | 0.6.0 - 0.7.0    |\n|                11 | 0.8.0 - 0.11.0   |\n|                12 | 0.12.0 - 0.17.0  |\n|                13 | 0.18.0 - 0.20.0  |\n|                14 | 0.21.0 - 0.22.0  |\n|                15 | 0.23.0 - 0.29.0  |\n|                16 | 0.30.0 - current |\n\n### How to Run Migrations\n\nPlease see the [migration run guide here](run.md).\n\n### Developing Migrations\n\nMigrations are one of those things that can be extremely painful on users. At the end of the day, we want users never to have to think about it. The process should be:\n\n- SAFE. No data lost. Ever.\n- Revertible. Tools must implement forward and backward migrations.\n- Frozen. After the tool is written, all code must be frozen and vendored.\n- To Spec. The tools must conform to the spec.\n\n#### Build and Test\n\nTo create a new migration, create a go module in a directory named `fs-repo-X-to-Y`, where `X` is the repo \"from\" version and `Y` the repo \"to\" version.  Vendor the module's dependencies. The build tooling will find this module and build the migration binary.\n\nIf the migration directory contains a subdirectory named `sharness`, tests contained in it are run using the sharness test tool. Tests must be named `tNNNN-*.sh`, where NNNN is a 4-digit sequence number.\n\nAfter the migration is merged into the main repo branch, create a version tag for it.  This is necessary for versioning individual migrations within the repo.\n```sh\ngit tag \u003cmigration\u003e/v\u003cversion\u003e\ngit push origin \u003cmigration\u003e/v\u003cversion\u003e\n```\n\nExample:\n```sh\ngit tag fs-repo-99-to-100/v1.0.1\ngit push origin fs-repo-99-to-100/v1.0.1\n```\n\n#### Ignoring legacy migrations\n\nWe \"archive\" legacy migrations by adding them to `ignored-migrations` file.\nThis keeps CI fast, and removes issues caused by old, with unsupported go code.\n\n### Dependencies\n\nDependencies must be vendored independently for each migration. Each migration is a separate go module with its own `vendor` directory (created with `go mod vendor` for that migration).  All migrations are built using `go build -mod=vendor` to ensure dependencies come from the module's `vendor` directory.\n\n## Migration with Plugins\nIf IPFS plugins were used to operate your IPFS datastore, such as the [ipfs-ds-s3](https://github.com/ipfs/go-ds-s3) plugin, then migration may require building a custom migration with the plugin built into it.  There is a script to assist with the process: `build-plugin.sh`.\n\n### Build a Migration with a Plugin\nThis requires that you have Go installed.\n\nFirst clone the `fs-repo-migrations` github repo:\n```sh\ngit clone https://github.com/ipfs/fs-repo-migrations.git\n```\n\nThen run the `build-plugin.sh` script, supplying the necessary arguments (run with -h for help).\n\n### Run the Custom Migration\nAfter the custom migration with plugin(s) has built successfully, change to the migration directory and run the migration binary.  You can also copy the migration binary into your `PATH` if you want it to be run by `ipfs-update` or by the `fs-repo-migrations` tool.\n\n## Contribute\n\nFeel free to join in. All welcome. Open an [issue](https://github.com/ipfs/fs-repo-migrations/issues)!\n\nThis repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).\n\n### Want to hack on IPFS?\n\n[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Ffs-repo-migrations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs%2Ffs-repo-migrations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Ffs-repo-migrations/lists"}