Usage#

This guide covers the basic usage patterns for Django Synced Seeds.

Management Commands#

Django Synced Seeds provides several management commands:

Export Seeds#

Export seed data from your current environment:

python manage.py exportseed <seeder_slug>

# Example
python manage.py exportseed categories

Sync Seeds#

Sync all available seeds to the current environment:

python manage.py syncseeds

# Sync only seeders with specific tags
python manage.py syncseeds e2e

# Sync multiple tags (union of all matching seeders)
python manage.py syncseeds e2e development

Creating Seeders#

Create a seeder by subclassing Seeder and registering it:

1
2
3
4
5
6
7
8
# myapp/seeders.py
from seeds import seeder_registry, Seeder
from .models import Category

@seeder_registry.register()
class CategorySeeder(Seeder):
    seed_slug = "categories"
    exporting_querysets = (Category.objects.all(),)

Setting Load Priority#

Use the priority attribute to control the order in which seeders are loaded. This is essential when you have foreign key dependencies between seeders.

Lower priority numbers load first (default is 100).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# myapp/seeders.py
from seeds import seeder_registry, Seeder
from .models import Category, Product

@seeder_registry.register()
class CategorySeeder(Seeder):
    seed_slug = "categories"
    priority = 10  # Load first
    exporting_querysets = (Category.objects.all(),)

@seeder_registry.register()
class ProductSeeder(Seeder):
    seed_slug = "products"
    priority = 20  # Load after categories
    exporting_querysets = (Product.objects.all(),)

Common Priority Patterns#

Base Data (Priority 1-20):

  • User roles and permissions

  • System configuration

  • Reference data (countries, currencies)

Primary Entities (Priority 21-50):

  • Users, organizations

  • Categories, taxonomies

  • Core domain entities

Dependent Data (Priority 51-100):

  • Content items referencing categories

  • Orders referencing users and products

  • Any data with foreign key dependencies

Example with Foreign Keys#

Consider an e-commerce application with these models:

# models.py
class Category(models.Model):
    name = models.CharField(max_length=100)

class Product(models.Model):
    name = models.CharField(max_length=100)
    category = models.ForeignKey(Category, on_delete=models.CASCADE)

class Review(models.Model):
    product = models.ForeignKey(Product, on_delete=models.CASCADE)
    rating = models.IntegerField()

The seeders should be prioritized to prevent foreign key errors:

# myapp/seeders.py
from seeds import seeder_registry, Seeder
from .models import Category, Product, Review

@seeder_registry.register()
class CategorySeeder(Seeder):
    seed_slug = "categories"
    priority = 10  # Load first - no dependencies
    exporting_querysets = (Category.objects.all(),)

@seeder_registry.register()
class ProductSeeder(Seeder):
    seed_slug = "products"
    priority = 20  # Load after categories
    exporting_querysets = (Product.objects.all(),)

@seeder_registry.register()
class ReviewSeeder(Seeder):
    seed_slug = "reviews"
    priority = 30  # Load last - depends on products
    exporting_querysets = (Review.objects.all(),)

When you run python manage.py syncseeds, the seeders will load in order: categories → products → reviews, preventing any foreign key constraint violations.

Tagging Seeders#

Organize seeders with tags for targeted execution. This is useful for different testing scenarios or deployment strategies.

Single Tag#

Register a seeder with a single tag:

1
2
3
4
5
6
7
8
# myapp/seeders.py
from seeds import seeder_registry, Seeder
from .models import User

@seeder_registry.register(tags="e2e")
class E2ETestSeeder(Seeder):
    seed_slug = "e2e_test_data"
    exporting_querysets = (User.objects.all(),)

Multiple Tags#

Register a seeder with multiple tags:

1
2
3
4
5
6
7
8
# myapp/seeders.py
from seeds import seeder_registry, Seeder
from .models import Product

@seeder_registry.register(tags=["development", "demo"])
class DemoSeeder(Seeder):
    seed_slug = "demo_data"
    exporting_querysets = (Product.objects.all(),)

Running Tagged Seeders#

Execute seeders by tag:

# Sync only e2e tagged seeders
python manage.py syncseeds e2e

# Sync multiple tags (union of all matching seeders)
python manage.py syncseeds e2e development

# Sync all seeders (default behavior)
python manage.py syncseeds

Common Use Cases#

Testing Environments:

  • e2e - End-to-end test data

  • integration - Integration test data

  • unit - Unit test data

Deployment Stages:

  • development - Development environment data

  • staging - Staging environment data

  • demo - Demo/showcase data

Data Categories:

  • base - Essential base data (users, roles)

  • sample - Sample content for testing

  • reference - Reference data (countries, currencies)

Auto-discovery#

The seeder registry automatically discovers seeders in your installed apps.

Auto-discovery looks for seeders.py files in each app.

Version Management#

Seeders automatically track versions using revision numbers.

Each time you export data, a new revision is created.

During sync, only newer revisions are imported.

Next Steps#

On this page