Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tepinly/mongogrator
A MongoDB migration CLI tool for Typescript & Javascript
https://github.com/tepinly/mongogrator
bun database executable hacktoberfest migration mongodb nodejs nosql
Last synced: 7 days ago
JSON representation
A MongoDB migration CLI tool for Typescript & Javascript
- Host: GitHub
- URL: https://github.com/tepinly/mongogrator
- Owner: tepinly
- License: mit
- Created: 2024-09-14T19:07:48.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2024-10-29T07:45:43.000Z (8 days ago)
- Last Synced: 2024-10-29T08:29:46.531Z (8 days ago)
- Topics: bun, database, executable, hacktoberfest, migration, mongodb, nodejs, nosql
- Language: TypeScript
- Homepage:
- Size: 78.1 KB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Mongogrator is a very fast database migration CLI for MongoDB. Its purpose is to easily create and run migrations for development and production stages
## Installing
Using the following command, it will automatically download, install and add Mongogrator to `PATH`
### MacOS/Linux
```bash
curl -fsSL git.new/mongogrator-installer.sh | bash
```
### Windows
```powershell
cmd /c "curl -L https://git.new/mongogrator-installer.ps1 | powershell -c -"
```
## List of commands
```sh
Mongogrator CLI
Usage: mongogrator [options]
Commands:
init [--js] Initialize a new configuration file
add Creates a new migration file with the provided name
list List all migrations and their status
migrate [config_path] Run all migrations that have not been applied yet
version, -v, --version Prints the current version of Mongogrator
Flags:
--help, -h Prints the detailed description of the command
```
## Usage guide
A basic guide on how to use the CLI
### Adding new migrations
Start by initializing the config file
```sh
mongogrator init
```
This initializes a `mongogrator.config.ts` file in the location of the command. You can optionally pass a `--js` flag at the end of the command to initialize in a js file
Setup the `url` to the desired mongo cluster, and make sure it's running
```sh
mongogrator add insert_user
```
This will create the migration file under the directory key assigned in the config `migrationsPath`
The following is an example of a newly created ts migration file
```ts
import type { Db } from 'mongodb'
/**
* This function is called when the migration is run.
* @param _db The mongodb database object that's passed to the migration
*/
export const migrate = async (_db: Db): Promise => {
// Migration code here
}
```
The migrations are executed through the native MongoDB Node.js driver
### Migration query example
```ts
import type { Db } from 'mongodb'
/**
* This function is called when the migration is run.
* @param _db The mongodb database object that's passed to the migration
*/
export const migrate = async (_db: Db): Promise => {
// Migration code here
_db.collection('users').insertOne({ name: 'Alex' })
}
```
### Migrations list
You can add as many migrations as you want and then call the `list` command to display the status of each
```sh
mongogrator list
```
This will print out a list of all the migrations, each has a status of either `NOT MIGRATED` or `MIGRATED`
```sh
┌───┬───────────────────────────────┬──────────────┐
│ │ migration │ status │
├───┼───────────────────────────────┼──────────────┤
│ 0 │ 20240923150201806_insert_user │ NOT MIGRATED │
└───┴───────────────────────────────┴──────────────┘
```
Naturally, the status will be `NOT MIGRATED` as we haven't run the migration yet
### Running the migrations
Run the migrations simply by calling
```sh
mongogrator migrate
```
This will run all the migrations and log them to the database under the specified collection name in the config `logsCollectionName`
For production purposes, you can pass the config path to the `migrate` command directly if it's not accessible under the same path
```sh
mongogrator migrate /dist
```
Now if you run the `list` command again, it will reveal that the migration file has been successfully executed
```sh
┌───┬───────────────────────────────┬──────────────┐
│ │ migration │ status │
├───┼───────────────────────────────┼──────────────┤
│ 0 │ 20240923150201806_insert_user │ MIGRATED │
└───┴───────────────────────────────┴──────────────┘
```
### Logs collection schema
```ts
{
_id: objectId(),
name: string,
createdAt: Date(),
}
```
## Configuration
```ts
{
url: 'mongodb://localhost:27017', // Cluster url
database: 'test', // Database name for which the migrations will be executed
migrationsPath: './migrations', // Migrations directory relative to the location of the commands
logsCollectionName: 'migrations', // Name of the logs collection that will be stored in the database
format: 'ts', // Format type of the migration files ['ts', 'js']
}
```
> [!IMPORTANT]
> all the config keys with path values are relative to the location of the config file itself