Metadata-Version: 2.4
Name: pypgsvg
Version: 1.1.2
Summary: Generate SVG Entity Relationship Diagrams from PostgreSQL database dump files
Author: blackburnd@gmail.com
Author-email: Daniel Blackburn <daniel@example.com>
License: MIT License
        
        Copyright (c) 2025 blackburnd
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/blackburnd/pypgsvg
Project-URL: Bug Reports, https://github.com/blackburnd/pypgsvg/issues
Project-URL: Source Code, https://github.com/blackburnd/pypgsvg
Project-URL: Documentation, https://github.com/blackburnd/pypgsvg#readme
Keywords: postgresql,database,erd,diagram,svg,graphviz,schema,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: graphviz>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# pypgsvg - Lightweight PostgreSQL ERD Generator

`pypgsvg` is a **lightweight, enterprise-ready** Python tool that generates interactive Entity Relationship Diagrams (ERDs) from PostgreSQL schema dump files. With **only Graphviz as a dependency**, it's perfect for enterprise scripting, CI/CD pipelines, and rapid deployment scenarios.

## 🚀 Enterprise Features

- **Zero-dependency Python tool** (except Graphviz)
- **Interactive SVG output** with navigation and selection tools
- **Scriptable and automatable** for enterprise workflows
- **Quick deployment** - install and run in seconds
- **Self-contained** - no database connections required
- **Cross-platform** support (Windows, macOS, Linux)

---

## ✨ Interactive Features

### 🎯 Selection & Navigation Tools
- **Smart table/edge selection** - Click any element to view detailed SQL
- **Miniature overview** with viewport indicator for large schemas
- **Drag & drop containers** - Reposition windows anywhere
- **Resizable panels** - Customize your workspace layout

### 📋 Copy & Export Tools
- **One-click copy** - Copy table definitions, foreign keys, or trigger SQL
- **Download selection details** - Export selected elements as formatted text
- **Emoji-free output** - Enterprise-friendly plain text exports

### 🖱️ Interactive Controls
- **Minimize/maximize** any panel to focus on your work
- **Close buttons** for distraction-free viewing
- **Pan and zoom** with mouse or miniature navigator
- **Keyboard shortcuts** (ESC/R to reset view)

### 🎨 Visual Enhancements
- **Color-coded tables** with accessible contrast
- **Hover effects** for better element identification
- **Professional styling** suitable for documentation and presentations

---

## 📦 Installation

**Lightweight setup - only 2 steps:**

1. Install `pypgsvg`:
   ```bash
   pip install pypgsvg
   ```

2. Install Graphviz (the only external dependency):
   - **macOS**: `brew install graphviz`
   - **Ubuntu/Debian**: `sudo apt-get install graphviz`
   - **CentOS/RHEL**: `sudo yum install graphviz`
   - **Windows**: Download from [Graphviz.org](https://graphviz.org/download/)

**That's it!** Ready for enterprise deployment.

---

## 🛠️ Enterprise Usage

### Quick Start - Schema Analysis
```bash
# Generate interactive ERD from schema dump
pypgsvg schema.dump --output database_erd --view

# Enterprise automation (CI/CD ready)
pypgsvg schema.dump --output docs/database_diagram --rankdir TB --node-sep 4
```

### Advanced Enterprise Options
```bash
# Large schema optimization
pypgsvg large_schema.dump --packmode graph --rank-sep 3 --hide-standalone

# Custom layout for documentation
pypgsvg schema.dump --rankdir LR --fontsize 20 --node-fontsize 16 --output presentation_erd
```

## Usage
### Get Your PostgreSQL Schema
If you don't have a schema dump, generate one with `pg_dump`:

```bash
# Standard schema export (most common)
pg_dump -h your-host -d database -U username -s --no-owner --no-privileges > schema.dump

# Comprehensive export with triggers and functions
pg_dump -h your-host -d database -U username -s -O -F plain --disable-triggers --encoding=UTF8 > schema.dump
```

Or use our [sample schema](https://github.com/blackburnd/pypgsvg/blob/main/Samples/complex_schema.dump) for testing.

### Interactive ERD Generation

**Basic usage:**
```bash
pypgsvg schema.dump --output my_database_erd --view
```

**Enterprise production:**
```bash
pypgsvg schema.dump \
  --output docs/database_architecture \
  --rankdir TB \
  --node-sep 4 \
  --packmode graph \
  --rank-sep 3 \
  --hide-standalone
```

**The generated SVG includes:**
- 🖱️ **Interactive selection** - Click tables/edges to view SQL details
- 📱 **Miniature navigator** - Overview panel for large schemas  
- 📋 **Copy/download tools** - Export selected elements
- 🎨 **Resizable panels** - Customize your workspace
- ⌨️ **Keyboard shortcuts** - ESC/R to reset view

> **Note:** For full interactivity, open the SVG file locally in your browser. GitHub restricts JavaScript for security.

### 🎬 Quick Demo

[[🎯 View Interactive Example](https://github.com/blackburnd/pypgsvg/blob/main/Samples/complex_schema.svg)] 

[![https://live.staticflickr.com/65535/54725569515_1a265e1695.jpghttps://flic.kr/ps/46D1Th)

**Try it yourself:**
```bash
# Download sample and generate interactive ERD
wget https://github.com/blackburnd/pypgsvg/raw/main/Samples/complex_schema.dump
pypgsvg schema.dump --output demo_erd --view
```

### Scriptable API

Perfect for automation and enterprise workflows:

```python
from pypgsvg import parse_sql_dump, generate_erd_with_graphviz

# Parse schema dump
with open("schema.dump", "r", encoding='utf-8') as file:
    sql_content = file.read()

# Extract database structure  
tables, foreign_keys, triggers, errors = parse_sql_dump(sql_content)

# Generate interactive ERD
if not errors:
    generate_erd_with_graphviz(
        tables=tables,
        foreign_keys=foreign_keys, 
        output_file="enterprise_diagram",
        rankdir='TB',
        packmode='graph'
    )
    print("✅ Enterprise ERD generated successfully!")
else:
    print("⚠️ Parsing errors:", errors)
```

---

## 🎯 Interactive Components

The generated SVG includes several interactive panels that can be moved, resized, and minimized:
### 📊 Metadata Panel
Displays comprehensive information about your database schema:
- **Schema statistics** (table count, columns, relationships)
- **Generation parameters** used
- **File information** and timestamps
- **Interactive controls** (minimize, close, drag to reposition)

[![Metadata Panel](https://live.staticflickr.com/65535/54701918384_2debb75e13_z.jpg)](https://flic.kr/s/aHBqjCpNX1)

### 🗺️ Miniature Overview
Navigate large schemas effortlessly:
- **Interactive minimap** with viewport indicator
- **Click to jump** to specific schema areas
- **Drag viewport** for precise navigation
- **Resizable panel** - make it larger for detailed navigation

[![Overview Panel](https://live.staticflickr.com/65535/54702015980_bca2aedb3e_c.jpg)](https://flic.kr/s/aHBqjCpNX1)

### 🔍 Selection Details
View and export detailed SQL information:
- **Table definitions** with column details and constraints
- **Foreign key relationships** with full SQL syntax
- **Trigger information** including execution details
- **Copy button** for instant clipboard access
- **Download button** for formatted text export
- **Enterprise-friendly** emoji-free output option

[![Selection Panel](https://flic.kr/p/2rnUkss](https://flic.kr/s/aHBqjCpNX1)
**Example selection output:**
```
📊 Selected Tables
==================
public_franchises
public_association_map
public_ecommerce
...

🔗 Foreign Key Relationships  
============================
🔑 franchise_id → id
ALTER TABLE ONLY public.association_map
    ADD CONSTRAINT association_map_franchise_id_fkey 
    FOREIGN KEY (franchise_id) REFERENCES public.franchises(id) 
    ON DELETE CASCADE;
```

---

## 🏢 Enterprise Deployment

### CI/CD Integration
```yaml
# GitHub Actions example
- name: Generate Database Documentation
  run: |
    pip install pypgsvg
    sudo apt-get install graphviz
    pypgsvg schemas/production.dump --output docs/database_erd
    
# Docker deployment
FROM python:3.9-slim
RUN apt-get update && apt-get install -y graphviz && rm -rf /var/lib/apt/lists/*
RUN pip install pypgsvg
COPY schema.dump .
RUN pypgsvg schema.dump --output database_diagram
```

### Automation Scripts
```bash
#!/bin/bash
# Enterprise schema documentation automation
DATE=$(date +%Y%m%d)
pg_dump -h $DB_HOST -d $DB_NAME -U $DB_USER -s > schema_$DATE.dump
pypgsvg schema_$DATE.dump --output docs/database_erd_$DATE --hide-standalone
echo "✅ Database documentation updated: docs/database_erd_$DATE.svg"
```

---

## 🧪 Testing & Quality

**Enterprise-grade testing** with comprehensive coverage:

```bash
# Run full test suite (no dependencies required)
python -m pytest tests/tests/

# Generate detailed coverage report
python -m pytest tests/tests/ --cov=src --cov-report=html
open htmlcov/index.html
```

**Quality metrics:**
- ✅ **95%+ code coverage** 
- ✅ **70+ comprehensive tests**
- ✅ **Enterprise PYTHONPATH support**
- ✅ **Cross-platform compatibility**

---

## 🏗️ Architecture & Performance

### Lightweight Design
```text
📦 pypgsvg/
├── 🐍 Pure Python core (~450 lines)
├── 🎨 CSS styling (~200 lines)  
├── ⚡ JavaScript interactivity (~2000 lines)
├── 🧪 Comprehensive tests (~1000+ lines)
└── 📚 Zero runtime dependencies (except Graphviz)
```

**Performance characteristics:**
- **Fast parsing** - Processes large schemas in seconds
- **Memory efficient** - Minimal footprint for enterprise deployment
- **Scalable output** - Handles schemas with hundreds of tables
- **Quick startup** - No database connections or heavy frameworks

### Enterprise-Ready Features
- **🔒 Security-focused** - No network requirements, processes local files only
- **📋 Audit-friendly** - Deterministic output for version control
- **🚀 Container-ready** - Minimal Docker image size
- **⚙️ Configurable** - Extensive customization options
- **📊 Monitoring** - Built-in error reporting and validation

---

## ⚙️ Configuration & Customization

### Advanced Layout Options
```bash
# Horizontal layout for wide displays
pypgsvg schema.dump --rankdir LR --node-sep 3 --rank-sep 2

# Compact layout for presentations  
pypgsvg schema.dump --packmode graph --fontsize 16 --node-fontsize 14

# Large schema optimization
pypgsvg schema.dump --hide-standalone --esep 8 --rank-sep 4
```

### Table Filtering (Automatic)
Enterprise-focused exclusions for cleaner diagrams:
- **Views** (`vw_*`) - Database views  
- **Backup tables** (`*_bk`, `*_backup`) - Temporary backup data
- **Utility tables** (`*_temp`, `*_tmp`) - Temporary processing tables
- **Log tables** (`*_log`, `*_audit`) - Audit and logging tables
- **Duplicate tables** (`*_dups`, `*_duplicates`) - Data cleanup tables
- **Version tables** (`*_old`, `*_archive`) - Historical data tables

### Color & Accessibility
- **WCAG-compliant** color palette with proper contrast ratios
- **Automatic text color** calculation for readability
- **Color-blind friendly** palette selection
- **High-contrast mode** for professional presentations

---

## 🔧 Supported Database Features

### SQL Parsing Capabilities
- ✅ **CREATE TABLE** statements with all PostgreSQL data types
- ✅ **ALTER TABLE** constraints and foreign keys
- ✅ **Triggers** with BEFORE/AFTER/INSTEAD OF events
- ✅ **Primary keys** and unique constraints
- ✅ **Complex data types** (JSON, arrays, custom types)
- ✅ **Quoted identifiers** and schema-qualified names
- ✅ **Unicode support** with proper encoding handling

### Advanced SQL Features
```sql
-- Fully supported constructs
CREATE TABLE "complex_table" (
    id SERIAL PRIMARY KEY,
    data JSONB NOT NULL,
    tags TEXT[],
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Trigger support
CREATE TRIGGER update_modified_time 
    BEFORE UPDATE ON complex_table 
    FOR EACH ROW EXECUTE FUNCTION update_timestamp();

-- Foreign key variations
ALTER TABLE orders 
    ADD CONSTRAINT fk_customer 
    FOREIGN KEY (customer_id) 
    REFERENCES customers(id) 
    ON DELETE CASCADE ON UPDATE RESTRICT;
```

---

## 🚨 Error Handling & Reliability

**Production-ready error management:**
- **Graceful degradation** - Continues processing despite individual parsing errors
- **Detailed error reporting** - Specific line numbers and context
- **Encoding resilience** - Handles various character encodings
- **Malformed SQL recovery** - Attempts to extract partial information
- **Validation checks** - Ensures output integrity

**Enterprise logging:**
```python
# Built-in error collection for monitoring
tables, foreign_keys, triggers, errors = parse_sql_dump(sql_content)

if errors:
    for error in errors:
        log.warning(f"Schema parsing issue: {error}")
    # Continue with partial results
```

---

## 🤝 Contributing

We welcome enterprise users and contributors:

1. **Code quality** - Follow PEP 8 and maintain >95% test coverage
2. **Enterprise focus** - Consider automation and deployment scenarios  
3. **Performance** - Optimize for large schemas and CI/CD usage
4. **Documentation** - Update examples for enterprise use cases
5. **Testing** - Add tests for new SQL patterns and edge cases

---

## 📋 Dependencies

**Minimal dependency footprint for enterprise deployment:**

### Required
- **Python 3.8+** (standard in most enterprise environments)
- **Graphviz** (system package, widely available)

### Development/Testing Only
- `pytest>=7.0.0` - Testing framework
- `pytest-cov>=4.0.0` - Coverage reporting  

**That's it!** No heavy frameworks, databases, or complex runtime dependencies.

---

## 📄 License & Enterprise Usage

This project is released under the MIT License, making it suitable for:
- ✅ **Commercial use** in enterprise environments
- ✅ **Modification** for internal requirements  
- ✅ **Distribution** within organizations
- ✅ **Private use** without attribution requirements

Perfect for enterprise adoption with minimal legal overhead.
