Interaktive Visualisierung der physischen Datenrepräsentation in PostgreSQL

Autor: Daniel Hristov
Hochschule: Technische Universität Berlin
Fachgebiet: Datenbanken und Informationssysteme (DIMA)
Betreuer: Dr. Stefan Halfpap
Studiengang: Wirtschaftsinformatik (B. Sc.)
Abgabejahr: 2025

---

Projektüberblick

Dieses Projekt wurde im Rahmen einer Bachelorarbeit an der Technischen Universität Berlin entwickelt. Es ermöglicht die interaktive und grafische Analyse des physischen Seitenaufbaus von PostgreSQL-Datenbanken, insbesondere der internen Speicherstrukturen wie Page Header, Line Pointer und Heap-Tupel.

Das Tool stellt für jede gewünschte Tabelle und Page folgende Informationen dar:

-Page Header

-Line Pointer

-Heap-Tupel

-Markierte Speicherregionen (Header / Line Pointer / Free Space / Tuple Data / Special)

-Tooltips für jedes Byte mit Offset und Interpretation

-Detailansicht von Tupeln mittels CTID-Abfrage (automatische SQL-Auswertung)

-Auswahl von Tabellen und Datenseiten über Dropdown-Menüs

Die enthaltene TPC-H-Datenbasis (reduzierte Version) wird beim ersten Start des Containers automatisch importiert.

Funktionen

Visualisierung von PostgreSQL-Seiten

-Darstellung der gesamten Page als Canvas (Byte-raster)

-Einfärbung der Speicherregionen basierend auf dem Page-Header

-Darstellung der Line Pointer und Heap-Tupel als gruppierte Blöcke

-Nummerierung der Line Pointer (LP 1, LP 2, ...) und Tupel (T 1, T 2, ...)

Interaktive Analyse

-Tooltip auf Byte-Ebene

-Hervorheben des vollständigen Tupelbereichs beim Hover mit der Maus

-Anzeige aller Tupeldaten mittels CTID-Abfrage im Backend

-Fixierbares Detailpanel

Vollständig Dockerisiert

Das Projekt besteht aus:

-PostgreSQL 17.7 Container (pg17)

-Flask-Backend-Container für die API und Benutzeroberfläche

Die Datenbank wird automatisch erstellt und initialisiert.

Projektstruktur

postgresql-visualizer/
│
├── backend.py                     
├── Dockerfile                     
├── docker-compose.yml            
├── requirements.txt              
│
├── dockerinit/
│   └── 01-init.sql               
│
├── templates/
│   └── ui.html                   
│
├── static/
│   ├── css/
│   │   └── style.css
│   └── js/
│       └── script.js              
│
└── README.md

---

Voraussetzung

-Docker Desktop

-Keine lokale PostgreSQL-Installation erforderlich

Installation & Setup

1 Repository klonen

git clone https://github.com/dhristov11/postgresql-internals-visualiser.git
cd postgresql-internals-visualiser

2 Docker starten

docker compose up --build

3 Warten, bis folgende Meldungen erscheinen:

-"database system is ready to accept connections"

-"Running on http://127.0.0.1:5000

4 Webinterface öffnen

http://localhost:5000

Das System ist nun vollständig einsatzbereit.

Datenbank-Setup

Beim ersten Start:

-Der PostgreSQL-Container initialisiert die Datenbank tpch_klein

-Die Datei dockerinit/01-init.sql wird automatisch ausgeführt

-TPC-H Testdaten werden importiert

Hinweise

Das System dient ausschließlich der Visualisierung und Lehre.

Die Implementierung ist nicht sicherheitsgehärtet und nicht für Produktionsumgebungen vorgesehen.

Die Datenbasis ist stark reduziert, um unter 100 Pages zu bleiben und kurze Ladezeiten zu gewährleisten.

Didaktischer Nutzen

Diese Anwendung dient der Lehre und Visualisierung von:

• Speicherorganisation in PostgreSQL-Seiten
• interner Struktur von Heap-Tupeln
• Verwaltung von Line Pointern
• Konzepten wie Freispeicher und Spezialbereichen
• Interpretation der Page-Header-Felder (pd_lower, pd_upper, pd_special, etc.)

Damit wird ein sonst verborgener Teil von Datenbanksystemen visuell und interaktiv erfahrbar.