# ankane/pgsync architecture

> Architecture diagram of the GitHub repository ankane/pgsync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ankane/pgsync
- Repository: https://github.com/ankane/pgsync
- Video tour (about a minute): https://gitdiagram.com/ankane/pgsync/video

## Overview

pgsync is a command-line tool for selectively copying PostgreSQL data between a source and a destination, with optional schema transfer and data anonymization. The main workflow parses CLI options, resolves configuration and table/group selections, then performs schema and/or table synchronization. Table transfers can run in parallel and support filtered rows, conflict handling, batching, and constraint controls. The README also documents initialization, sequence handling, and table listing. Some orchestration and sequence implementation details are unsampled, so those connections are limited to documented behavior or shown calls.

Main entry points: [`lib/pgsync/sync.rb`](https://github.com/ankane/pgsync/blob/master/lib/pgsync/sync.rb) (Sync coordinator), [`lib/pgsync/data_source.rb`](https://github.com/ankane/pgsync/blob/master/lib/pgsync/data_source.rb) (Database adapter), [`lib/pgsync/table_sync.rb`](https://github.com/ankane/pgsync/blob/master/lib/pgsync/table_sync.rb) (Table scheduler), [`lib/pgsync/schema_sync.rb`](https://github.com/ankane/pgsync/blob/master/lib/pgsync/schema_sync.rb) (Schema transfer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and setup"]
  node_client["CLI client<br/>[client.rb]"]
  node_initializer["Config initializer<br/>[init.rb]"]
  node_config_template["Config template<br/>[config.yml]"]
end

subgraph group_planning["Sync planning"]
  node_sync["Sync coordinator<br/>[sync.rb]"]
  node_resolver["Task resolver<br/>[task_resolver.rb]"]
  node_table_model["Table identity<br/>[table.rb]"]
end

subgraph group_transfer["Schema and data transfer"]
  node_schema_sync["Schema transfer<br/>[schema_sync.rb]"]
  node_schema_tools["Postgres dump tools"]
  node_table_sync["Table scheduler<br/>[table_sync.rb]"]
  node_table_task["Table transfer task<br/>[task.rb]"]
  node_sequence_model["Sequence identity<br/>[sequence.rb]"]
end

subgraph group_connections["Database access"]
  node_data_source["Database adapter<br/>[data_source.rb]"]
end

node_operator(("Operator"))
node_source_db[("Source PostgreSQL")]
node_destination_db[("Destination PostgreSQL")]

node_operator -->|"runs commands"| node_client
node_client -->|"dispatches init"| node_initializer
node_client -->|"dispatches sync"| node_sync
node_initializer -->|"reads template"| node_config_template
node_sync -->|"creates adapters"| node_data_source
node_data_source -->|"queries"| node_source_db
node_data_source -->|"queries"| node_destination_db
node_sync -->|"resolves tasks"| node_resolver
node_resolver -->|"builds table IDs"| node_table_model
node_resolver -->|"lists tables"| node_data_source
node_sync -->|"runs schema transfer"| node_schema_sync
node_schema_sync -->|"pipes dump to restore"| node_schema_tools
node_schema_sync -->|"creates schemas"| node_data_source
node_sync -->|"runs table transfer"| node_table_sync
node_table_sync -->|"runs tasks"| node_table_task
node_table_task -->|"copies rows"| node_data_source
node_table_sync -->|"builds sequence IDs"| node_sequence_model
node_table_task -->|"applies data rules"| node_destination_db
node_operator -->|"selects tables and rows"| node_sync
node_sync -->|"schema-first or schema-only"| node_schema_sync
node_sync -->|"supports filtered and batched sync"| node_table_sync
node_table_sync -.->|"updates sequences"| node_destination_db

click node_client "https://github.com/ankane/pgsync/blob/master/lib/pgsync/client.rb"
click node_initializer "https://github.com/ankane/pgsync/blob/master/lib/pgsync/init.rb"
click node_config_template "https://github.com/ankane/pgsync/blob/master/config.yml"
click node_sync "https://github.com/ankane/pgsync/blob/master/lib/pgsync/sync.rb"
click node_resolver "https://github.com/ankane/pgsync/blob/master/lib/pgsync/task_resolver.rb"
click node_table_model "https://github.com/ankane/pgsync/blob/master/lib/pgsync/table.rb"
click node_schema_sync "https://github.com/ankane/pgsync/blob/master/lib/pgsync/schema_sync.rb"
click node_table_sync "https://github.com/ankane/pgsync/blob/master/lib/pgsync/table_sync.rb"
click node_table_task "https://github.com/ankane/pgsync/blob/master/lib/pgsync/task.rb"
click node_sequence_model "https://github.com/ankane/pgsync/blob/master/lib/pgsync/sequence.rb"
click node_data_source "https://github.com/ankane/pgsync/blob/master/lib/pgsync/data_source.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_initializer,node_config_template toneBlue
class node_sync,node_resolver,node_table_model,node_source_db,node_destination_db toneAmber
class node_schema_sync,node_schema_tools,node_table_sync,node_table_task,node_sequence_model toneMint
class node_data_source toneRose
class node_operator toneIndigo
```

## Components

### CLI and setup

- [CLI client](https://github.com/ankane/pgsync/blob/master/lib/pgsync/client.rb): `lib/pgsync/client.rb`
- [Config initializer](https://github.com/ankane/pgsync/blob/master/lib/pgsync/init.rb): `lib/pgsync/init.rb`
- [Config template](https://github.com/ankane/pgsync/blob/master/config.yml): `config.yml`

### Sync planning

- [Sync coordinator](https://github.com/ankane/pgsync/blob/master/lib/pgsync/sync.rb): `lib/pgsync/sync.rb`
- [Task resolver](https://github.com/ankane/pgsync/blob/master/lib/pgsync/task_resolver.rb): `lib/pgsync/task_resolver.rb`
- [Table identity](https://github.com/ankane/pgsync/blob/master/lib/pgsync/table.rb): `lib/pgsync/table.rb`

### Schema and data transfer

- [Schema transfer](https://github.com/ankane/pgsync/blob/master/lib/pgsync/schema_sync.rb): `lib/pgsync/schema_sync.rb`
- **Postgres dump tools**
- [Table scheduler](https://github.com/ankane/pgsync/blob/master/lib/pgsync/table_sync.rb): `lib/pgsync/table_sync.rb`
- [Table transfer task](https://github.com/ankane/pgsync/blob/master/lib/pgsync/task.rb): `lib/pgsync/task.rb`
- [Sequence identity](https://github.com/ankane/pgsync/blob/master/lib/pgsync/sequence.rb): `lib/pgsync/sequence.rb`

### Database access

- [Database adapter](https://github.com/ankane/pgsync/blob/master/lib/pgsync/data_source.rb): `lib/pgsync/data_source.rb`

### Other components

- **Operator**
- **Source PostgreSQL**
- **Destination PostgreSQL**

## Connections

- Operator → CLI client: runs commands (evidence: `README.md`)
- CLI client → Config initializer: dispatches init (evidence: `lib/pgsync/client.rb`)
- CLI client → Sync coordinator: dispatches sync (evidence: `lib/pgsync/client.rb`)
- Config initializer → Config template: reads template (evidence: `lib/pgsync/init.rb`)
- Sync coordinator → Database adapter: creates adapters (evidence: `lib/pgsync/sync.rb`)
- Database adapter → Source PostgreSQL: queries (evidence: `lib/pgsync/data_source.rb`)
- Database adapter → Destination PostgreSQL: queries (evidence: `lib/pgsync/data_source.rb`)
- Sync coordinator → Task resolver: resolves tasks (evidence: `lib/pgsync/sync.rb`)
- Task resolver → Table identity: builds table IDs (evidence: `lib/pgsync/task_resolver.rb`)
- Task resolver → Database adapter: lists tables (evidence: `lib/pgsync/task_resolver.rb`)
- Sync coordinator → Schema transfer: runs schema transfer (evidence: `lib/pgsync/sync.rb`)
- Schema transfer → Postgres dump tools: pipes dump to restore (evidence: `lib/pgsync/schema_sync.rb`)
- Schema transfer → Database adapter: creates schemas (evidence: `lib/pgsync/schema_sync.rb`)
- Sync coordinator → Table scheduler: runs table transfer (evidence: `lib/pgsync/sync.rb`)
- Table scheduler → Table transfer task: runs tasks (evidence: `lib/pgsync/table_sync.rb`)
- Table transfer task → Database adapter: copies rows (evidence: `lib/pgsync/task.rb`)
- Table scheduler → Sequence identity: builds sequence IDs (evidence: `lib/pgsync/table_sync.rb`)
- Table transfer task → Destination PostgreSQL: applies data rules (evidence: `README.md`)
- Operator → Sync coordinator: selects tables and rows (evidence: `README.md`)
- Sync coordinator → Schema transfer: schema-first or schema-only (evidence: `README.md`)
- Sync coordinator → Table scheduler: supports filtered and batched sync (evidence: `README.md`)
- Table scheduler → Destination PostgreSQL: updates sequences
