# maheshpulivarthi18/postgres-connector architecture

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

- Interactive diagram: https://gitdiagram.com/maheshpulivarthi18/postgres-connector
- Repository: https://github.com/maheshpulivarthi18/postgres-connector

## Overview

Oceanic Postgres ORM is an async Python ORM over PostgreSQL. Applications declare typed models and filters, then call the connector for CRUD or streaming; it builds SQL, executes through a connection pool, hydrates model instances, and batch-resolves requested relations. Separate capabilities cover additive migrations, transactions, stored procedures, and PostgreSQL Pub/Sub. The map emphasizes these product stages; several links rely on the connector’s SOURCE INDEX references or README rather than inspected call sites, so unsampled implementation details are not expanded.

Main entry points: [`src/postgres_connector/connector.py`](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/connector.py) (ORM connector), [`src/postgres_connector/model.py`](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/model.py) (Typed models), [`src/postgres_connector/pool.py`](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/pool.py) (Async connection pool), [`src/postgres_connector/query_builder.py`](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/query_builder.py) (SQL query builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Models and filters"]
  node_model["Typed models<br/>[model.py]"]
  node_fields["Fields and relations<br/>[fields.py]"]
  node_registry["Model registry<br/>[registry.py]"]
  node_filter["Filter types<br/>[types.py]"]
end

subgraph group_queries["Query runtime"]
  node_connector["ORM connector<br/>[connector.py]"]
  node_querybuilder["SQL query builder<br/>[query_builder.py]"]
  node_relations["Relation resolver"]
  node_pool["Async connection pool<br/>[pool.py]"]
  node_exceptions["Typed errors<br/>[exceptions.py]"]
end

subgraph group_schema["Schema management"]
  node_migrator["Schema migrator<br/>[migrator.py]"]
end

subgraph group_transactions["Transactions"]
  node_transaction["Transaction context<br/>[transaction.py]"]
end

subgraph group_extensions["Database features"]
  node_procedures["Stored procedures<br/>[procedures.py]"]
  node_pubsub["Postgres Pub/Sub<br/>[pool.py]"]
  node_streaming["Result streaming<br/>[connector.py]"]
  node_upsert["Upsert operations<br/>[connector.py]"]
  node_locking["Row locking<br/>[query_builder.py]"]
end

node_app(("Application"))
node_postgres[("PostgreSQL")]

node_app -->|"calls"| node_connector
node_app -->|"declares"| node_model
node_model -->|"uses declarations"| node_fields
node_model -->|"registers models"| node_registry
node_app -->|"provides filters"| node_filter
node_connector -->|"builds SQL"| node_querybuilder
node_connector -->|"executes queries"| node_pool
node_pool -->|"queries"| node_postgres
node_connector -->|"resolves includes"| node_relations
node_relations -->|"batch fetches"| node_pool
node_connector -->|"hydrates rows"| node_model
node_connector -->|"maps errors"| node_exceptions
node_connector -->|"syncs schema"| node_migrator
node_migrator -->|"executes migrations"| node_pool
node_connector -->|"creates context"| node_transaction
node_transaction -->|"delegates ORM calls"| node_connector
node_connector -->|"calls procedures"| node_procedures
node_connector -->|"offers notifications"| node_pubsub
node_pubsub -->|"LISTEN and NOTIFY"| node_postgres
node_connector -->|"streams results"| node_streaming
node_connector -->|"upserts records"| node_upsert
node_querybuilder -->|"builds lock filters"| node_locking

click node_connector "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/connector.py"
click node_model "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/model.py"
click node_fields "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/fields.py"
click node_registry "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/registry.py"
click node_filter "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/types.py"
click node_querybuilder "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/query_builder.py"
click node_relations "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/relation_resolver.py"
click node_pool "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/pool.py"
click node_exceptions "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/exceptions.py"
click node_migrator "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/migrator.py"
click node_transaction "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/transaction.py"
click node_procedures "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/procedures.py"
click node_pubsub "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/pool.py"
click node_streaming "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/connector.py"
click node_upsert "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/connector.py"
click node_locking "https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/query_builder.py"

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_model,node_fields,node_registry,node_filter toneBlue
class node_connector,node_querybuilder,node_relations,node_pool,node_exceptions,node_postgres toneAmber
class node_migrator toneMint
class node_transaction toneRose
class node_procedures,node_pubsub,node_streaming,node_upsert,node_locking,node_app toneIndigo
```

## Components

### Models and filters

- [Typed models](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/model.py): `src/postgres_connector/model.py`
- [Fields and relations](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/fields.py): `src/postgres_connector/fields.py`
- [Model registry](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/registry.py): `src/postgres_connector/registry.py`
- [Filter types](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/types.py): `src/postgres_connector/types.py`

### Query runtime

- [ORM connector](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/connector.py): `src/postgres_connector/connector.py`
- [SQL query builder](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/query_builder.py): `src/postgres_connector/query_builder.py`
- [Relation resolver](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/relation_resolver.py): `src/postgres_connector/relation_resolver.py`
- [Async connection pool](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/pool.py): `src/postgres_connector/pool.py`
- [Typed errors](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/exceptions.py): `src/postgres_connector/exceptions.py`

### Schema management

- [Schema migrator](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/migrator.py): `src/postgres_connector/migrator.py`

### Transactions

- [Transaction context](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/transaction.py): `src/postgres_connector/transaction.py`

### Database features

- [Stored procedures](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/procedures.py): `src/postgres_connector/procedures.py`
- [Postgres Pub/Sub](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/pool.py): `src/postgres_connector/pool.py`
- [Result streaming](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/connector.py): `src/postgres_connector/connector.py`
- [Upsert operations](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/connector.py): `src/postgres_connector/connector.py`
- [Row locking](https://github.com/maheshpulivarthi18/postgres-connector/blob/main/src/postgres_connector/query_builder.py): `src/postgres_connector/query_builder.py`

### Other components

- **Application**
- **PostgreSQL**

## Connections

- Application → ORM connector: calls (evidence: `README.md`)
- Application → Typed models: declares (evidence: `README.md`)
- Typed models → Fields and relations: uses declarations (evidence: `src/postgres_connector/model.py`)
- Typed models → Model registry: registers models (evidence: `src/postgres_connector/registry.py`)
- Application → Filter types: provides filters (evidence: `README.md`)
- ORM connector → SQL query builder: builds SQL (evidence: `src/postgres_connector/connector.py`)
- ORM connector → Async connection pool: executes queries (evidence: `src/postgres_connector/connector.py`)
- Async connection pool → PostgreSQL: queries (evidence: `src/postgres_connector/pool.py`)
- ORM connector → Relation resolver: resolves includes (evidence: `src/postgres_connector/connector.py`)
- Relation resolver → Async connection pool: batch fetches (evidence: `src/postgres_connector/relation_resolver.py`)
- ORM connector → Typed models: hydrates rows (evidence: `src/postgres_connector/connector.py`)
- ORM connector → Typed errors: maps errors (evidence: `src/postgres_connector/connector.py`)
- ORM connector → Schema migrator: syncs schema (evidence: `src/postgres_connector/connector.py`)
- Schema migrator → Async connection pool: executes migrations (evidence: `src/postgres_connector/migrator.py`)
- ORM connector → Transaction context: creates context (evidence: `src/postgres_connector/transaction.py`)
- Transaction context → ORM connector: delegates ORM calls (evidence: `src/postgres_connector/transaction.py`)
- ORM connector → Stored procedures: calls procedures (evidence: `src/postgres_connector/connector.py`)
- ORM connector → Postgres Pub/Sub: offers notifications (evidence: `README.md`)
- Postgres Pub/Sub → PostgreSQL: LISTEN and NOTIFY (evidence: `src/postgres_connector/pool.py`)
- ORM connector → Result streaming: streams results (evidence: `README.md`)
- ORM connector → Upsert operations: upserts records (evidence: `README.md`)
- SQL query builder → Row locking: builds lock filters (evidence: `README.md`)
