# aiven/aiven-db-migrate architecture

> Architecture diagram of the GitHub repository aiven/aiven-db-migrate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aiven/aiven-db-migrate
- Repository: https://github.com/aiven/aiven-db-migrate

## Overview

##### Project type and purpose
- This is an open-source, Python-based CLI and library tool ("aiven-db-migrate") for migrating PostgreSQL databases between service providers (e.g., AWS RDS → Aiven) or on-prem → cloud.
- It packages a core migration engine (“PGMigrate”), command-line entrypoints (`pg_migrate`), utility modules (`pgutils`, `pgmigrate`, error handling), and test/CI scaffolding.

##### File structure
- Top-level:
- `aiven_db_migrate/` – main package
– `migrate/` – code for migration logic:
○ `__main__.py` – CLI entrypoint for `python -m aiven_db_migrate.migrate`
○ `pgmigrate.py` – orchestrator for dump vs replication methods
○ `pgutils.py` – wrappers around psql/pg_dump calls, connection handling
○ `errors.py` – custom exceptions
○ `version.py` – version metadata
- `setup.py`, `Makefile`, config files – packaging, build, style, CI
- `test/` – pytest suite covering all migration scenarios
- No web server or frontend; this is a monolithic CLI tool structured as a library + console scripts.

##### README for additional insights
- Describes features: dump vs logical replication fallback; role & schema migration; extension handling; `aiven-extras` integration.
- Mentions future extensibility to other DB engines (MySQL, etc.) – implies plugin-style architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "User Interaction"
        direction TB
        User["User"]:::user
        CLI["CLI Layer"]:::entry
    end

    subgraph "Migration Engine Layer"
        direction TB
        Engine["PGMigrate\n(aiven_db_migrate/migrate/pgmigrate.py)"]:::engine
        Utils["pgutils\n(aiven_db_migrate/migrate/pgutils.py)"]:::util
        Errors["errors\n(aiven_db_migrate/migrate/errors.py)"]:::util
        Version["version\n(aiven_db_migrate/migrate/version.py)"]:::util
    end

    subgraph "CLI Package"
        direction TB
        Setup["setup.py"]:::infra
        Main["__main__.py\n(aiven_db_migrate/migrate/__main__.py)"]:::entry
    end

    subgraph "External Dependencies"
        direction TB
        Binaries["pg_dump / psql\n(System Binaries)"]:::bin
        SourceDB["Source PostgreSQL\nCylinder"]:::db
        TargetDB["Target PostgreSQL\nCylinder"]:::db
        Extras["aiven-extras\n(Extension)"]:::db
    end

    subgraph "Packaging & CI"
        direction TB
        Makefile["Makefile"]:::infra
        CI["GitHub Actions\n(.github/workflows)"]:::infra
    end

    %% Connections
    User -->|invokes| CLI
    CLI -->|entrypoint| Main
    CLI -->|defined in| Setup
    Main -->|instantiates| Engine
    Engine -->|calls| Utils
    Engine -->|raises| Errors
    Engine -->|reads| Version
    Engine -->|executes dump/replication via| Binaries
    Utils -->|connects to| SourceDB
    Utils -->|connects to| TargetDB
    Engine -->|optional plugin| Extras

    %% Packaging & CI flows
    Setup --> Makefile
    Setup --> CI

    %% Click events
    click Setup "https://github.com/aiven/aiven-db-migrate/blob/main/setup.py"
    click Main "https://github.com/aiven/aiven-db-migrate/blob/main/aiven_db_migrate/migrate/__main__.py"
    click Engine "https://github.com/aiven/aiven-db-migrate/blob/main/aiven_db_migrate/migrate/pgmigrate.py"
    click Utils "https://github.com/aiven/aiven-db-migrate/blob/main/aiven_db_migrate/migrate/pgutils.py"
    click Errors "https://github.com/aiven/aiven-db-migrate/blob/main/aiven_db_migrate/migrate/errors.py"
    click Version "https://github.com/aiven/aiven-db-migrate/blob/main/aiven_db_migrate/migrate/version.py"
    click CI "https://github.com/aiven/aiven-db-migrate/tree/main/.github/workflows/"
    click Makefile "https://github.com/aiven/aiven-db-migrate/tree/main/Makefile"

    %% Styles
    classDef user fill:#FFF3BF,stroke:#F59E0B,stroke-width:2px;
    classDef entry fill:#FEF08A,stroke:#CA8A04,stroke-width:2px;
    classDef engine fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px;
    classDef util fill:#E0F2FE,stroke:#0284C7,stroke-width:2px;
    classDef infra fill:#F3F4F6,stroke:#6B7280,stroke-width:2px;
    classDef bin fill:#E5E7EB,stroke:#374151,stroke-width:2px,stroke-dasharray: 2 2;
    classDef db fill:#DCFCE7,stroke:#15803D,stroke-width:2px;
```
