> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellomas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Circular Dependencies

> Handling circular FK dependencies between tables.

# Circular Dependencies

Real-world schemas often have circular foreign key dependencies. Seedling handles these with multi-pass generation.

## Detection

During planning, Seedling detects cycles in the FK dependency graph:

```mermaid theme={null}
graph LR
  A[Table A] -->|FK| B[Table B]
  B -->|FK| C[Table C]
  C -->|FK| A
```

When a cycle is detected, it is split into **pass groups**. Tables in a cycle are generated together across multiple passes.

## Nullable Circular FKs

If at least one column in the cycle is nullable:

1. **Pass 1:** Generate rows with NULL in the nullable FK
2. **Pass 2:** Update the NULL FKs with valid references

This is the simplest and most performant approach.

## Non-Nullable Circular FKs

If all columns in a cycle are `NOT NULL`:

1. Use `SET CONSTRAINTS ALL DEFERRED` within a transaction
2. Generate all rows without FK validation
3. Commit — deferred constraints are checked at commit time

This requires the database to support deferred constraints (Postgres supports this; MySQL does not).

## Many-to-Many Join Tables

Join tables (e.g., `users_roles`) are handled by:

1. Generating both parent tables first
2. Generating the join table with FK references to both parents
3. Configurable join factor (how many links per parent row)

```yaml theme={null}
users_roles:
  user_id:
    generator: fk_pool
    params:
      strategy: weighted
      join_factor: 3
  role_id:
    generator: fk_pool
    params:
      strategy: uniform
```