{"_id":"@a.svetlitskiy/migrate-ydb","name":"@a.svetlitskiy/migrate-ydb","dist-tags":{"latest":"0.1.3-dev-01"},"versions":{"0.1.3-dev-01":{"name":"@a.svetlitskiy/migrate-ydb","version":"0.1.3-dev-01","description":"A database migration tool for YDB in Node","main":"build/lib/migrate-ydb.js","bin":{"migrate-ydb":"build/migrate-ydb.js"},"scripts":{"test":"nyc --reporter=html --reporter=text env TS_NODE_COMPILER_OPTIONS='{\"module\": \"commonjs\" }' mocha -r ts-node/register 'test/**/*.ts'","build":"rm -rf build && tsc","watch":"tsc -w","clean":"rm -rf build","lint":"eslint --ext .js,.ts --ignore-path .gitignore .","prepublish":"npm run clean && npm run build"},"author":{"name":"leshiple"},"license":"MIT","keywords":["migrate ydb migrations database"],"repository":{"type":"git","url":"git+https://github.com/leshiple/migrate-ydb.git"},"engines":{"node":">=8"},"preferGlobal":true,"dependencies":{"cli-table3":"^0.6.0","commander":"^7.1.0","date-fns":"^2.19.0","fs-extra":"^9.1.0","lodash":"^4.17.21","p-each-series":"^2.2.0","typescript":"^4.2.3","ydb-sdk":"^4.5.0"},"devDependencies":{"@types/chai":"^4.2.16","@types/fs-extra":"^9.0.10","@types/lodash":"^4.14.168","@types/mocha":"^8.2.2","@types/sinon":"^9.0.11","@typescript-eslint/eslint-plugin":"^4.21.0","@typescript-eslint/parser":"^4.21.0","chai":"^4.3.4","coveralls":"^3.1.0","eslint":"^7.23.0","eslint-config-airbnb-base":"^14.2.1","eslint-config-prettier":"^8.1.0","eslint-plugin-import":"^2.22.1","eslint-plugin-mocha":"^8.0.0","mocha":"^8.3.2","nyc":"^15.1.0","proxyquire":"^2.1.3","sinon":"^9.2.4","ts-mock-imports":"^1.3.3","ts-node":"^9.1.1"},"gitHead":"fc656e32157500698cbd8cdbd9fd7e923d19774e","bugs":{"url":"https://github.com/leshiple/migrate-ydb/issues"},"homepage":"https://github.com/leshiple/migrate-ydb#readme","_id":"@a.svetlitskiy/migrate-ydb@0.1.3-dev-01","_nodeVersion":"14.17.3","_npmVersion":"6.14.13","dist":{"integrity":"sha512-nkIqPlONIO+VsUoaQTp5URXtRj2pttr2XBm623EUosmHY7azL2uyctiiJzG3WmvkootxBpGvtJQBjlWsIxC3Sg==","shasum":"0fc079cebf7eb87927cc6cd6bfd56e1af38aa059","tarball":"https://registry.npmjs.org/@a.svetlitskiy/migrate-ydb/-/migrate-ydb-0.1.3-dev-01.tgz","fileCount":52,"unpackedSize":110614,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFmjZWcL26UkWmBcvPZ13D8ddwDyK2PVoW+Olhzg598jAiBAPjnE6lfrjUEHRSq8MqVPQ56Wvup8wXGD0A01uBMGUg=="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJkSCLSACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmoaXg//eIqrxVr+bbZRf3nXxov5VnOiy/bbBMHSWZmm4uPvJTbUd3QQ\r\nPKpS6AL+T40mSWK79WB3ZhGPimQiisARdeVwIpFJ56Csf1Kq5LIi59oxAkFK\r\njnzv8fvpmVE2wOfzpkH42eOWCvGpqUld5YvYo4UtmjrMH1tb3iFw2vnDLaCB\r\nrF1MVJjz2I6kuK6p+OQvTrOgV/r1QM3g/Gxi/vvGfUcqWie9PTPf4wA/MPEI\r\nVJy9yaqMVdXnVyePQGFX6YmHvlkTio2MG46mqZI0gDOPhU4pmWO+x4OF8IhY\r\ni5C1kJyglfJ+gTOKj8Kxqw4tJnsyURiKCSPWEcOue4devQDOJwuCle59zpfQ\r\n+NYiDH6bDBv6Qycm7SUMFdRTlw81dWn6zd2fh/ULOUbj2PAsMxF7n9IXi5Q1\r\n7ZVJ9p4XFpt5l3AAZ4gZWMFdrD575G+j/N6DyhdFd7cOUfdvvP0/87tH1nsp\r\nMbGEQdHL1mKzMIdSPrrx8xjRK9ydnM0Boz3a3c1VX+j2C/Q3UGka3Y7yEM4m\r\nusUD0VEHtN+O7aVXj41lT93WCohA6DqUquyl6C1wD5H3vM5XaxWXtt5si/RM\r\n+0h2lbj8gP5X5DXMGB66+QZbO95hD4qoF3OZxJTwP4WfPfAj1jcFoejsXA/j\r\n7urkNDdbuzNf4xks6zI9Z7VKjE1B+xG0tl0=\r\n=QlZX\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"a.svetlitskiy","email":"a.svetlitskiy@gmail.com"},"directories":{},"maintainers":[{"name":"a.svetlitskiy","email":"a.svetlitskiy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/migrate-ydb_0.1.3-dev-01_1682449105984_0.9824218262186917"},"_hasShrinkwrap":false}},"time":{"created":"2023-04-25T18:58:25.922Z","0.1.3-dev-01":"2023-04-25T18:58:26.149Z","modified":"2023-04-25T18:58:26.394Z"},"maintainers":[{"name":"a.svetlitskiy","email":"a.svetlitskiy@gmail.com"}],"description":"A database migration tool for YDB in Node","homepage":"https://github.com/leshiple/migrate-ydb#readme","keywords":["migrate ydb migrations database"],"repository":{"type":"git","url":"git+https://github.com/leshiple/migrate-ydb.git"},"author":{"name":"leshiple"},"bugs":{"url":"https://github.com/leshiple/migrate-ydb/issues"},"license":"MIT","readme":"migrate-ydb is a database migration tool for [Yandex Database](https://cloud.yandex.ru/services/ydb) running in Node.js\n    \n## Installation\n````bash\n$ npm install -g migrate-ydb\n````\n\n## CLI Usage\n````\n$ migrate-ydb\nUsage: migrate-ydb [options] [command]\n\n\n  Commands:\n\n    init                  initialize a new migration project\n    create [description]  create a new database migration with the provided description\n    up [options]          run all unapplied database migrations\n    down [options]        undo the last applied database migration\n    status [options]      print the changelog of the database\n\n  Options:\n\n    -h, --help     output usage information\n    -V, --version  output the version number\n````\n\n## Basic Usage\n### Initialize a new project\nMake sure you have [Node.js](https://nodejs.org/en/) 10 (or higher) installed.  \n\nCreate a directory where you want to store your migrations for your ydb database (eg. 'albums' here) and cd into it\n````bash\n$ mkdir albums-migrations\n$ cd albums-migrations\n````\n\nInitialize a new migrate-ydb project\n````bash\n$ migrate-ydb init\nInitialization successful. Please edit the generated migrate-ydb-config.js file\n````\n\nThe above command did two things: \n1. create a sample 'migrate-ydb-config.js' file and \n2. create a 'migrations' directory\n\nEdit the migrate-ydb-config.js file. An object or promise can be returned. \n````javascript\n// In this file you can configure migrate-ydb\n\n// Choose one\n// process.env.YDB_TOKEN = \"xxxxxxxxxxxxxx\";\n// yc iam create-token\n//\n// process.env.SA_JSON_FILE = 'key.json';\n// yc iam key create --service-account-name $sa_name --output ./key.json\n\nconst config = {\n  ydb: {\n    entryPoint: 'grpcs://ydb.serverless.yandexcloud.net:2135',\n    dbName: '/ru-central1/xxxxxxxxxxxxxxxxxxxxxxx',\n\n    options: {\n      connectTimeoutMS: 10000, // connection timeout\n    },\n  },\n\n  // The migrations dir, can be an relative or absolute path. Only edit this when really necessary.\n  migrationsDir: 'migrations',\n\n  // The ydb table where the applied changes are stored. Only edit this when really necessary.\n  migrationsTable: 'migrations',\n\n  // The file extension to create migrations and search for in migration dir\n  migrationFileExtension: '.js',\n};\n\n// Return the config as a promise\nmodule.exports = config;\n\n````\n\n### Creating a new migration script\nTo create a new database migration script, just run the ````migrate-ydb create [description]```` command.\n\nFor example:\n````bash\n$ migrate-ydb create cats\nCreated: migrations/2016_06_08_15-59-48-cats.js\n````\n\nA new migration file is created in the 'migrations' directory:\n````javascript\nmodule.exports = {\n  up(driver) {\n    // TODO write your migration here. Return a Promise (and/or use async & await).\n  },\n\n  down(driver) {\n    // TODO write the statements to rollback your migration (if possible)\n  }\n};\n````\n\nEdit this content so it actually performs changes to your database. Don't forget to write the down part as well.\n\n#### Example:\n\n````javascript\nmodule.exports = {\n  async up(driver) {\n    await driver.tableClient.withSession(async (session) => {\n      await session.createTable(\n        'cats',\n        new TableDescription()\n          .withColumn(new Column(\n              'id',\n              Ydb.Type.create({optionalType: {item: {typeId: Ydb.Type.PrimitiveTypeId.UINT64}}})\n          ))\n          .withColumn(new Column(\n              'name',\n              Ydb.Type.create({optionalType: {item: {typeId: Ydb.Type.PrimitiveTypeId.UTF8}}})\n          ))\n      );\n    });\n  },\n\n  async down(driver) {\n    await driver.tableClient.withSession(async (session) => {\n      await session.dropTable('cats');\n    });\n  },\n};\n````\nMore examples [here](https://github.com/yandex-cloud/ydb-nodejs-sdk/tree/master/examples).\n\n#### Overriding the sample migration\nTo override the content of the sample migration that will be created by the `create` command, \ncreate a file **`sample-migration.js`** in the migrations directory.\n\n### Checking the status of the migrations\nAt any time, you can check which migrations are applied (or not)\n\n````bash\n$ migrate-ydb status\n┌────────────────────────────┬────────────────────────────────┬──────────────────────────┐\n│ Filename                   │ Hash                           │ Applied At               │\n├────────────────────────────┼────────────────────────────────┼──────────────────────────┤\n│ 2016_06_08_15-59-48-cats.js│ 7625a0220d552dbeb42e26fdab61d8 │ PENDING                  │\n└────────────────────────────┴────────────────────────────────┴──────────────────────────┘\n\n````\n`Hash` - sha256 file hash\n\nEnabled tracking a hash of the file contents and will run a file with the same name again as long as the file contents have changes. Each script needs to be written in a manner where it can be re-run safefly.  A script of the same name and hash will not be executed again, only if the hash changes.\n\n\n### Migrate up\nThis command will apply all pending migrations\n````bash\n$ migrate-ydb up\nMIGRATED UP: 2016_06_08_15-59-48-cats.js\n````\n\nIf an an error occurred, it will stop and won't continue with the rest of the pending migrations\n\nIf we check the status again, we can see the last migration was successfully applied:\n````bash\n$ migrate-ydb status\n┌────────────────────────────┬────────────────────────────────┬──────────────────────────┐\n│ Filename                   │ Hash                           │ Applied At               │\n├────────────────────────────┼────────────────────────────────┼──────────────────────────┤\n│ 2016_06_08_15-59-48-cats.js│ 7625a0220d552dbeb42e26fdab61d8 │ 2016_06_08_18-19-18      │\n└────────────────────────────┴────────────────────────────────┴──────────────────────────┘\n\n````\n\n### Migrate down\nWith this command, migrate-ydb will revert the applied migration\n\n#### Rollback the last applied migration\n````bash\n$ migrate-ydb down\nMIGRATED DOWN: 2016_06_08_15-59-48-cats.js\n````\n\nIf we check the status again, we see that the reverted migration is pending again:\n````bash\n$ migrate-ydb status\n┌────────────────────────────┬────────────────────────────────┬──────────────────────────┐\n│ Filename                   │ Hash                           │ Applied At               │\n├────────────────────────────┼────────────────────────────────┼──────────────────────────┤\n│ 2016_06_08_15-59-48-cats.js│ 7625a0220d552dbeb42e26fdab61d8 │ PENDING                  │\n└────────────────────────────┴────────────────────────────────┴──────────────────────────┘\n````\n\n#### Rollback the all applied migration\n````bash\n$ migrate-ydb down --step=all\nMIGRATED DOWN: 2016_06_08_15-59-48-cats.js\nMIGRATED DOWN: 2016_06_08_16-59-48-dogs.js\nMIGRATED DOWN: 2016_06_08_17-59-48-mouses.js\n````\n\nIf we check the status again, we see that the reverted migration is pending again:\n````bash\n$ migrate-ydb status\n┌──────────────────────────────┬────────────────────────────────┬─────────────────────┐\n│ Filename                     │ Hash                           │ Applied At          │\n├──────────────────────────────┼────────────────────────────────┼─────────────────────┤\n│ 2016_06_08_15-59-48-cats.js  │ 7625a0220d552dbeb42e26fdab61d8 │ 2016_06_08_20-13-30 │\n├──────────────────────────────┼────────────────────────────────┼─────────────────────┤\n│ 2016_06_08_16-59-48-dogs.js  │ 2625bfn506hjxb2kjhk345zxfg8973 │ PENDING             │\n├──────────────────────────────┼────────────────────────────────┼─────────────────────┤\n│ 2016_06_08_17-59-48-mouses.js│ 681jhx87zvl57bskjhyksdf7cbkjrg │ PENDING             │\n└──────────────────────────────┴────────────────────────────────┴─────────────────────┘\n\n````\n\n#### Rollback the last two applied migration\n````bash\n$ migrate-ydb down --step=a2\nMIGRATED DOWN: 2016_06_08_16-59-48-dogs.js\nMIGRATED DOWN: 2016_06_08_17-59-48-mouses.js\n````\n\nIf we check the status again, we see that the reverted migration is pending again:\n````bash\n$ migrate-ydb status\n┌──────────────────────────────┬────────────────────────────────┬──────────────────────────┐\n│ Filename                     │ Hash                           │ Applied At               │\n├──────────────────────────────┼────────────────────────────────┼──────────────────────────┤\n│ 2016_06_08_15-59-48-cats.js  │ 7625a0220d552dbeb42e26fdab61d8 │ PENDING                  │\n├──────────────────────────────┼────────────────────────────────┼──────────────────────────┤\n│ 2016_06_08_16-59-48-dogs.js  │ 2625bfn506hjxb2kjhk345zxfg8973 │ PENDING                  │\n├──────────────────────────────┼────────────────────────────────┼──────────────────────────┤\n│ 2016_06_08_17-59-48-mouses.js│ 681jhx87zvl57bskjhyksdf7cbkjrg │ PENDING                  │\n└──────────────────────────────┴────────────────────────────────┴──────────────────────────┘\n\n````\n\n````\n$ migrate-ydb down --help\nUsage: migrate-ydb down [options]\n\nundo the applied database migration\n\nOptions:\n  -f --file <file>  use a custom config file\n  -s --step <step>  count migration rollback\n  -h, --help        display help for command\n````\n\n## Advanced Features\n\n### Using a custom config file\nAll actions (except ```init```) accept an optional ````-f```` or ````--file```` option to specify a path to a custom config file.\nBy default, migrate-ydb will look for a ````migrate-ydb-config.js```` config file in of the current directory.\n\n#### Example:\n\n````bash\n$ migrate-ydb status -f '~/configs/albums-migrations.js'\n┌────────────────────────────┬────────────────────────────────┬──────────────────────────┐\n│ Filename                   │ Hash                           │ Applied At               │\n├────────────────────────────┼────────────────────────────────┼──────────────────────────┤\n│ 2016_06_08_15-59-48-cats.js│ 7625a0220d552dbeb42e26fdab61d8 │ PENDING                  │\n└────────────────────────────┴────────────────────────────────┴──────────────────────────┘\n\n````\n\n### Using npm packages in your migration scripts\nYou can use use Node.js modules (or require other modules) in your migration scripts.\nIt's even possible to use npm modules, just provide a `package.json` file in the root of your migration project:\n\n````bash\n$ cd albums-migrations\n$ npm init --yes\n````\n\nNow you have a package.json file, and you can install your favorite npm modules that might help you in your migration scripts.\n\n\n### Version\nTo know which version of migrate-ydb you're running, just pass the `version` option:\n\n````bash\n$ migrate-ydb version\n````\n\n## API Usage\n\n```javascript\nconst {\n  init,\n  create,\n  database,\n  config,\n  up,\n  down,\n  status\n} = require('migrate-ydb');\n```\n\n### `init() → Promise`\n\nInitialize a new migrate-ydb project\n```javascript\nawait init();\n```\n\nThe above command did two things: \n1. create a sample `migrate-ydb-config.js` file and \n2. create a `migrations` directory\n\nEdit the `migrate-ydb-config.js` file.\n\n### `create(description) → Promise<fileName>`\n\nFor example:\n```javascript\nconst fileName = await create('cats');\nconsole.log('Created:', fileName);\n```\n\nA new migration file is created in the `migrations` directory.\n\n### `database.connect() → Promise<{driver}>`\n\nConnect to an ydb using the connection settings from the `migrate-ydb-config.js` file.\n\n```javascript\nconst { driver } = await database.connect();\n```\n\n### `config.read() → Promise<JSON>`\n\nRead connection settings from the `migrate-ydb-config.js` file.\n\n```javascript\nconst ydbConnectionSettings = await config.read();\n```\n\n### `config.set(yourConfigObject)`\n\nTell migrate-ydb NOT to use the `migrate-ydb-config.js` file, but instead use the config object passed as the first argument of this function.\nWhen using this feature, please do this at the very beginning of your program.\n\nExample:\n```javascript\nconst { config, up } = require('../lib/migrate-ydb');\n\nconst myConfig = {\n    ydb: {\n      entryPoint: 'grpcs://ydb.serverless.yandexcloud.net:2135',\n      dbName: '/ru-central1/xxxxxxxxxxxxxxxxxxxxxxx',\n\n      options: {\n        connectTimeoutMS: 10000, // connection timeout\n      },\n    },\n    migrationsDir: \"migrations\",\n    migrationsTable: \"migrations\",\n    migrationFileExtension: \".js\"\n};\n\nconfig.set(myConfig);\n\n// then, use the API as you normally would, eg:\nawait up();\n```\n\n### `up(driver) → Promise<Array<fileName>>`\n\nApply all pending migrations\n\n```javascript\nconst { driver } = await database.connect();\nconst migrated = await up(driver);\nmigrated.forEach(fileName => console.log('Migrated:', fileName));\n```\n\nIf an an error occurred, the promise will reject and won't continue with the rest of the pending migrations.\n\n### `down(driver) → Promise<Array<fileName>>`\n\nRevert (only) the last applied migration\n\n```javascript\nconst { db, client } = await database.connect();\nconst migratedDown = await down(db, client);\nmigratedDown.forEach(fileName => console.log('Migrated Down:', fileName));\n```\n\n### `status(driver) → Promise<Array<{ fileName, fileHash, appliedAt }>>`\n\nCheck which migrations are applied (or not.\n\n```javascript\nconst { driver } = await database.connect();\nconst migrationStatus = await status(driver);\nmigrationStatus.forEach(({ fileName, fileHash, appliedAt }) => console.log(fileName, ':', fileHash, ':', appliedAt));\n```\n\n### `client.close() → Promise`\nClose the database connection\n\n```javascript\nconst { driver } = await database.connect();\nawait driver.destroy();\n```\n","readmeFilename":"README.md"}