| Name | pypgsvg JSON |
| Version |
1.0.6
JSON |
| download |
| home_page | None |
| Summary | Generate SVG Entity Relationship Diagrams from PostgreSQL database dumps |
| upload_time | 2025-07-24 17:40:57 |
| maintainer | None |
| docs_url | None |
| author | ERD Generator |
| requires_python | >=3.8 |
| 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.
|
| keywords |
postgresql
database
erd
diagram
svg
graphviz
schema
visualization
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python ERD Generator from Postgres schema dump file
pypgsvg is an open source Python application that parses postgresql schema SQL dump files and generates
Directed Entity Relationship Diagrams (Diagraph, ERDs) using Graphviz. In a past life I had been tasked
with showing what the normalized postgresql database looks like for employers who do not want to pay for
postgres tools that have the graphical tools. There are some free ones out there but requires the installation of Java,
and does work well for what I needed it for, so admittedly this started as an academic excersise. By no
means is this even an alledgedly full throated tool, but is being adapted to take all diagraph args shortly as to
offer some options for best display of the ERD. Some versions of this saved me hours of time in explainations,
now easier to share.
```
PYTHONPATH=src python -m pytest tests/tests/
python -m src.pypgsvg Samples/schema.dump --output=test
```
## BETA, TODO, and Features
- TODO: Allow all argument options for Diagraph..
- allow show/hide FK based on cascade type.
- CSS facelift.
- Parse PostgreSQL dump files to extract table definitions and relationships
- Generate interactive SVG Entity Relationship Diagrams
- Automatic color coding for tables with accessible color palette
- Support for complex SQL structures including foreign keys, constraints, and various data types
- Table filtering to exclude temporary/utility tables
- Comprehensive test suite with >90% code coverage
## Installation
1. Install pypgsvg:
```bash
pip install .
```
2. Ensure Graphviz is installed on your system:
- **macOS**: `brew install graphviz`
- **Ubuntu/Debian**: `sudo apt-get install graphviz`
- **Windows**: Download from <https://graphviz.org/download/>
## Usage
### Basic Usage
Generate an ERD from your SQL dump file:
```bash
pypgsvg your_database.sql
```
This will create an SVG file with the same name as your input file (e.g., `your_database_erd.svg`).
### Example Output
Here's an example of the generated ERD from a sample database schema with users, posts, and comments:
[](Samples/sample_schema_erd.svg)
*Simple Blog Schema - showing basic relationships between users, posts, and comments*
---
For more complex databases, pypgsvg can handle extensive schemas with many tables and relationships:
[](Samples/schema_erd.svg)
*Complex Database Schema - demonstrating pypgsvg's ability to visualize large, real-world database structures*
*View the interactive SVG diagrams:*
- [Simple Schema Example](Samples/sample_schema_erd.svg)
- [Complex Database Schema Example](Samples/schema_erd.svg)
The diagram shows:
- **Tables** as nodes with their column definitions
- **Foreign key relationships** as directed edges between tables
- **Automatic color coding** for visual distinction
- **Accessible color palette** with proper contrast for readability
### Usage
Specify a custom output filename:
```bash
pypgsvg your_database_dump.sql --output custom_diagram.svg
```
View the diagram immediately after generation:
```bash
pypgsvg your_database_dump.sql --view
```
### Python API Usage
For programmatic use:
```python
from src.pypgsvg import parse_sql_dump, generate_erd_with_graphviz
# Load SQL dump
with open("your_database_dump.sql", "r", encoding='utf-8') as file:
sql_content = file.read()
# Parse tables and relationships
tables, foreign_keys, errors = parse_sql_dump(sql_content)
# Generate ERD
if not errors:
generate_erd_with_graphviz(tables, foreign_keys, "database_diagram")
print("ERD generated successfully!")
else:
print("Parsing errors found:", errors)
```
## Testing
Run the complete test suite with coverage:
```bash
# Run all tests with coverage
PYTHONPATH=src python -m pytest tests/tests/
# Run specific test categories
pytest -m unit # Unit tests only
pytest -m integration # Integration tests only
# Run with verbose output
pytest -v
# Generate HTML coverage report
pytest --cov-report=html
open htmlcov/index.html # View coverage report
```
## Project Structure
```text
├── src/
│ └── create_graph.py # Main application code
├── tests/
│ ├── conftest.py # Test fixtures and configuration
│ ├── test_utils.py # Tests for utility functions
│ ├── test_parser.py # Tests for SQL parsing
│ ├── test_erd_generation.py # Tests for ERD generation
│ └── test_integration.py # Integration tests
├── requirements.txt # Python dependencies
├── pyproject.toml # pytest configuration
└── README.md # This file
```
## Configuration
### Table Exclusion
The application automatically excludes tables matching certain patterns (defined in `should_exclude_table`):
- Views (`vw_`)
- Backup tables (`bk`)
- Temporary fix tables (`fix`)
- Duplicate tables (`dups`, `duplicates`)
- Match tables (`matches`)
- Version logs (`versionlog`)
- Old tables (`old`)
- Member data (`memberdata`)
### Color Palette
The ERD uses an accessible color palette with automatic contrast calculation for text readability following WCAG guidelines.
## Supported SQL Features
- `CREATE TABLE` statements with various column types
- `CREATE TABLE IF NOT EXISTS`
- `ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY`
- Quoted identifiers
- Complex data types (numeric, timestamp, jsonb, etc.)
- Multiple constraint variations
## Error Handling
The application includes comprehensive error handling for:
- Malformed SQL syntax
- Missing table references in foreign keys
- Unicode encoding issues
- File reading errors
## Contributing
1. Follow PEP 8 style guidelines
2. Write tests for new functionality
3. Maintain >90% test coverage
4. Use type hints where appropriate
5. Update documentation as needed
## Dependencies
- `graphviz>=0.20.1` - For generating diagrams
- `pytest>=7.4.0` - Testing framework
- `pytest-cov>=4.1.0` - Coverage reporting
- `pytest-mock>=3.11.0` - Mocking utilities
Raw data
{
"_id": null,
"home_page": null,
"name": "pypgsvg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "postgresql, database, erd, diagram, svg, graphviz, schema, visualization",
"author": "ERD Generator",
"author_email": "Daniel Blackburn <daniel@example.com>",
"download_url": "https://files.pythonhosted.org/packages/bd/42/1a10f04f6873c0b969061815f0bd33f3e0a267abb989dc685cf8528746ee/pypgsvg-1.0.6.tar.gz",
"platform": null,
"description": "# Python ERD Generator from Postgres schema dump file\n\npypgsvg is an open source Python application that parses postgresql schema SQL dump files and generates \nDirected Entity Relationship Diagrams (Diagraph, ERDs) using Graphviz. In a past life I had been tasked\nwith showing what the normalized postgresql database looks like for employers who do not want to pay for \npostgres tools that have the graphical tools. There are some free ones out there but requires the installation of Java, \nand does work well for what I needed it for, so admittedly this started as an academic excersise. By no \nmeans is this even an alledgedly full throated tool, but is being adapted to take all diagraph args shortly as to \noffer some options for best display of the ERD. Some versions of this saved me hours of time in explainations, \nnow easier to share.\n\n\n```\n PYTHONPATH=src python -m pytest tests/tests/ \n python -m src.pypgsvg Samples/schema.dump --output=test\n```\n\n\n\n## BETA, TODO, and Features\n- TODO: Allow all argument options for Diagraph..\n - allow show/hide FK based on cascade type. \n - CSS facelift.\n- Parse PostgreSQL dump files to extract table definitions and relationships\n- Generate interactive SVG Entity Relationship Diagrams\n- Automatic color coding for tables with accessible color palette\n- Support for complex SQL structures including foreign keys, constraints, and various data types\n- Table filtering to exclude temporary/utility tables\n- Comprehensive test suite with >90% code coverage\n\n## Installation\n\n1. Install pypgsvg:\n\n```bash\npip install .\n```\n\n2. Ensure Graphviz is installed on your system:\n - **macOS**: `brew install graphviz`\n - **Ubuntu/Debian**: `sudo apt-get install graphviz`\n - **Windows**: Download from <https://graphviz.org/download/>\n\n## Usage\n\n### Basic Usage\n\nGenerate an ERD from your SQL dump file:\n\n```bash\npypgsvg your_database.sql\n```\n\nThis will create an SVG file with the same name as your input file (e.g., `your_database_erd.svg`).\n\n### Example Output\n\nHere's an example of the generated ERD from a sample database schema with users, posts, and comments:\n\n[](Samples/sample_schema_erd.svg)\n\n*Simple Blog Schema - showing basic relationships between users, posts, and comments*\n\n---\n\nFor more complex databases, pypgsvg can handle extensive schemas with many tables and relationships:\n\n[](Samples/schema_erd.svg)\n\n*Complex Database Schema - demonstrating pypgsvg's ability to visualize large, real-world database structures*\n\n*View the interactive SVG diagrams:*\n\n- [Simple Schema Example](Samples/sample_schema_erd.svg)\n- [Complex Database Schema Example](Samples/schema_erd.svg)\n\nThe diagram shows:\n\n- **Tables** as nodes with their column definitions\n- **Foreign key relationships** as directed edges between tables\n- **Automatic color coding** for visual distinction\n- **Accessible color palette** with proper contrast for readability\n\n### Usage\n\nSpecify a custom output filename:\n\n```bash\npypgsvg your_database_dump.sql --output custom_diagram.svg\n```\n\nView the diagram immediately after generation:\n\n```bash\npypgsvg your_database_dump.sql --view\n```\n\n### Python API Usage\n\nFor programmatic use:\n\n```python\nfrom src.pypgsvg import parse_sql_dump, generate_erd_with_graphviz\n\n# Load SQL dump\nwith open(\"your_database_dump.sql\", \"r\", encoding='utf-8') as file:\n sql_content = file.read()\n\n# Parse tables and relationships\ntables, foreign_keys, errors = parse_sql_dump(sql_content)\n\n# Generate ERD\nif not errors:\n generate_erd_with_graphviz(tables, foreign_keys, \"database_diagram\")\n print(\"ERD generated successfully!\")\nelse:\n print(\"Parsing errors found:\", errors)\n```\n\n## Testing\n\nRun the complete test suite with coverage:\n\n```bash\n# Run all tests with coverage\nPYTHONPATH=src python -m pytest tests/tests/\n\n\n# Run specific test categories\npytest -m unit # Unit tests only\npytest -m integration # Integration tests only\n\n# Run with verbose output\npytest -v\n\n# Generate HTML coverage report\npytest --cov-report=html\nopen htmlcov/index.html # View coverage report\n```\n\n## Project Structure\n\n```text\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 create_graph.py # Main application code\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 conftest.py # Test fixtures and configuration\n\u2502 \u251c\u2500\u2500 test_utils.py # Tests for utility functions\n\u2502 \u251c\u2500\u2500 test_parser.py # Tests for SQL parsing\n\u2502 \u251c\u2500\u2500 test_erd_generation.py # Tests for ERD generation\n\u2502 \u2514\u2500\u2500 test_integration.py # Integration tests\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u251c\u2500\u2500 pyproject.toml # pytest configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Configuration\n\n### Table Exclusion\n\nThe application automatically excludes tables matching certain patterns (defined in `should_exclude_table`):\n\n- Views (`vw_`)\n- Backup tables (`bk`)\n- Temporary fix tables (`fix`)\n- Duplicate tables (`dups`, `duplicates`)\n- Match tables (`matches`)\n- Version logs (`versionlog`)\n- Old tables (`old`)\n- Member data (`memberdata`)\n\n### Color Palette\n\nThe ERD uses an accessible color palette with automatic contrast calculation for text readability following WCAG guidelines.\n\n## Supported SQL Features\n\n- `CREATE TABLE` statements with various column types\n- `CREATE TABLE IF NOT EXISTS`\n- `ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY`\n- Quoted identifiers\n- Complex data types (numeric, timestamp, jsonb, etc.)\n- Multiple constraint variations\n\n## Error Handling\n\nThe application includes comprehensive error handling for:\n\n- Malformed SQL syntax\n- Missing table references in foreign keys\n- Unicode encoding issues\n- File reading errors\n\n## Contributing\n\n1. Follow PEP 8 style guidelines\n2. Write tests for new functionality\n3. Maintain >90% test coverage\n4. Use type hints where appropriate\n5. Update documentation as needed\n\n## Dependencies\n\n- `graphviz>=0.20.1` - For generating diagrams\n- `pytest>=7.4.0` - Testing framework\n- `pytest-cov>=4.1.0` - Coverage reporting\n- `pytest-mock>=3.11.0` - Mocking utilities\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 blackburnd\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Generate SVG Entity Relationship Diagrams from PostgreSQL database dumps",
"version": "1.0.6",
"project_urls": {
"Bug Reports": "https://github.com/danielblackburn/pypgsvg/issues",
"Documentation": "https://github.com/danielblackburn/pypgsvg#readme",
"Homepage": "https://github.com/danielblackburn/pypgsvg",
"Source Code": "https://github.com/danielblackburn/pypgsvg"
},
"split_keywords": [
"postgresql",
" database",
" erd",
" diagram",
" svg",
" graphviz",
" schema",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4411f8b01863e87c4cf7344c10e6a2b5da0c044062ce273ef9c40cd31404478c",
"md5": "a35397f99bfb8a0fe7c0a9adce401b06",
"sha256": "e893720f13167e634a2da4cb1f7b12c9cf49e378b51628013c2f1481bc1fb80b"
},
"downloads": -1,
"filename": "pypgsvg-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a35397f99bfb8a0fe7c0a9adce401b06",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21874,
"upload_time": "2025-07-24T17:40:56",
"upload_time_iso_8601": "2025-07-24T17:40:56.005328Z",
"url": "https://files.pythonhosted.org/packages/44/11/f8b01863e87c4cf7344c10e6a2b5da0c044062ce273ef9c40cd31404478c/pypgsvg-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bd421a10f04f6873c0b969061815f0bd33f3e0a267abb989dc685cf8528746ee",
"md5": "9c4df943795ed1234a3b6a3205a676e5",
"sha256": "ddfe6b72ed7578b54aa55f05266f9e812e609b8e8da982159854ebf5b08ddf35"
},
"downloads": -1,
"filename": "pypgsvg-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "9c4df943795ed1234a3b6a3205a676e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 161752,
"upload_time": "2025-07-24T17:40:57",
"upload_time_iso_8601": "2025-07-24T17:40:57.138608Z",
"url": "https://files.pythonhosted.org/packages/bd/42/1a10f04f6873c0b969061815f0bd33f3e0a267abb989dc685cf8528746ee/pypgsvg-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 17:40:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "danielblackburn",
"github_project": "pypgsvg",
"github_not_found": true,
"lcname": "pypgsvg"
}
