{"id":15678087,"url":"https://github.com/timmikeladze/arango-migrate","last_synced_at":"2025-09-12T13:40:52.069Z","repository":{"id":38213250,"uuid":"437802156","full_name":"TimMikeladze/arango-migrate","owner":"TimMikeladze","description":"🥑 Database migration tools and CLI for ArangoDB. Apply migrations in a transaction-safe manner with optional before/after hooks and dry-run support.","archived":false,"fork":false,"pushed_at":"2025-09-05T16:41:17.000Z","size":475,"stargazers_count":17,"open_issues_count":15,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-05T18:40:22.860Z","etag":null,"topics":["arango","arango-migrate","arangodb","arangodb-migrate","arangodb-migration","database","database-management","javascript","migration","migrations","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/TimMikeladze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"linesofcodedev","custom":["https://www.paypal.me/TimMikeladze"]}},"created_at":"2021-12-13T09:00:11.000Z","updated_at":"2025-04-11T10:02:26.000Z","dependencies_parsed_at":"2023-12-29T15:25:44.425Z","dependency_job_id":"ed64012b-974f-4ae0-a2ff-e63e38618d20","html_url":"https://github.com/TimMikeladze/arango-migrate","commit_stats":{"total_commits":128,"total_committers":4,"mean_commits":32.0,"dds":0.5234375,"last_synced_commit":"a90cdb92c94dc39277077f6e35849aabb3a3c1b7"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/TimMikeladze/arango-migrate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Farango-migrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Farango-migrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Farango-migrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Farango-migrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimMikeladze","download_url":"https://codeload.github.com/TimMikeladze/arango-migrate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Farango-migrate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274822805,"owners_count":25356592,"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","status":"online","status_checked_at":"2025-09-12T02:00:09.324Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["arango","arango-migrate","arangodb","arangodb-migrate","arangodb-migration","database","database-management","javascript","migration","migrations","typescript"],"created_at":"2024-10-03T16:16:23.447Z","updated_at":"2025-09-12T13:40:52.047Z","avatar_url":"https://github.com/TimMikeladze.png","language":"TypeScript","funding_links":["https://ko-fi.com/linesofcodedev","https://www.paypal.me/TimMikeladze"],"categories":[],"sub_categories":[],"readme":"# arango-migrate\n\nApply migrations to an ArangoDB in a transaction-safe manner with optional before/after hooks and dry-run support.\n\n## Getting Started\n\n```console\nyarn add arango-migrate -D\n```\n\n**Note:** Check out a functioning sample in the [arango-migrate-example](https://github.com/TimMikeladze/arango-migrate-example) repository.\n\n## Usage\n\n```\nUsage: cli [options]\n\nOptions:\n  -c, --config \u003cconfig\u003e  path to a js config file. Defaults to ./config.migrate.js\n  -u, --up               run up migrations. Defaults to running all unapplied migrations if no --to parameter is provided\n  -d, --down             run down migrations. --to parameter is required\n  -t, --to \u003cversion\u003e     run migrations to and including a specific version\n  -i --init \u003cname\u003e       initialize a new migration file\n  -l --list              list all applied migrations\n  -dr --dry-run          dry run. Executes migration lifecycle functions but never commits the transaction to the database or writes to the migration history log\n  -nh --no-history       Skips writing to the migration history log. Use this with caution since the applied migrations will not be saved in the migration\n                         history log, opening the possibility of applying the same migration multiple times and potentially dirtying your data\n  -h, --help             display help for command\n```\n\n### Configuration\n\nCreate a `config.migrate.js` file in the root of your project. This file contains the database connection information and options for running migrations.\n\nExample:\n\n```js\nimport 'dotenv/config'\n\nexport default {\n    dbConfig: {\n        databaseName: process.env.ARANGO_NAME,\n        url: process.env.ARANGO_URL,\n            auth: {\n              username: process.env.ARANGO_USERNAME,\n              password: process.env.ARANGO_PASSWORD || ''\n        }\n    },\n    autoCreateNewCollections: true, // defaults to true if not specified\n    migrationHistoryCollection: 'migration_history', // defaults to 'migration_history' if not specified\n    migrationsPath: './migrations'\n}\n```\n\n### Initialize a new migration\n\n`yarn arango-migrate -i new-migration-name`\n\nThis will create an empty migration file in the `migrations` directory.\n\n### Simple migration example\n\nThis migration will create new collections `todo`, `user`, an edge collection `user_todo` and then insert documents in them. Additional lifecycle functions can be added to the migration file, see the full list of options below. If a collection does not exist it will be created by default (set `autoCreateNewCollections` option to `false` to disable this behavior).\n\n\n```javascript\nimport { CollectionType } from 'arangojs'\n\nconst migration = {\n  description: 'Simple migration',\n  async collections () {\n    // All collections used in this migration must be defined here. A string or an options object can be used.\n    return [\n      'todo',\n      'user',\n      {\n        collectionName: 'user_todo_edge',\n        options: {\n          type: CollectionType.EDGE_COLLECTION\n        }\n      }]\n  },\n  async up (db, step) {\n    // Using the `step` function, add a new document to the collection as part of this migration's transaction.\n    await step(async () =\u003e await db.collection('todo').save({\n      _key: '1',\n      name: 'Buy milk'\n    }))\n\n    await step(async () =\u003e await db.collection('user').save({\n      _key: '1',\n      name: 'John Doe'\n    }))\n\n    await step(async () =\u003e await db.collection('user_todo_edge').save({\n      _from: 'user/1',\n      _to: 'todo/1'\n    }))\n  }\n}\n\nexport default migration\n```\n\n### Running up migrations\n\n`yarn arango-migrate -u`\n\nRuns all un-applied migrations.\n\n`yarn arango-migrate -u -t 2`\n\nRuns all un-applied migrations up to and including migration with version number 2.\n\n## Understanding ArangoDB transactions and the step function\n\nIndividual migrations are ran within a transaction in order to keep the database in a valid state if a migration fails. The migration's transaction is committed to ArangoDB after the `up` or `down` functions are executed.\n\nObserve how the second argument of the `up` and `down` functions is a function called `step`. This is a special function which allows you to add valid ArangoDB operations to the transaction.\n\nFor example in order to add a new document to the `todo` collection.\n\n```js\nconst up = async (db, step) =\u003e {\n    const todoItem = await step(async () =\u003e await db.collection('todo').save({\n        _key: '1',\n        name: 'Buy milk'\n    }))\n    return todoItem;\n}\n```\n\n**Read more about transactions in ArangoDB**\n\n- https://github.com/arangodb/arangojs/blob/main/src/transaction.ts#L168\n- https://www.arangodb.com/docs/stable/transactions.html\n\n## Anatomy of a migration\n\n```typescript\nexport interface Migration {\n  /**\n   * Defines all the collections that will be used as part of this migration.\n   * @returns {Promise\u003cCollections\u003e} An array of collection names or an array of collection options.\n   */\n  collections(): Promise\u003cCollections\u003e;\n  /**\n   * Optional function that configures how the transaction will be executed. See ArangoDB documentation for more information.\n   * @returns {Promise\u003cTransactionOptions\u003e} - The transaction options.\n   */\n  transactionOptions?: () =\u003e Promise\u003cTransactionOptions\u003e;\n  /**\n   * Optional description of what the migration does. This value will be stored in the migration log.\n   */\n  description?: string,\n  /**\n   * Optional function that will be called before the migration's `up` function is executed.\n   * @param {Database} db -  Database instance.\n   * @returns {Promise\u003c*\u003e} - Value returned will be passed to the `up` function.\n   */\n  beforeUp?: (db: Database) =\u003e Promise\u003cany\u003e\n  /**\n   * Function that will be called to perform the `up` migration.\n   * @param {Database} - db Database instance.\n   * @param {StepFunction} - step The `step` function is used to add valid ArangoDB operations to the transaction.\n   * @param {*} data Optional value received from the `beforeUp` function.\n   */\n  up: (db: Database, step: StepFunction, data?: any) =\u003e Promise\u003cany\u003e;\n  /**\n   * Optional function that will be called after the migration's `up` function is executed.\n   * @param {Database} db - Database instance.\n   * @param {*} data - Value returned from the `up` function.\n   * @returns {Promise\u003c*\u003e} - Value returned will be passed to the `afterUp` function.\n   */\n  afterUp?: (db: Database, data?: any) =\u003e Promise\u003cvoid\u003e\n  /**\n   * Optional function that will be called before the migration's `down` function is executed.\n   * @param {Database} db - Database instance.\n   * @returns {Promise\u003c*\u003e} - Value returned will be passed to the `down` function.\n   */\n  beforeDown?: (db: Database) =\u003e Promise\u003cany\u003e\n  /**\n   * Function that will be called to perform the `down` migration.\n   * @param {Database} db - Database instance.\n   * @param {StepFunction} - step The `step` function is used to add valid ArangoDB operations to the transaction.\n   * @param {*} data - Optional value received from the `beforeDown` function.\n   */\n  down?: (db: Database, step: StepFunction, data?: any) =\u003e Promise\u003cany\u003e;\n  /**\n   * Optional function that will be called after the migration's `down` function is executed.\n   * @param {Database} db - Database instance.\n   * @param {*} data - Optional value received from the `beforeDown` function.\n   * @returns {Promise\u003c*\u003e} - Value returned will be passed to the `afterDown` function.\n   */\n  afterDown?: (db: Database, data?: any) =\u003e Promise\u003cany\u003e\n}\n```\n\n## Contributing\n\nTo get started with development, clone the repository and install dependencies with your package manager of choice. This project uses `yarn` by default.\n\nThen copy the `.env.template` file to `.env`. The default values should work for most cases.\n\nNow start the ArangoDB docker container by running `docker-compose up -d`.\n\nOnce the container is running make sure everything is working by running `yarn test` and `yarn build`. If both commands succeed you are ready to start contributing to this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimmikeladze%2Farango-migrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimmikeladze%2Farango-migrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimmikeladze%2Farango-migrate/lists"}