@samhammer/migrate-mongo-sag 0.0.5 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -0
- package/dist/migrate-mongo.js +1 -2
- package/package.json +12 -9
package/README.md
CHANGED
|
@@ -1 +1,118 @@
|
|
|
1
1
|
# migrate-mongo-sag
|
|
2
|
+
|
|
3
|
+
migrate-mongo-sag is a database migration tool for MongoDB running in Node.js<br>
|
|
4
|
+
it provides some additional functionality to the original migrate-mongo https://github.com/seppevs/migrate-mongo
|
|
5
|
+
|
|
6
|
+
this tool additionally supports:
|
|
7
|
+
|
|
8
|
+
- execution of migration-scripts for "brand" and "default" (will be merged)
|
|
9
|
+
- new options to set "brand", "env" and "suffix" as environment variables
|
|
10
|
+
- new command "dropDatabase" to delete the configured database
|
|
11
|
+
- load settings from .env files by https://github.com/motdotla/dotenv
|
|
12
|
+
- load vault secrets defined in .env files https://github.com/SamhammerAG/vault-client-sag
|
|
13
|
+
|
|
14
|
+
## Requirements
|
|
15
|
+
|
|
16
|
+
- yarn 4.x
|
|
17
|
+
- node 18.x
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
`$ yarn add @samhammer/migrate-mongo-sag`
|
|
22
|
+
|
|
23
|
+
## CLI Usage
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
$ yarn run migrate-mongo
|
|
27
|
+
Usage: migrate-mongo [options] [command]
|
|
28
|
+
|
|
29
|
+
CLI to migrate mongodb
|
|
30
|
+
|
|
31
|
+
Options:
|
|
32
|
+
-V, --version output the version number
|
|
33
|
+
-e, --env <env> set process.env.Environment
|
|
34
|
+
-b, --brand <brand> set process.env.Brand
|
|
35
|
+
-s, --suffix <suffix> set process.env.Suffix
|
|
36
|
+
-t, --trace set process.env.TRACE to enable trace outputs
|
|
37
|
+
-h, --help display help for command
|
|
38
|
+
|
|
39
|
+
Commands:
|
|
40
|
+
create [options] [description] create a new database migration with the provided description
|
|
41
|
+
up run all pending database migrations
|
|
42
|
+
down undo the last applied database migration
|
|
43
|
+
status print the changelog of the database
|
|
44
|
+
dropDatabase deletes the database
|
|
45
|
+
help [command] display help for command
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Basic Setup
|
|
49
|
+
|
|
50
|
+
- create a ".env" file and ".env.local" (optional) file
|
|
51
|
+
- create a "migrate-mongo.config.js" file
|
|
52
|
+
- create a "migrations" directory
|
|
53
|
+
- create sub-directory "default"
|
|
54
|
+
- create sub-directory per "brand"
|
|
55
|
+
- place a sample-migration.js in "default" and "brand" directories (optional)
|
|
56
|
+
|
|
57
|
+
#### sample .env
|
|
58
|
+
|
|
59
|
+
this should be used to define settings for all environments and secret keys
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
#setup directory name for default migrations (mandatory)
|
|
63
|
+
DefaultMigrations="default"
|
|
64
|
+
|
|
65
|
+
#setup vault secret for user name + password (optional)
|
|
66
|
+
MongoDbOptions__AdminUserName="VaultKey--kv-v2/data/mongodb/Username"
|
|
67
|
+
MongoDbOptions__AdminPassword="VaultKey--kv-v2/data/mongodb/Password"
|
|
68
|
+
|
|
69
|
+
#setup url for mongodb which can then be used in migrate-mongo-config.js (optional)
|
|
70
|
+
MongoDb__Url="mongodb://$MongoDbOptions__AdminUserName:$MongoDbOptions__AdminPassword@$MongoDbOptions__DatabaseHost"
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
#### sample .env.local
|
|
74
|
+
|
|
75
|
+
this should be used to define settings for local development only
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
#setup host for mongodb to be used as placeholder in mongodb url (optional)
|
|
79
|
+
MongoDbOptions__DatabaseHost="localhost:27017"
|
|
80
|
+
|
|
81
|
+
#setup defaults for environment and brand; can still be overwritten by cli with "--env" and "--brand" (optional)
|
|
82
|
+
Environment=dev
|
|
83
|
+
Brand=myBrand
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
#### sample migrate-mongo.config.js
|
|
87
|
+
|
|
88
|
+
with this config we can map settings defined in environment for migrate-mongo<br>
|
|
89
|
+
we can access settings defined in environment variables or .env files by process.env
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
/** @type {import("migrate-mongo").config.Config} */
|
|
93
|
+
module.exports = {
|
|
94
|
+
mongodb: {
|
|
95
|
+
// Change (or review) the url to your MongoDB:
|
|
96
|
+
url: `${process.env.MongoDb__Url}`,
|
|
97
|
+
|
|
98
|
+
// Change this to your database name
|
|
99
|
+
databaseName: "my-database"
|
|
100
|
+
},
|
|
101
|
+
|
|
102
|
+
// The migrations dir, can be an relative or absolute path. Only edit this when really necessary.
|
|
103
|
+
migrationsDir: "migrations",
|
|
104
|
+
|
|
105
|
+
// The mongodb collection where the applied changes are stored. Only edit this when really necessary.
|
|
106
|
+
changelogCollectionName: "migrations",
|
|
107
|
+
|
|
108
|
+
// The file extension to create migrations and search for in migration dir
|
|
109
|
+
migrationFileExtension: ".js",
|
|
110
|
+
|
|
111
|
+
// Enable the algorithm to create a checksum of the file contents and use that in the comparison to determine
|
|
112
|
+
// if the file should be run. Requires that scripts are coded to be run multiple times.
|
|
113
|
+
useFileHash: false,
|
|
114
|
+
|
|
115
|
+
// Change moduleSystem for migration files. Supported values are "commonjs" and "esm".
|
|
116
|
+
moduleSystem: "commonjs"
|
|
117
|
+
};
|
|
118
|
+
```
|
package/dist/migrate-mongo.js
CHANGED
|
@@ -1,3 +1,2 @@
|
|
|
1
1
|
#! /usr/bin/env node
|
|
2
|
-
"use strict";const s=require("migrate-mongo"),
|
|
3
|
-
if the brand is set, the migration will be placed in the brand folder, otherwise in the defaultMigration folder`).option("-d, --default","enforce creation in defaultMigration folder").action(async(e,n)=>{process.env.TRACE&&console.log("run command create...");try{await G(n.default);const o=await s.create(e),t=await s.config.read();console.log(`CREATED: ${t.migrationsDir}${i.sep}${o}`)}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}});r.command("up").description("run all pending database migrations").action(async()=>{process.env.TRACE&&console.log("run command up...");const{db:e,client:n}=await s.database.connect();try{await f(),(await s.up(e,n)).forEach(t=>console.log(`MIGRATED UP: ${t}`))}catch(o){console.error(`ERROR: ${o.message}`,o.stack),o.migrated.forEach(t=>console.log(`MIGRATED UP: ${t}`)),process.exit(1)}finally{await n.close()}});r.command("down").description("undo the last applied database migration").action(async()=>{process.env.TRACE&&console.log("run command down...");const{db:e,client:n}=await s.database.connect();try{await f(),(await s.down(e,n)).forEach(t=>console.log(`MIGRATED DOWN: ${t}`))}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}finally{await n.close()}});r.command("status").description("print the changelog of the database").action(async()=>{process.env.TRACE&&console.log("run command status...");const{db:e,client:n}=await s.database.connect();try{await f(),(await s.status(e)).forEach(t=>console.log(`${t.appliedAt}: ${t.fileName}`))}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}finally{await n.close()}});r.command("dropDatabase").description("deletes the database").action(async()=>{process.env.TRACE&&console.log("run command dropDatabase...");const{db:e,client:n}=await s.database.connect();try{const o=await I(e);console.log("DROPPED DB:",o.databaseName,o.userName)}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}finally{await n.close()}});r.parse();
|
|
2
|
+
"use strict";const s=require("migrate-mongo"),h=require("commander"),p=require("dotenv"),f=require("dotenv-expand"),y=require("@samhammer/vault-client-sag"),d=require("lodash"),b=require("child_process"),i=require("path"),l=require("fs/promises"),m=require("fs"),R="@samhammer/migrate-mongo-sag",D="1.0.0",T={"migrate-mongo":"dist/migrate-mongo.js"},C=["dist/**/*"],A=["mongodb","migration"],$="SamhammerAG",x="MIT",k={build:"vite build","migrate-mongo":"vite build && node dist/migrate-mongo.js",format:"prettier --write --parser typescript ./src",lint:"eslint ./src",test:"vitest run"},q={"@rushstack/eslint-patch":"^1.10.3","@types/lodash":"^4.17.5","@types/migrate-mongo":"^8.2.0","@types/node":"^18.19.34","@typescript-eslint/eslint-plugin":"^7.13.0","@typescript-eslint/parser":"^7.13.0",eslint:"^8.57.0","eslint-config-prettier":"^8.10.0","eslint-plugin-import":"^2.29.1","eslint-plugin-prettier":"^5.1.3",mongodb:"^4.17.2",prettier:"^3.3.2",typescript:"^5.4.5",vite:"^5.2.13",vitest:"^1.6.0"},M={"@samhammer/vault-client-sag":"^1.1.0",commander:"^12.1.0",dotenv:"^16.4.5","dotenv-expand":"^11.0.6",lodash:"^4.17.21","migrate-mongo":"^11.0.0"},B={mongodb:"^4.4.1 || ^5.0.0 || ^6.0.0"},S={node:"18.19.0",yarn:"4.0.2"},N={name:R,version:D,bin:T,files:C,keywords:A,author:$,license:x,scripts:k,devDependencies:q,dependencies:M,peerDependencies:B,volta:S},v=[".env.local",".env"];async function O(e){try{process.env.TRACE&&console.log("int env..."),await P(e),await I(),await F(),await j(),process.env.TRACE&&console.log("finished init env")}catch(n){console.error("init env failed",n)}}function j(){process.env.TRACE&&console.log("loading env files...");const e=p.config({path:v});f.expand({parsed:e.parsed})}async function F(){process.env.TRACE&&console.log("loading vault...");const e=V(v);process.env.TRACE&&console.log("requesting vault keys",e),await(await y.getVault()).loadSecretsToEnv(e),process.env.TRACE&&console.log("finished loading from vault")}function V(e){const n=d.clone(process.env),o=p.config({path:e,processEnv:n}),t=d.pickBy(o.parsed,c=>c.startsWith("VaultKey")),a=f.expand({parsed:t,processEnv:n});return d.invert(a.parsed)}async function P(e){process.env.TRACE&&console.log("loading command options...");const n=e.getOptionValue("env"),o=e.getOptionValue("brand"),t=e.getOptionValue("suffix"),a={};n&&(a.Environment=n),o&&(a.Brand=o),t&&(a.Suffix=t),p.populate(process.env,a,{override:!0}),process.env.TRACE&&console.log("set options",a)}function I(){if(process.env.TRACE&&console.log("loading branch..."),process.env.Branch){process.env.TRACE&&console.log("skip branch cause its defined already",process.env.Branch);return}const n={Branch:b.execSync("git rev-parse --abbrev-ref HEAD").toString("utf-8").replace(/[\n\r\s]+$/,"")};p.populate(process.env,n),process.env.TRACE&&console.log("set branch",n)}async function G(e){const n=process.env.MongoDbOptions__UserName;return n&&await e.removeUser(n),await e.dropDatabase(),{databaseName:e.databaseName,userName:n??""}}async function g(){if(!process.env.DefaultMigrations)throw new Error("enviroment variable DefaultMigrations is required");if(!process.env.Brand)throw new Error("enviroment variable Brand is required");const e=await E(),n=i.join(e,process.env.DefaultMigrations),o=i.join(e,process.env.Brand),t=await K();await u(n,t),await u(o,t),await w(t)}async function U(e){if(e&&!process.env.DefaultMigrations)throw new Error("enviroment variable DefaultMigrations is required");if(!e&&!process.env.Brand)throw new Error("enviroment variable Brand is required");const n=e?process.env.DefaultMigrations:process.env.Brand,o=await E(),t=i.join(o,n);await w(t)}async function K(){const e=await _();return await W(e),e}async function _(){const e=i.join(process.cwd(),".temp");return m.existsSync(e)?process.env.TRACE&&console.log("using tempDir",e):(m.mkdirSync(e),process.env.TRACE&&console.log("created tempDir",e)),e}async function W(e){const n=await l.readdir(e,{withFileTypes:!0});for(const o of n){const t=i.join(e,o.name);process.env.TRACE&&console.log("remove tempFile",t),await l.rm(t)}process.env.TRACE&&console.log("cleaned up tempDir",e)}async function w(e){const n=await s.config.read();n.migrationsDir=e,s.config.set(n),process.env.TRACE&&console.log("configured new migrationDir",e)}async function u(e,n){if(!m.existsSync(e)){process.env.TRACE&&console.log("sourceDir does not exist, skipping",e);return}let o=await l.readdir(e,{withFileTypes:!0});o=o.filter(t=>t.isFile());for(const t of o){const a=`${e}${i.sep}${t.name}`,c=`${n}${i.sep}${t.name}`;process.env.TRACE&&console.log("copy file",a,c),await l.copyFile(a,c)}}async function E(){const n=(await s.config.read()).migrationsDir;return i.isAbsolute(n)?n:i.join(process.cwd(),n)}const r=new h.Command;r.name("migrate-mongo").description("CLI to migrate mongodb").version(N.version).option("-e, --env <env>","set process.env.Environment").option("-b, --brand <brand>","set process.env.Brand").option("-s, --suffix <suffix>","set process.env.Suffix").option("-t, --trace","set process.env.TRACE to enable trace outputs");r.hook("preSubcommand",async e=>{process.env.TRACE=e.getOptionValue("trace")?"on":"",process.env.TRACE&&console.log("hook pre-command..."),await O(e)});r.command("create [description]").description("create a new database migration with the provided description").option("-d, --default","enforce creation in defaultMigration folder").action(async(e,n)=>{process.env.TRACE&&console.log("run command create...");try{await U(n.default);const o=await s.create(e),t=await s.config.read();console.log(`CREATED: ${t.migrationsDir}${i.sep}${o}`)}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}});r.command("up").description("run all pending database migrations").action(async()=>{process.env.TRACE&&console.log("run command up...");const{db:e,client:n}=await s.database.connect();try{await g(),(await s.up(e,n)).forEach(t=>console.log(`MIGRATED UP: ${t}`))}catch(o){console.error(`ERROR: ${o.message}`,o.stack),o.migrated.forEach(t=>console.log(`MIGRATED UP: ${t}`)),process.exit(1)}finally{await n.close()}});r.command("down").description("undo the last applied database migration").action(async()=>{process.env.TRACE&&console.log("run command down...");const{db:e,client:n}=await s.database.connect();try{await g(),(await s.down(e,n)).forEach(t=>console.log(`MIGRATED DOWN: ${t}`))}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}finally{await n.close()}});r.command("status").description("print the changelog of the database").action(async()=>{process.env.TRACE&&console.log("run command status...");const{db:e,client:n}=await s.database.connect();try{await g(),(await s.status(e)).forEach(t=>console.log(`${t.appliedAt}: ${t.fileName}`))}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}finally{await n.close()}});r.command("dropDatabase").description("deletes the database").action(async()=>{process.env.TRACE&&console.log("run command dropDatabase...");const{db:e,client:n}=await s.database.connect();try{const o=await G(e);console.log("DROPPED DB:",o.databaseName,o.userName)}catch(o){console.error(`ERROR: ${o.message}`,o.stack),process.exit(1)}finally{await n.close()}});r.parse();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@samhammer/migrate-mongo-sag",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"bin": {
|
|
5
5
|
"migrate-mongo": "dist/migrate-mongo.js"
|
|
6
6
|
},
|
|
@@ -22,18 +22,19 @@
|
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
24
|
"@rushstack/eslint-patch": "^1.10.3",
|
|
25
|
-
"@types/lodash": "^4",
|
|
25
|
+
"@types/lodash": "^4.17.5",
|
|
26
26
|
"@types/migrate-mongo": "^8.2.0",
|
|
27
|
-
"@types/node": "^18.
|
|
28
|
-
"@typescript-eslint/eslint-plugin": "^7.
|
|
29
|
-
"@typescript-eslint/parser": "^7.
|
|
27
|
+
"@types/node": "^18.19.34",
|
|
28
|
+
"@typescript-eslint/eslint-plugin": "^7.13.0",
|
|
29
|
+
"@typescript-eslint/parser": "^7.13.0",
|
|
30
30
|
"eslint": "^8.57.0",
|
|
31
31
|
"eslint-config-prettier": "^8.10.0",
|
|
32
32
|
"eslint-plugin-import": "^2.29.1",
|
|
33
33
|
"eslint-plugin-prettier": "^5.1.3",
|
|
34
|
-
"
|
|
34
|
+
"mongodb": "^4.17.2",
|
|
35
|
+
"prettier": "^3.3.2",
|
|
35
36
|
"typescript": "^5.4.5",
|
|
36
|
-
"vite": "^5.2.
|
|
37
|
+
"vite": "^5.2.13",
|
|
37
38
|
"vitest": "^1.6.0"
|
|
38
39
|
},
|
|
39
40
|
"dependencies": {
|
|
@@ -42,8 +43,10 @@
|
|
|
42
43
|
"dotenv": "^16.4.5",
|
|
43
44
|
"dotenv-expand": "^11.0.6",
|
|
44
45
|
"lodash": "^4.17.21",
|
|
45
|
-
"migrate-mongo": "^
|
|
46
|
-
|
|
46
|
+
"migrate-mongo": "^11.0.0"
|
|
47
|
+
},
|
|
48
|
+
"peerDependencies": {
|
|
49
|
+
"mongodb": "^4.4.1 || ^5.0.0 || ^6.0.0"
|
|
47
50
|
},
|
|
48
51
|
"volta": {
|
|
49
52
|
"node": "18.19.0",
|