A modern, secure, terminal-first MySQL client built for developers.
Structured tables, smart flags, and secure local profiles—without the CLI clutter.
Introduction • Features • Installation • Usage • Flags & Commands • Roadmap
PY DBMS is a UI/UX-focused MySQL CLI client built in Python. It replaces the traditional, low-signal database output with a high-fidelity terminal experience.
v4.0.0 overhauled the system completely to introduce Secure Local Authentication, Live Query Spinners, a hardened Export Pipeline, and intelligent multi-line prompt formatting (e.g. ->). v4.1.0 stabilizes this architecture and brings powerful tools like inline --row-limit execution and --include-query export embedding.
The Philosophy: Stop squinting at wrapped CLI output. Work in a visually structured, highly reliable environment that respects your time and your eyeballs.
- 🚫 No More Walls of Text: Utilizes
richto render data in clean, color-coded grid tables that respect your terminal bounds. - 🔒 Authentication Guard: Your database credentials shouldn't be unprotected.
pydbmsrequires a local profile login verified by anargon2hashed password. - 📊 One-Flag Exports: Append
--export jsonor--export csvto any query. No weirdINTO OUTFILEpermission issues from the backend server. - 👀 Responsive UI: See exactly what's happening. Executing a heavy
JOIN? A cyan spinner keeps you updated. Broke a query? Explicit redmysql error>tags will let you know instantly.
- Live Query Spinners: Long-running queries use an animated
Executing query...spinner that clearly indicates network IO and properly vanishes before visualizing your result sets. - Structured Data Grids: Results print into beautiful bordered panels with explicit column widths.
- SQL Multi-Line Formatting: Typing extensive queries prompts you with the MySQL-standard
->prefix across lines until terminated with;.
- Local Profiles Gate: The CLI refuses to spin up a MySQL connection layer without validating against your local profile block.
- Hardware-Grade Cryptography: Local passwords are hashed via the
argon2-cffiprotocol.profile.jsonwill never host plaintext payloads. - Masked Login Pipelines: Password inputs globally obscure keystrokes using
pwinput.
- Non-Fatal Fallbacks: Misspelled an export format? Missing disk write permissions? The export manager will catch the fault and warn you natively without blowing up your active session.
- JSON & CSV Formats: Built-in modular exporters ensure massive result rows are serialized efficiently.
- Auto-Resolution Paths: Output locations gracefully scale using
shlexpath parsing to support spaces (export csv "C:\My Data\data.csv").
config.json: Set global persistent states (likeexport.path) mapping directly to cross-session behaviors..session-config: Temporarily mutate CLI states (like global expansions) strictly bounded by termination closures.
- Python 3.10+
Preferred latest Python version. Download from Python's official website↗
- A running MySQL server
Download from mysql's official website↗
pip install -U py-dbms-cli(This automatically bootstraps all terminal dependencies identically into your virtual or global environment).
pipx install -U py-dbms-cliOpen your terminal and boot up the client:
pydbmsOn initial startup, pydbms will ask you to bootstrap your first local root user. Following startups will route through a standard login wall.
Post-authorization, your credentials for the target MySQL server are collected (with encrypted masking on your password). pydbms will connect you to SQL server.
Once you are logged in to your SQL connection, everything operates within standard MySQL standard dialects. Queries process exactly once preventing accidental duplicate state mutation, returning cleanly visually bounded outputs.
Example usage:
pydbms> SELECT * FROM users
-> WHERE access_tier = "admin"
-> ORDER BY created_at DESC;Mistakes happen. Instead of dumping a giant Python stack trace or messy string blocks on fail, exceptions are handled and printed uniformly for immediate bug patching.
Flags are appended explicitly to the end of standard SQL queries, shifting display settings for a single action cycle without altering your base configurations.
Usage Example:
SELECT * FROM inventory; --expand --export csv
| Flag | Description |
|---|---|
--expand |
Forces the output table to horizontally scroll over wrapping, preventing truncated columns at Terminal Edge boundaries. default=false |
--export <format> <path?> |
Rents out the result stack instantly to a local file in either json or csv. |
--row-limit <N> |
Limit rows returned for this query (overrides ui.max_rows). |
--include-query |
Embed original SQL query in the exported file (default: off). |
Meta commands bypass the SQL parser outright to configure environments internally.
| Command | Description |
|---|---|
.help |
Show helper commands |
.databases |
Show databases in current connection |
.tables |
Show tables in current database |
.schema <table> |
Show CREATE TABLE statement for table <table> |
.clear |
Clear the terminal screen |
.version |
Show pydbms build information |
.config |
Show config settings for pydbms |
.config set <section>.<key> <value> |
Set config to a new value |
.config reset <section?>.<key?> |
Reset config to a default value |
.session-config |
Show session config settings for pydbms (Resets on every run) |
.session-config set <key> <value> |
Set session config to a new value |
.session-config reset <key?> |
Reset session config to a default value |
.exit |
Exit pydbms |
PY DBMS uses a highly flexible, 3-tiered configuration system:
Managed via .config set of commands. These configurations persist permanently across boots and are stored directly in your OS-appropriate appdata/config directory.
Managed via .session-config and .session-config set commands. These overrides live only in memory for your current active terminal session and revert immediately when you exit via .exit.
Managed via appending raw --flags to the end of a SQL string. Overrides everything beneath it (Session and Global) for that exact execution cycle only.
- Use Case: Normal queries are truncating strings, but you just need to
SELECTa massive JSON blob once? DoSELECT * FROM logs; --expand. It expands the blob, and the very next query goes back to normal.
## 👤 Who is this for? Who can use `pydbms`
• Developers who prefer working in the terminal
• Engineers who want cleaner query outputs
• Users who frequently export query results
• Anyone who wants a modern, secure, terminal-first MySQL client
• Students who are learning about databases and want a user-friendly way to interact with them
- Multi DBMS Support: Built-in interactive command (
.use <db_name>) for jumping database grids securely. (Planned v5.x) - Hardware Connectors: Bridge the core codebase abstraction layer to support commonly used databases like Postgre, Mongo, Oracle SQL, etc.
PY DBMS strictly utilizes pytest to govern all underlying architecture (Query Execution, Parsing, CSV/JSON Export flows, and Configuration Schemas).
All test pipelines are publicly committed to GitHub to ensure community pull requests maintain absolute stability.
To contribute or run tests locally on your machine:
# 1. Install the CLI with developer testing dependencies attached
pip install -e .[dev]
# 2. Run the test suite natively
pytest tests/Anish Sethi | B.Tech Computer Science & Engineering | Delhi Technological University (Class of 2029)
This project is licensed under the BSD 3-Clause License. See the LICENSE.
Consider dropping a ⭐️ star to support a student-led open-source project and keep the updates rolling in!