{"id":13454856,"url":"https://github.com/pkosiec/mongo-seeding","last_synced_at":"2025-05-15T13:08:30.746Z","repository":{"id":37780664,"uuid":"111328662","full_name":"pkosiec/mongo-seeding","owner":"pkosiec","description":"🌱 The ultimate solution for populating your MongoDB database.","archived":false,"fork":false,"pushed_at":"2025-04-24T18:55:10.000Z","size":5827,"stargazers_count":559,"open_issues_count":5,"forks_count":48,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-06T15:18:43.310Z","etag":null,"topics":["cli","cli-app","command-line-tool","database","database-seeder","database-seeding","db","db-seed","docker","docker-image","hacktoberfest","mongo","mongo-seeding","mongodb","mongodb-database","nodejs","seed","seed-database","seeding","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/pkosiec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2017-11-19T20:16:03.000Z","updated_at":"2025-05-02T20:56:11.000Z","dependencies_parsed_at":"2023-11-12T23:20:37.042Z","dependency_job_id":"68d067e3-c03c-48c7-81f2-c5500222a48a","html_url":"https://github.com/pkosiec/mongo-seeding","commit_stats":{"total_commits":257,"total_committers":8,"mean_commits":32.125,"dds":"0.046692607003890996","last_synced_commit":"7723d6f89a25b52717df159dbeb0c17e21d762f3"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkosiec%2Fmongo-seeding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkosiec%2Fmongo-seeding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkosiec%2Fmongo-seeding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkosiec%2Fmongo-seeding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkosiec","download_url":"https://codeload.github.com/pkosiec/mongo-seeding/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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":["cli","cli-app","command-line-tool","database","database-seeder","database-seeding","db","db-seed","docker","docker-image","hacktoberfest","mongo","mongo-seeding","mongodb","mongodb-database","nodejs","seed","seed-database","seeding","typescript"],"created_at":"2024-07-31T08:00:58.603Z","updated_at":"2025-05-15T13:08:25.719Z","avatar_url":"https://github.com/pkosiec.png","language":"TypeScript","funding_links":[],"categories":["Packages","Repository","TypeScript","包","目录","Database","Tools"],"sub_categories":["Database","数据库","Development"],"readme":"![Mongo Seeding](https://raw.githubusercontent.com/pkosiec/mongo-seeding/main/docs/assets/logo.png)\n\n# Mongo Seeding\n\n[![GitHub release](https://img.shields.io/github/release/pkosiec/mongo-seeding.svg)](https://github.com/pkosiec/mongo-seeding/releases) [![Build Status](https://github.com/pkosiec/mongo-seeding/actions/workflows/branch.yaml/badge.svg)](https://github.com/pkosiec/mongo-seeding/actions) [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)\n\nThe ultimate solution for populating your MongoDB database :rocket:\n\nDefine MongoDB documents in JSON, JavaScript or even TypeScript files. Use JS library, install CLI or run Docker image to import them!\n\n## Introduction\n\nMongo Seeding is a flexible set of tools for importing data into MongoDB database.\n\nIt's great for:\n\n- testing database queries, automatically or manually\n- preparing ready-to-go development environment for your application\n- setting initial state for your application\n\n## How does it work?\n\n1. Define documents for MongoDB import in JSON, JavaScript or TypeScript file(s). To learn, how to do that, read the **[import data definition](./docs/import-data-definition.md)** guide. To see some examples, navigate to the **[`examples`](./examples)** directory.\n\n1. Use one of the Mongo Seeding tools, depending on your needs:\n\n   - [TypeScript/JavaScript library with friendly API](./core)\n   - [Command line interface (CLI)](./cli)\n   - [Docker image](./docker-image)\n\n1. ???\n1. Profit!\n\n## Motivation\n\nThere are many tools for MongoDB data import out there, including the official one - `mongoimport`. Why should you choose Mongo Seeding?\n\n### Problem #1: JSON used for import data definition\n\nEvery tool I found before creating Mongo Seeding support only JSON files. In my opinion, that is not the most convenient way of data definition. The biggest problems are data redundancy and lack of ability to write logic.\n\nImagine that you want to import 10 very similar documents into `authors` collection. Every document is identical - except the name:\n\n```json\n{\n  \"name\": \"{NAME_HERE}\",\n  \"email\": \"example@example.com\",\n  \"avatar\": \"https://placekitten.com/300/300\"\n}\n```\n\nWith every tool I've ever found, you would need to create 5 separate JSON files, or one file with array of objects. Of course, the latter option is better, but anyway you end up with a file looking like this:\n\n```json\n[\n  {\n    \"name\": \"John\",\n    \"email\": \"example@example.com\",\n    \"avatar\": \"https://placekitten.com/300/300\"\n  },\n  {\n    \"name\": \"Joanne\",\n    \"email\": \"example@example.com\",\n    \"avatar\": \"https://placekitten.com/300/300\"\n  },\n  {\n    \"name\": \"Bob\",\n    \"email\": \"example@example.com\",\n    \"avatar\": \"https://placekitten.com/300/300\"\n  },\n  {\n    \"name\": \"Will\",\n    \"email\": \"example@example.com\",\n    \"avatar\": \"https://placekitten.com/300/300\"\n  },\n  {\n    \"name\": \"Chris\",\n    \"email\": \"example@example.com\",\n    \"avatar\": \"https://placekitten.com/300/300\"\n  }\n]\n```\n\nIt doesn't look good - you did probably hear about [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle.\n\nImagine that now you have to change authors' email. You would probably use search and replace. But what if you would need change the data shape completely? This time you can also use IDE features like multiple cursors etc., but hey - it's a waste of time. What if you had a much more complicated data shape?\n\nIf you could use JavaScript to define the authors documents, it would be much easier and faster to write something like this:\n\n```javascript\nconst names = ['John', 'Joanne', 'Bob', 'Will', 'Chris'];\n\nmodule.exports = names.map((name) =\u003e ({\n  name,\n  email: 'example@example.com',\n  avatar: 'https://placekitten.com/300/300',\n}));\n```\n\nObviously, in JavaScript files you can also import other files - external libraries, helper methods etc. It's easy to write some data randomization rules - which are mostly essential for creating development sample data. Consider the following example of `people` collection import:\n\n```javascript\nconst { getObjectId } = require('../../helpers/index');\n\nconst names = ['John', 'Joanne', 'Bob', 'Will', 'Chris'];\n\nconst min = 18;\nconst max = 100;\n\nmodule.exports = names.map((name) =\u003e ({\n  firstName: name,\n  age: Math.floor(Math.random() * (max - min + 1)) + min,\n  _id: getObjectId(name),\n}));\n```\n\nThe difference should be noticeable. This way of defining import data feels just right. And yes, you can do that in Mongo Seeding. But, JSON files are supported as well.\n\n### Problem #2: No data model validation\n\nIn multiple JSON files which contains MongoDB documents definition, it's easy to make a mistake, especially in complex data structure. Sometimes a typo results in invalid data. See the example below for `people` collection definition:\n\n```json\n[\n  {\n    \"name\": \"John\",\n    \"email\": \"john@mail.de\",\n    \"age\": 18\n  },\n  {\n    \"name\": \"Bob\",\n    \"email\": \"bob@example.com\",\n    \"age\": \"none\"\n  }\n]\n```\n\nBecause of a typo, Bob has `email` field empty. Also, there is a non-number value for `age` key.\nThe same problem would exist in JavaScript data definition. But, if you were able to use TypeScript, the situation slightly changes:\n\n```typescript\nexport interface Person {\n  name: string;\n  email: string;\n  age: number;\n}\n```\n\n```typescript\n// import interface defined above\nimport { Person } from '../../models/index';\n\nconst people: Person[] = [\n  {\n    name: 'John',\n    email: 'john@mail.de',\n    age: 18,\n  },\n  {\n    name: 'Bob',\n    emial: 'bob@example.com', // \u003c-- error underlined in IDE\n    age: 'none', //  \u003c-- error underlined in IDE\n  },\n];\n\nexport = people;\n```\n\nIf you used types, you would instantly see that you made mistakes - not only during import, but much earlier, in your IDE.\n\nAt this point some can say: “We had this for years — this is the purpose of mongoose!”. The problem is that importing a bigger amount of data with mongoose is painfully slow — because of the model validation. You can decide to use a faster approach, `Model.collection.insert()`\nmethod, but in this case you disable model validation completely!\n\nAlso, starting from version 3.6, MongoDB supports JSON Schema validation. Even if you are OK with writing validation rules in JSON, you still have to try inserting a document into collection to see if the object is valid. It is too slow and cumbersome, isn’t it? How to solve this problem?\n\nIt’s simple. Use TypeScript. Compile time model validation will be much faster. And IDE plugins (or built-in support like in Visual Studio Code) will ensure that you won’t make any mistake during sample data file modification. Oh, and the last thing: If you have an existing TypeScript application which uses MongoDB, then you can just reuse all models for data import.\n\nThe Mongo Seeding CLI and Mongo Seeding Docker Image have TypeScript runtime built-in. It means that you can take advantage of static type checking in TypeScript data definition files (`.ts` extension).\n\n### Problem #3: No ultimate solution\n\nTools like this should be as flexible as possible. Some developers need just CLI tool, and some want to import data programmatically. Before writing Mongo Seeding, I needed a ready-to-use Docker image and found none. Dockerizing an application is easy, but it takes time.\n\nThat's why Mongo Seeding consists of:\n\n- [TypeScript/JavaScript library](./core) - it can be installed straight from NPM and used in any JavaScript/TypeScript project,\n- [Command line interface (CLI)](./cli) - it can be installed globally and used from command line in any location,\n- [Docker image](./docker-image) - it is good for containerized applications.\n\nAll tools you'll ever need for seeding your MongoDB database.\n\n## Contribution\n\nBefore you contribute to this project, read **[`CONTRIBUTING.md`](./CONTRIBUTING.md)** file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkosiec%2Fmongo-seeding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkosiec%2Fmongo-seeding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkosiec%2Fmongo-seeding/lists"}