pgMui User Guide

pgMui is a minimal UI for PostgreSQL: you can connect to a database, write SQL, and run queries.

This guide describes the application as shipped in the distributable bundle.

Getting pgMui

Distributable bundle

The files needed to run the application are in pgMui.zip, stored next to this guide. Unpack it, then follow the instructions under Install and run.

The archive contains:

`src/`	application code – app.py is the entry point
`LICENSE`	MIT license
`README.md`	instructions
`requirements.txt`	required Python packages
`run.sh`	script to create the virtual environment and start pgMui

Source repository

The full source is available at Codeberg^🏔️.

Requirements

You need:

Python 3.12 or newer
A running PostgreSQL server you can reach from this machine
A terminal (to unpack the bundle and start the app)
On Debian/Ubuntu, Qt's xcb plugin needs libxcb-cursor0:
```
bashsudo apt install libxcb-cursor0
```

Install and run

In the directory that contains pgMui.zip:

bashunzip pgMui.zip

Then:

bashcd pgMui
./run.sh

The first launch of run.sh creates a virtual environment in .venv/ and installs the packages from requirements.txt. Later launches reuse that environment.

Or, by hand:

bashpython3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python src/app.py

Using pgMui

The main window

The window is split horizontally:

Left — SQL editor (monospace, line numbers, syntax highlighting)
Right — result table

The toolbar (left to right):

Control	What it does
Disconnect	Close the current database connection
Run	Execute SQL `[Ctrl+Return]`
Tables	Open the tables window
Clear	Empty the editor and the result table
Dark/Light	Toggle the theme
Quit	Exit the application `[Ctrl+Q]`

The status bar shows the current connection on the left (user@host:port/dbname) and a short result notice on the right.

On first start the editor contains a sample query:

sql-> write SQL, then Run (Ctrl+Return)
SELECT current_user, current_database(), now();

Connect to a database

The connection dialog opens when a database is needed.

Fill in Host, Port, Database, User, and Password.
Click Connect.

Defaults (until you have saved a connection) are host localhost, port 5432, and database postgres. The user field starts empty.

A successful connection stores those values for the next session. The status bar then shows user@host:port/dbname, and Run / Disconnect become available.

If the server refuses the connection, a Connection failed dialog shows the error. Nothing is saved in that case.

To use another database, choose Disconnect. The connection dialog opens when a new connection is needed.

Write SQL

Type in the editor on the left. The editor:

uses a fixed-width font
shows line numbers
highlights SQL keywords, types, strings, numbers, identifiers, and comments
does not wrap long lines
treats tab width as four spaces

When the editor is empty, the placeholder reads Write SQL here.

Run a query

Connect if you are not already connected (Run stays disabled until then).
Click Run, or press [Ctrl+Return].

What gets executed:

If there is a selection, only the selected text is sent.
Otherwise the whole editor is sent (leading and trailing whitespace stripped).

An empty editor or selection does nothing.

While the query runs, the mouse pointer becomes a wait cursor. On failure, a Query failed dialog shows the error.

Read the results

SELECT (and other SQL statements that return rows) fill the table on the right:

column headers come from the query
NULL is shown as italic NULL
rows are selectable; cells are not editable
columns resize to their contents

The status bar reports N row(s). If more than 120 rows were produced, only the first 120 are shown and the notice ends with (truncated).

Statements that do not return rows (for example INSERT, UPDATE, DELETE) leave the table empty. The status bar reports OK — N row(s) affected.

Clear, theme, and quit

Clear wipes the editor and the result table. The connection is unchanged.
Dark /Light switches the Fusion colour scheme. The choice is remembered. The button label is the scheme you would switch to.
Quit or [Ctrl+Q] closes the window and the database connection. Closing the window from the window manager does the same.

Tables window

Clicking Tables opens a window that lists the tables in the current database, and the content of the selected table. The list is refreshed each time a query is run in the main window.

Saved settings

pgMui stores settings with Qt. On Linux they typically live under ~/.config/pgMui/.

What is saved after a successful connect:

host, port, database, user
password (see the note below)
whether the UI is dark or light

On the next start, the connection dialog is pre-filled from those values. If a password was stored, the password field shows the placeholder Password is saved!.

The colour scheme defaults to the desktop preference until you toggle it.

Behaviour notes

Connections use a 5 second timeout.
Sessions run with autocommit enabled: each statement is its own transaction.
Result sets are capped at 120 rows.
Run and Disconnect are disabled until a connection succeeds.

License

pgMui is released under the MIT License. The text is in LICENSE inside pgMui.zip and in the source repository.