Welcome to fastapi-data-generator Documentation!

fastapi-data-generator is a powerful FastAPI package designed to facilitate realistic data generation for testing and development purposes. Developed to support large-scale data needs, it allows developers to populate database tables with customizable, constraint-aware, and highly representative sample data directly within their FastAPI projects.

The package enables the generation of data across various columns, including integers, strings, dates, emails, IP addresses, and more, with careful attention to unique constraints, data types, and column limits. It also supports related models and nested relationships, ensuring consistency across complex data structures. With its flexibility, memory efficiency, and ability to handle large datasets, fastapi-data-generator is ideal for developers looking to streamline testing with accurate and varied data scenarios in FastAPI applications.

Because it works against the SQLAlchemy mapper rather than any framework-specific model layer, it supports plain SQLAlchemy declarative models and SQLModel alike — a SQLModel class is a SQLAlchemy model.

Project Detail

• Language: Python >= 3.9
• Framework: FastAPI
• ORM: SQLAlchemy >= 2.0

Documentation Overview

The documentation is organized into the following sections:

• Quick Start: Get up and running quickly with basic setup instructions.
• Usage: How to effectively use the package in your projects.
• Settings: Configuration options and settings you can customize.

---

Quick Start

This section provides a fast and easy guide to getting the fastapi-data-generator package up and running in your FastAPI project. Follow the steps below to quickly set up the package and start using it.

1. Install the Package

Option 1: Using pip (Recommended)

Install the package via pip:

$ pip install fastapi-data-generator

Option 2: Using Poetry

If you're using Poetry, add the package with:

$ poetry add fastapi-data-generator

Option 3: Using pipenv

If you're using pipenv, install the package with:

$ pipenv install fastapi-data-generator

2. Point the Generator at Your Models

FastAPI has no global application registry, so the package needs to be told where your SQLAlchemy models live and which database to write to. Both are configured through environment variables, which may also be placed in a .env file:

DATA_GENERATOR_MODELS_MODULE=myapp.models
DATA_GENERATOR_DATABASE_URL=postgresql+psycopg://user:pass@localhost/db

Any module that exposes your declarative Base — or any single mapped model — is enough: every model sharing that base is discovered from it, including models defined in other modules.

3. Verify the Configuration

Confirm everything is wired up correctly before generating anything:

$ fastapi-data-generator check

4. Generate Fake Data

After setting up the package, run the generate-data command to generate fake data for project models:

$ fastapi-data-generator generate-data --num-records=1000

You can also use the --skip-confirmation argument to bypass the user confirmation prompt.

To generate fake data for a specific model, use the --model=app.Model argument.

---

Usage

This section provides a comprehensive guide on how to utilize the package's key features.

Model Identifiers

Every model is addressed as app_label.ModelName, the same format the Django package uses. Since SQLAlchemy has no concept of an app, the label is resolved from the model itself using the first rule that applies:

1. An explicit __app_label__ attribute on the model.
2. The schema of the model's table, when one is set.
3. The top-level package of the module the model is defined in.

Setting __app_label__ on your declarative base is the simplest way to give a whole group of models a stable, meaningful label:

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    __app_label__ = "shop"

With that base, a User model is addressed as shop.User.

How Columns Are Populated

Values are chosen from the SQLAlchemy column type, resolved through the type's method resolution order — so dialect-specific types such as VARCHAR or BIGINT, and your own subclasses, resolve to their nearest supported base type.

SQLAlchemy has no equivalent of Django's EmailField or URLField, so for string columns the intent is additionally inferred from the column name, and that inference takes precedence over the plain string generator:

Column name contains	Generated value
email	userAb3xZ@example.com
url, website, homepage	https://example.com/Ab3xZ
ip_address, ipaddress	192.0.2.14 or an IPv6 form
image, avatar, photo, picture	images/Ab3xZ.png
slug	a random slug string
uuid	3d4c065c-4814-...

Columns are otherwise handled as follows:

• Autoincrementing primary keys are left to the database. A non-autoincrementing primary key, such as a string code, is generated.
• Unique columns receive values guaranteed distinct within the run.
• Columns with a default or server default are skipped so the default applies.
• Foreign keys reference rows that already exist, generating the related model first when needed.
• Unsupported column types are skipped rather than guessed at.

generate-data Command

The generate-data command generates fake data for all models in your FastAPI project or for a specified model. It offers options to customize record count, skip confirmation prompts, and filter models and apps based on configuration settings.

Command Overview

The generate-data command creates a specified number of records for each model, excluding any models or apps specified in the configuration. This is especially useful for populating your database with sample data for testing and development.

Settings

This command is influenced by the following settings for fine-grained control over data generation:

• DATA_GENERATOR_MODELS_MODULE: The dotted path of the module defining your SQLAlchemy models.

• DATA_GENERATOR_DATABASE_URL: The SQLAlchemy database URL the generated data is written to.

• DATA_GENERATOR_EXCLUDE_APPS: A list of app labels to exclude from data generation. Models within these apps will not be included in the data generation process.

• DATA_GENERATOR_EXCLUDE_MODELS: A list of models to exclude from data generation, specified in the format app_label.ModelName. Any models listed here will be skipped.

• DATA_GENERATOR_CUSTOM_FIELD_VALUES: Allows setting custom values for specific columns in specified models. This dictionary should have keys in the format app_label.ModelName, with each key containing a dictionary of field-value pairs to customize.

Example:

DATA_GENERATOR_CUSTOM_FIELD_VALUES='{"shop.User": {"first_name": "sample", "email": "sample@example.com"}}'

Usage

The command is available as a console script once the package is installed:

$ fastapi-data-generator generate-data

Optional Arguments

• --num-records: Sets the number of records to generate per model. If not specified, the default is 100 records per model.

Example:

$ fastapi-data-generator generate-data --num-records 1000

• --skip-confirmation: Skips the confirmation prompt, proceeding directly with data generation. Useful for automation or non-interactive environments.

Example:

$ fastapi-data-generator generate-data --skip-confirmation

• --model: Specifies a single model (in app_label.ModelName format) to generate data for, instead of generating data for all models.

Example:

$ fastapi-data-generator generate-data --model shop.User

• --models-module and --database-url: Override DATA_GENERATOR_MODELS_MODULE and DATA_GENERATOR_DATABASE_URL for a single run, without touching the environment.

Example:

$ fastapi-data-generator generate-data --models-module myapp.models --database-url sqlite:///dev.db

Command Flow

1. Discover Target Models: The command imports the configured models module and collects every mapped model, excluding those defined in DATA_GENERATOR_EXCLUDE_APPS and DATA_GENERATOR_EXCLUDE_MODELS. If a specific model is specified with --model, only that model will be targeted.

2. Confirmation Prompt: If no --skip-confirmation flag is set, the command lists the models to be processed and asks for user confirmation. This allows users to verify the list before proceeding with data generation.

3. Generate Data for Models: The command generates the specified number of records per model, handling unique columns and relationships between models. Related model instances are cached for reuse within a session.

4. Output Progress: A progress bar is displayed in the terminal, showing the completion percentage for each model.

Example Output

When running the command, you may see output similar to:

The following models were found:
1. <class 'myapp.models.User'>
2. <class 'myapp.models.Profile'>
3. <class 'myapp.models.Order'>

Are these the correct target models?
 Type 'y' to proceed or 'n' to cancel the operation:y

Generating data for model: shop.User
[ █ █ █ █ █ █ ─ ─ ─ ─ ] 60% completed for shop.User

Generating data for model: shop.Profile
[ █ █ █ █ █ █ █ █ █ █ ] 100% completed for shop.Profile

Done!

check Command

Django registers its configuration checks with the framework automatically. FastAPI has no equivalent hook, so the same validation is exposed as a command:

$ fastapi-data-generator check

It validates every DATA_GENERATOR_* setting — that the models module is importable, the database URL is set, the exclusion lists are lists of strings naming real models, and the custom field values name real models and real columns. It exits with a non-zero status when anything is wrong, which makes it suitable for CI. The same validation runs automatically before every generate-data run.

---

Settings

This section outlines the available settings for configuring the fastapi-data-generator package. You can customize these settings through environment variables or a .env file to tailor the behavior of the data generator to your needs.

Settings are read with the DATA_GENERATOR_ prefix. List and dictionary settings are parsed as JSON.

Example Settings

Below is an example configuration with default values:

DATA_GENERATOR_MODELS_MODULE=
DATA_GENERATOR_DATABASE_URL=
DATA_GENERATOR_EXCLUDE_APPS=[]
DATA_GENERATOR_EXCLUDE_MODELS=[]
DATA_GENERATOR_CUSTOM_FIELD_VALUES={}

They can equally be applied from Python, which is the closest equivalent to editing Django's settings.py:

from fastapi_data_generator.settings.conf import config

config.override(
    models_module="myapp.models",
    database_url="sqlite:///dev.db",
    exclude_apps=["billing"],
)

Settings Overview

Below is a detailed description of each setting, so you can better understand and tweak them to fit your project's needs.

DATA_GENERATOR_MODELS_MODULE

Type: str

Default: "" (empty string)

Description: The dotted path of the module defining your SQLAlchemy models. This is how the package discovers what to generate data for, replacing Django's application registry. For example:

DATA_GENERATOR_MODELS_MODULE=myapp.models

The module only needs to expose your declarative Base or any single mapped model — every model sharing that base is reached from it.

---

DATA_GENERATOR_DATABASE_URL

Type: str

Default: "" (empty string)

Description: The SQLAlchemy database URL the generated rows are written to. For example:

DATA_GENERATOR_DATABASE_URL=postgresql+psycopg://user:pass@localhost/db

Point this at a development or test database. The command writes real rows, so it is not something to run against production data.

---

DATA_GENERATOR_EXCLUDE_APPS

Type: list

Default: [] (empty list)

Description: Specifies a list of app labels that should be excluded when running the generate-data command. If certain apps should not be considered for data generation, list them here. For example:

DATA_GENERATOR_EXCLUDE_APPS='["finance", "store"]'

This setting prevents the generate-data command from scanning the specified apps when generating fake data for models.

---

DATA_GENERATOR_EXCLUDE_MODELS

Type: list

Default: [] (empty list)

Description: Specifies a list of model names that should be excluded when running the generate-data command. If certain models should not be included in the data generation process, define them here. For example:

DATA_GENERATOR_EXCLUDE_MODELS='["app_label.CustomModel", "app_label.AnotherModel"]'

This setting allows fine-tuned control over which models are excluded from fake data creation, even if their app is not fully excluded.

Note that a model on the other side of a one-to-one relation is still generated even when excluded, since the dependent model cannot be created without it.

---

DATA_GENERATOR_CUSTOM_FIELD_VALUES

Type: dict

Default: {} (empty dictionary)

Description: Defines custom values for specific columns in particular models during the data generation process. This setting allows users to specify exact values for certain columns instead of random or default-generated data, giving finer control over the generated dataset.

The dictionary's format follows { "app_label.ModelName": { "column_name": "custom_value" } }.

For example:

DATA_GENERATOR_CUSTOM_FIELD_VALUES='{"shop.User": {"first_name": "somebody", "email": "user@example.com"}, "shop.Product": {"price": 9.99, "stock": 100}}'

In this example:

• The shop.User model's first_name column will always be set to "somebody".

• The shop.Product model's price and stock columns will always have values of 9.99 and 100, respectively.

This setting is useful when certain columns require specific values, such as default usernames or predefined product prices, while other columns can still be generated with random or unique values.

---

Final Notes:

• Version Compatibility: Ensure your project meets the compatibility requirements for both SQLAlchemy and Python versions.
• Contributions: Contributions are welcome! Feel free to check out the Contributing guide for more details.

If you encounter any issues or have feedback, please reach out via our GitHub Issues page.