🌱 seed-smith

A powerful, flexible CLI tool for effortlessly seeding databases from YAML or JSON configuration files. Perfect for development, testing environments, and CI/CD pipelines.

✨ Features

• Multi-database Support: Seamlessly works with MongoDB and PostgreSQL
• Simple Configuration: Easy-to-write YAML or JSON configuration files
• Environment Variables: Built-in support for environment variable substitution
• Intelligent Updates: Identity field support for smart upserts
• Data Management: Options to clear existing data before seeding
• Safety First: Dry-run mode to validate configurations without modifying databases
• Performance Optimized: Efficiently handles large datasets with bulk operations

🚀 Quick Start

# Install globally
npm install -g seed-smith

# Run with your config
seed-smith --config seed-config.yml

📋 Installation Options

Global Installation

Makes seed-smith available across all your projects:

npm install -g seed-smith

Project Installation

Install as a development dependency in your current project:

npm install --save-dev seed-smith

Running with npx

Use without installation:

npx seed-smith --config seed-config.yml

🛠️ Command Line Options

Options:
  -c, --config <path>   Path to the configuration file (YAML or JSON)
  -e, --env <path>      Path to .env file (default: .env)
  --dry-run             Validate the configuration without seeding the database
  -v, --verbose         Enable verbose logging
  -h, --help            display help for command

📝 Configuration Examples

MongoDB Example

database:
  type: mongodb
  uri: ${MONGODB_URI}
  # Alternatively, you can specify components separately:
  # host: localhost
  # port: 27017
  # username: user
  # password: pass
  # database: testdb

options:
  clearBeforeSeeding: true

seeds:
  - name: users
    options:
      identityField: email
    data:
      - name: John Doe
        email: [email protected]
        role: admin
        createdAt: "2023-08-15T00:00:00Z"
      - name: Jane Smith
        email: [email protected]
        role: user
        createdAt: "2023-08-16T00:00:00Z"
  
  - name: products
    data:
      - name: Product A
        price: 19.99
        category: electronics
        inStock: true
      - name: Product B
        price: 29.99
        category: furniture
        inStock: false

PostgreSQL Example

database:
  type: postgresql
  host: ${PG_HOST}
  port: 5432
  username: ${PG_USER}
  password: ${PG_PASSWORD}
  database: ${PG_DATABASE}

options:
  clearBeforeSeeding: true

seeds:
  - name: users
    options:
      identityField: email
    data:
      - id: 1
        name: John Doe
        email: [email protected]
        role: admin
        created_at: "2023-08-15 00:00:00"
      - id: 2
        name: Jane Smith
        email: [email protected]
        role: user
        created_at: "2023-08-16 00:00:00"
  
  - name: products
    data:
      - id: 1
        name: Product A
        price: 19.99
        category: electronics
        in_stock: true
      - id: 2
        name: Product B
        price: 29.99
        category: furniture
        in_stock: false

🔄 Environment Variables

Use environment variables in your configuration files with the ${VARIABLE_NAME} syntax for secure credential management and environment-specific configurations.

Example .env file:

MONGODB_URI=mongodb://localhost:27017/testdb
PG_HOST=localhost
PG_USER=postgres
PG_PASSWORD=secret
PG_DATABASE=testdb

📊 Configuration Reference

Database Configuration

| Option | Description | Required | Default | |:-------------|:----------------------------------------|:---------|:------------| | type | Database type (mongodb or postgres) | Yes | - | | uri | Connection URI (MongoDB only) | No* | - | | host | Database host | No* | localhost | | port | Database port | No | Default port| | username | Database username | No | - | | password | Database password | No | - | | database | Database name | Yes** | - | | options | Additional connection options | No | - |

* Either uri or host must be provided for MongoDB
** Required for PostgreSQL

Seed Configuration

| Option | Description | Required | Default | |:---------------|:--------------------------------------|:---------|:--------| | name | Collection/Table name | Yes | - | | data | Array of records to seed | Yes | - | | options | Additional options | No | - | | identityField| Field to use for upsert operations | No | - |

Global Options

| Option | Description | Default | |:----------------------|:------------------------------------|:--------| | clearBeforeSeeding | Clear existing data before seeding | false |

💡 Common Use Cases

Testing Environments

NODE_ENV=test seed-smith --config test-data.yml

CI/CD Pipelines

# In your CI workflow
seed-smith --config ci-seed.yml --env .env.ci

Development Setup

# Add to your package.json scripts
"setup:dev": "seed-smith --config dev-seed.yml"

🔍 Troubleshooting

Connection Issues

If you're experiencing connection issues, try using the --verbose flag to get more detailed logs:

seed-smith --config seed-config.yml --verbose

Data Not Being Updated

When using identity fields, ensure that your data objects contain the specified identity field and that it has a unique value.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.