Installation¶

This guide will help you install Edda and set up your development environment.

Prerequisites¶

• Python 3.11 or higher
• uv package manager (recommended) or pip

Installing Edda¶

Using uv¶

Install Edda from PyPI using uv:

# Basic installation (includes SQLite support)
uv add edda-framework

This installs Edda with SQLite support, which is perfect for:

• Local development
• Testing
• Single-process deployments (suitable for development, testing, and low-traffic single-server apps)

Important: For multi-process or multi-pod deployments (K8s, Docker Compose with multiple replicas, etc.), you must use PostgreSQL or MySQL. SQLite supports multiple async workers within a single process, but its table-level locking makes it unsuitable for multi-process/multi-pod scenarios.

With database extras:

# With PostgreSQL support (recommended for production)
uv add edda-framework --extra postgresql

# With MySQL support
uv add edda-framework --extra mysql

# With Viewer UI (workflow visualization)
uv add edda-framework --extra viewer

# All extras (PostgreSQL + MySQL + Viewer UI)
uv add edda-framework --extra postgresql --extra mysql --extra viewer

What gets installed:

• Base: SQLite support via aiosqlite (always included)
• postgresql: asyncpg driver for PostgreSQL
• mysql: aiomysql driver for MySQL
• viewer: nicegui and httpx for workflow visualization UI

Using pip¶

If you prefer using pip:

# Basic installation
pip install edda-framework

# With PostgreSQL support
pip install "edda-framework[postgresql]"

# With MySQL support
pip install "edda-framework[mysql]"

# With Viewer UI
pip install "edda-framework[viewer]"

# All extras
pip install "edda-framework[postgresql,mysql,viewer]"

Installing from GitHub (Development Versions)¶

For testing the latest development version or a specific branch/commit, you can install directly from GitHub:

Latest Development Version¶

# Using uv
uv add git+https://github.com/i2y/edda.git

# Using pip
pip install git+https://github.com/i2y/edda.git

This installs the latest code from the main branch.

Specific Version, Branch, or Commit¶

# Specific tag (e.g., v0.1.0)
uv add git+https://github.com/i2y/edda.git@v0.1.0
pip install git+https://github.com/i2y/edda.git@v0.1.0

# Specific branch
uv add git+https://github.com/i2y/edda.git@feature-branch
pip install git+https://github.com/i2y/edda.git@feature-branch

# Specific commit
uv add git+https://github.com/i2y/edda.git@abc1234
pip install git+https://github.com/i2y/edda.git@abc1234

With Database Extras¶

# Using uv (PostgreSQL + Viewer)
uv add "git+https://github.com/i2y/edda.git[postgresql,viewer]"

# Using pip
pip install "git+https://github.com/i2y/edda.git[postgresql,viewer]"

When to use GitHub installation:

• ✅ Development & Testing: Try unreleased features or bug fixes
• ✅ Contributing: Test your changes before submitting a PR
• ✅ Specific Version: Pin to a particular commit or branch
• ❌ Production: Use PyPI releases for production deployments

Note: GitHub installations require Git to be installed on your system.

Verifying Installation¶

Check that Edda is installed correctly:

# test_installation.py
import asyncio
from edda import EddaApp, workflow, activity, WorkflowContext

@activity
async def hello_activity(ctx: WorkflowContext, name: str):
    return f"Hello, {name}!"

@workflow
async def hello_workflow(ctx: WorkflowContext, name: str):
    result = await hello_activity(ctx, name)
    return {"message": result}

async def main():
    # Create app with in-memory SQLite
    app = EddaApp(service_name="demo-service", db_url="sqlite:///:memory:")

    # Initialize the app before starting workflows
    await app.initialize()

    try:
        # Start workflow
        instance_id = await hello_workflow.start(name="World")
        print(f"Workflow started: {instance_id}")

        # Get result
        instance = await app.storage.get_instance(instance_id)
        result = instance['output_data']['result']
        print(f"Result: {result}")

    finally:
        # Cleanup resources
        await app.shutdown()

if __name__ == "__main__":
    asyncio.run(main())

Run the test:

uv run python test_installation.py

Expected output:

Workflow started: <instance_id>
Result: {'message': 'Hello, World!'}

The result is extracted from instance['output_data']['result'], which contains the return value of the workflow.

Database Setup¶

Database Selection¶

SQLite (Default)¶

No additional setup required! SQLite databases are created automatically:

from edda import EddaApp

# File-based SQLite (single-process only)
app = EddaApp(service_name="demo-service", db_url="sqlite:///workflow.db")

# In-memory (testing only)
app = EddaApp(service_name="demo-service", db_url="sqlite:///:memory:")

SQLite Considerations:

✅ Supported scenarios:

• Single-process deployments (even with multiple async workers within that process)
• Development and testing environments
• Low-traffic single-server applications

❌ Not supported:

• Multi-process deployments (Docker Compose with replicas: 3, multiple systemd services)
• Multi-pod deployments (Kubernetes with multiple replicas)
• High-concurrency production scenarios

⚠️ Performance limitations:

• Table-level locking (not row-level like PostgreSQL/MySQL)
• Concurrent writes are serialized, impacting throughput
• For production with multiple processes/pods, use PostgreSQL or MySQL

PostgreSQL¶

1. Install PostgreSQL (if not already installed)

2. Create a database:

CREATE DATABASE edda_workflows;

1. Configure connection:

from edda import EddaApp

app = EddaApp(
    service_name="demo-service",
    db_url="postgresql://user:password@localhost/edda_workflows"
)

MySQL¶

1. Install MySQL (if not already installed)

2. Create a database:

CREATE DATABASE edda_workflows;

1. Configure connection:

from edda import EddaApp

app = EddaApp(
    service_name="demo-service",
    db_url="mysql://user:password@localhost/edda_workflows"
)

Next Steps¶

• Quick Start: Build your first workflow in 5 minutes
• Core Concepts: Learn about workflows, activities, and durable execution
• Your First Workflow: Step-by-step tutorial