Django Model Seeder

Command-based synthetic data generation and seeding for Django models using data-seed-ph.

Note

Designed for rapid database population in development environments, API testing, QA automation, and demo applications with seamless integration to Django's management command system.

Why Django Model Seeder

Populating Django databases with realistic test data can be repetitive and time-consuming. Django Model Seeder simplifies this process by offering powerful management commands that automatically generate realistic Philippine-based synthetic data and insert it directly into your Django models, eliminating the need for manual data seeding scripts.

Table of Contents

• Installation
• Quick Start
• Configuration
  • JSON Configuration
  • YAML Configuration
• Management Commands
  • seed_models
  • clear_seeds
  • list_seeds
• Data Generation Types
• Advanced Usage
• Use Cases
• Important Notes
• Troubleshooting
• Library Source
• License

Installation

Install via python package index Pypi.

pip install django-model-seeder

Quick Start

Add django_seeder to your Django INSTALLED_APPS:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_seeder',
    'your_app_name',
]

Create Database model in your app/models.py file:

from django.db import models

class Artist(models.Model):
    firstname = models.CharField(max_length=100)
    lastname = models.CharField(max_length=100)
    email = models.EmailField()

Create fixtures/seed_config.json file:

{
    "Artist": {
        "app_label": "music_app",
        "rows": 30,
        "mapping": {
            "firstname": "firstname",
            "lastname": "lastname",
            "email": "email"
        }
    }
}

Run seeding command:

python manage.py seed_models --config fixtures/seed_config.json

Output of the command and check your database for confirmation:

Loaded config from fixtures/seed_config.json
Seeding successfully completed
Artist: 30 rows seeded

Configuration

JSON Configuration

Define your seeding configuration in JSON format:

{
    "ModelName": {
        "app_label": "app_label_name",
        "rows": "number_of_rows",
        "mapping": {
            "field_name": "data_generator_keyword_or_custom_values"
        }
    }
}

Example:

{
    "Artist": {
        "app_label": "music_app",
        "rows": 30,
        "mapping": {
            "firstname": "firstname",
            "lastname": "lastname",
            "email": "email",
            "birthdate": "birthdate"
        }
    },
    "Album": {
      "app_label": "music_app",
        "rows": 100,
        "mapping": {
            "category": ["Jazz", "Rock", "RnB"],
            "rating": [0.0, 5.0, "float"],
            "views": [0, 50000]
        }
    }
}

YAML Configuration

Define your seeding configuration in YAML format:

Artist:
    app_label: app_label_name
    rows: number_of_rows
    mapping:
        field_name: data_generator_keyword_or_custom_values

Example:

Artist:
    app_label: music_app
    rows: 50
    mapping:
        firstname: firstname
        lastname: lastname
        email: email
        birthdate: birthdate
Album:
    rows: 100
    mapping: 
        category:
            - Jazz
            - Rock
            - RnB
        rating:
            - 0.0
            - 5.0
            - float
        views:
            - 0
            - 50000

Management Commands

1. seed_models command

Seed Django models with synthetic data from configuration files or direct arguments.

Syntax:

python manage.py seed_models [OPTIONS]

Options:

Option	Type	Default	Description
--config	str	None	Path to seed configuration file (JSON or YAML)
--model	str	None	Specific model to seed (format: ModelName)
--app	str	None	Django app label
--rows	int	10	Number of rows to seed
--clear	flag	False	Clear existing data before seeding
--dry-run	flag	False	Show what would be seeded without actually seeding
--verbose	flag	False	Show detailed output including sample records

Examples

From configuration file:

python manage.py seed_models --config fixtures/seed_config.json

From configuration file with verbose output:

python manage.py seed_models --config fixtures/seed_config.json --verbose

Clear existing data and reseed:

python manage.py seed_models --config fixtures/seed_config.json --clear

Dry run preview:

python manage.py seed_models --config fixtures/seed_config.json --dry-run

Seed specific model or auto-generated mapping with arguments:

python manage.py seed_models --model Artist --app music_app --rows 50

Seed specific model and clear first:

python manage.py seed_models --model Artist --app music_app --rows 50 

2. clear_seeds command

Clear seeded data from Django models.

Syntax:

python manage.py clear_seeds [OPTIONS]

Options:

Option	Type	Default	Description
--model	str	None	Specific model to clear (format: ModelName)
--app	str	None	Django app label
--all	flag	False	Clear data from all models
--confirm	flag	False	Skip confirmation prompt

Examples

Clear specific model with confirmation:

python manage.py clear_seeds --model Artist --app music_app

Clear specific model without confirmation:

python manage.py clear_seeds --model Artist --app music_app --confirm

Clear all seeded data with confirmation:

python manage.py clear_seeds --all

Clear all seeded data without confirmation:

python manage.py clear_seeds --all --confirm

3. list_seeds command

List all available Django models for seeding with optional record counts.

Syntax:

python manage.py list_seeds [OPTIONS]

Options:

Option	Type	Default	Description
--app	str	None	Django app label
--count	flag	False	Show record count each model

Examples

List all available models:

python manage.py list_seeds

List models in specific app:

python manage.py list_seeds --app music_app

List models with record counts:

python manage.py list_seeds --count

List models in specific app with counts:

python manage.py list_seeds --app music_app --count

Data Generation Types

1. String Keywords

Use built-in data generators with string keywords from Data Seed PH.

Examples

{
    "Artist": {
        "app_label": "music_app",
        "rows": 30,
        "mapping": {
            "firstname": "firstname",
            "lastname": "lastname",
            "email": "email",
            "birthdate": "birthdate"
        }
    }
}

2. Numeric Ranges (Tuples)

Generate random integers ot floats within specified ranges.

Note

JSON lists are converted into tuples when generating data with specified ranges.

{
    "Album": {
        "app_label": "music_app",
        "rows": 100,
        "mapping": {
            "likes": [0, 100000],
            "rating": [0.0, 5.0, "float"],
            "views": [0, 50000]
        }
    }
}

Format

• Integer range: [min, max]
• Float range: [min, max, "float"]

3. Categorical Values (Lists)

Choose randomly from predefined options.

{
    "Album": {
        "app_label": "music_app",
        "rows": 100,
        "mapping": {
            "catgeory": ["RnB", "Rock", "Hip-Hop", "Jazz"],
            "album_type": ["Studio Album", "Live Album", "Single", "EP"],
            "release_format": ["Digital", "CD"]
        }
    }
}

4. Parameterized Keywords

Some generators accept parameters using colon syntax:

Note

Parameterized keywords only available in AddressDataProvider provider within Data Seed PH library.

{
  "Location": {
    "app_label": "geoprroject",
    "rows": 30,
    "mapping": {
      "addr_province": "province:Surigao Del Norte",
      "addr_municipality": "municipality:Claver",
      "addr_barangay": "barangay"
    }
  }
}

Supported field types

• CharField, TextField: string keywords or lists
• IntegerField: tuples with int range
• FloatField: tuples with float range
• DateField: date keywords like birthdate
• EmailField: email keyword
• ForeignKey: handled programmatically (see Advanced Usage)

Advanced Usage

Models with Foreign Key Relations

Seed models with foreign key relationships using the relations key in your configuration file.

Example Django Models in music_app/models.py:

from django.db import models

class Artist(models.Model):
    firstname = models.CharField(max_length=100)
    lastname = models.CharField(max_length=100)
    email = models.EmailField(unique=True)
    phone = models.CharField(max_length=20)
    age = models.IntegerField()

class Album(models.Model):
    title = models.CharField(max_length=200)
    artist = models.ForeignKey(Artist, on_delete=models.CASCADE, related_name='albums')
    description = models.TextField()
    genre = models.CharField(max_length=100)
    release_year = models.IntegerField()
    streams = models.IntegerField(default=0)
    rating = models.FloatField(default=0.0)

class Review(models.Model):
    album = models.ForeignKey(Album, on_delete=models.CASCADE, related_name='reviews')
    reviewer_name = models.CharField(max_length=100)
    feedback = models.TextField()
    email = models.EmailField()
    rating = models.IntegerField()

Configuration with Relations (JSON) file in fixtures/seed_config.json:

{
  "Artist": {
    "app_label": "music_app",
    "rows": 20,
    "mapping": {
      "firstname": "firstname",
      "lastname": "lastname",
      "email": "email",
      "phone": "mobile",
      "age": [25, 65]
    }
  },
  "Album": {
    "app_label": "music_app",
    "rows": 100,
    "mapping": {
      "title": ["Echoes of Time", "Midnight Dreams", "Silver Linings"],
      "description": "fulladdress",
      "genre": "course",
      "release_year": [2015, 2024],
      "streams": [0, 1000000],
      "rating": [1.0, 5.0, "float"]
    },
    "relations": {
      "artist": "Artist"
    }
  },
  "Review": {
    "app_label": "music_app",
    "rows": 250,
    "mapping": {
      "reviewer_name": "fullname",
      "feedback": "fulladdress",
      "email": "email",
      "rating": [1, 5]
    },
    "relations": {
      "album": "Album"
    }
  }
}

Configuration with Relation (YAML) file in fixtures/seed_config.yaml:

Artist:
  app_label: music_app
  rows: 20
  mapping:
    firstname: firstname
    lastname: lastname
    email: email
    phone: mobile
    age:
      - 25
      - 65

Album:
  app_label: music_app
  rows: 100
  mapping:
    title:
      - Echoes of Time
      - Midnight Dreams
      - Silver Linings
    description: fulladdress
    genre: course
    release_year:
      - 2015
      - 2024
    streams:
      - 0
      - 1000000
    rating:
      - 1.0
      - 5.0
      - float
  relations:
    artist: Artist

Review:
  app_label: music_app
  rows: 250
  mapping:
    reviewer_name: fullname
    feedback: fulladdress
    email: email
    rating:
      - 1
      - 5
  relations:
    album: Album

How Relations Work

The relations key links foreign keys to parent models:

• "artist": "Artist": Each Album gets a random Artist from existing Artist records
• "album": "Album": Each Review gets a random Album from existing Album records

Use Cases

• Development: Populate databases with realistic test data during development

• Testing: Seed test databases for integration and end-to-end tests

• API Testing: Generate test payloads and bulk request data for API endpoint testing

• QA Automation: Quickly set up test databases for QA testing cycles

• Demo Applications: Build convincing demos with realistic Philippine synthetic data

• Load Testing: Create large datasets for performance and stress testing

• Staging Environments: Pre-populate staging databases with realistic data

• Documentation: Generate example data for README and API documentation

• Database Backup Testing: Restore and verify database backups with synthetic data

Important Notes

Important

Synthetic Data Disclaimer: All generated data is random and synthetic. It does NOT represent real individuals, real addresses, or real contact information. Use this library only for development, testing, and non-production environments.

Tip

Related Library: Django Model Seeder uses data-seed-ph library for authentic Philippine synthetic data generation.

Warning

Avoid seeding production databases. Always use this library in development and testing environments only.

Troubleshooting

1. Command Not Found

Error: django.core.management.base.CommandError: No app with label 'django_seeder'

Solution: Ensure django_seeder is added to INSTALLED_APPS in settings.py

INSTALLED_APPS = [
    ...
    'django_seeder',
    ...
]

2. Configuration File Not Found

Error: FileNotFoundError: Configuration file not found

Solution: Ensure the config file path is correct and relative to your project root

python manage.py seed_models --config fixtures/seed_config.json

3. Import Errors

Error: ModuleNotFoundError: No module named 'data_seed_ph'

Solution: Install the dependency

pip install data-seed-ph

4. Module Not Found

Error: LookupError: Model not found: myapp.Author

Solution: Verify app label and model name are correct

python manage.py list_seeds

5. Invalid JSON Configuration

Error: InvalidConfigurationError: Invalid configuration file format

Solution: Validate JSON syntax using an online validate or:

python -m json.tool fixtures/seed_config.json

Library Source

• Data Seed PH
• Django Documentation
• Django Management Commands

Releases

See releases

License

MIT License - See LICENSE file for details.

Author