Metadata-Version: 2.4
Name: py-dbms-cli
Version: 4.0.10002
Summary: A modern, secure, aesthetic and your ultimate DBMS client. Implemented as a CLI (Command-Line Interface) tool and written 100% in Python
Author-email: Anish Sethi <sethi.dynasty123@gmail.com>
License: Copyright 2025 Anish Sethi
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Homepage, https://github.com/Anish-Sethi-12122/py-dbms-cli
Project-URL: Source, https://github.com/Anish-Sethi-12122/py-dbms-cli
Project-URL: Issues, https://github.com/Anish-Sethi-12122/py-dbms-cli/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mysql-connector-python
Requires-Dist: rich
Requires-Dist: pyfiglet
Requires-Dist: sqlparse
Requires-Dist: pwinput
Requires-Dist: crypto-functions
Dynamic: license-file

# PY DBMS — A Modern, Secure MySQL CLI Client

**Experimental Release — v4.0.0**

PY DBMS is a modern, developer-focused command-line client for MySQL, built with Python.  
It provides a clean terminal UI, readable query output, powerful helper commands, and a robust export system—without sacrificing safety, clarity, or control.

Designed for developers who live in the terminal but want a more structured, reliable experience than the default MySQL CLI.

---

## Key Features

### 🏗️ Modular Architecture
- **Decoupled DB Connector Layer:** Connection logic is separated from the CLI UX core to prepare for multi-engine support (PostgreSQL, SQLite, etc.).
- **Clean Result Abstraction:** Query execution, rendering, and export are kept modular and easy to extend.

### 👤 Local Profile Login (New in v4.0.0)
- **Startup Authentication Gate:** PY DBMS requires local login before starting the MySQL session.
- **Profile Stored Locally (`profile.json`)**
  - Username stored as plain text
  - Password stored as **Argon2 hash** (never stored in plaintext)
- **Secure Input:** Password entry is masked using `pwinput`.
- **First Run Friendly:**
  - If no user exists, PY DBMS prompts to create a profile first.
  - If profile exists, user can choose:
    - Login
    - Create new user

### 📤 Query Export System (Stable)
- **Pluggable Export Manager:** Centralized export handling with strict validation and predictable UX.
- **CSV & JSON Support:** Export query results directly to `.csv` or `.json`.
- **Safe by Design:** Export failures (invalid format, empty result, I/O issues) never terminate the session.
- **Persistent Default Export Path (`export.path`):**
  - Default export directory is created automatically.
  - Can be modified using `.config set export.path ...`.
  - Can be reset to default using `.config reset export.path`.
- **Space-Safe Paths:** Quoted file paths with spaces are fully supported.
- **Bounded Result Rendering:** Large result-sets do not crash the CLI and do not leave unread cursor data.

> Note: `--export` always requires a format explicitly (`csv` or `json`).

### 📊 Query Output Control
- **`--expand` Flag:** Expand query results inline to prevent column truncation.
- **Precedence-Aware Design:**
  - Query-level `--expand` overrides session configuration
  - Session configuration defines default behavior
- **Composable Flags:** `--expand` and `--export` work together in a single query.

### Terminal UX
- **Rich Interface:** Structured tables and panels for high readability.
- **Visual Feedback:** Color-coded status messages for success, warnings, and SQL errors.
- **Startup Dashboard:** ASCII banner and session summary on launch.

### Configuration & Control
- **Persistent Config (`config.json`):** Stored in an OS-appropriate runtime directory.
- **Session Config Layer:** Runtime-only overrides that reset on every launch.
- **Inline Query Flags:** Per-query behavior customization without mutating configuration.

### Security
- **Masked Credentials:** MySQL password input is always masked.
- **Local Profile Protection:** Profile password is Argon2-hashed.
- **Zero Credential Persistence:** MySQL credentials are never stored on disk.

---

## Installation

### Prerequisites
- Python **3.10+**
- A running MySQL Server

### Install via pip
```bash
pip install py-dbms-cli
```

---

## Usage

### 1. Run from terminal
```bash
pydbms
```

### 2. Local login/signup
- If a profile exists, choose:
  1) Login to existing user  
  2) Create a new user
- If no user exists, you will be prompted to create one.

### 3. MySQL Connection
You will be prompted for:
  - Host
  - Username
  - Password (masked)

### 4. Begin querying
Enter SQL commands as you normally would.  
Multi-line queries are supported and executed once terminated with `;`.

---

## Meta Commands

PY DBMS includes several helper commands for interactive usage:

| Command | Description |
|------|-----------|
| `.help` | Show all helper commands |
| `.databases` | List all databases |
| `.tables` | List tables in the current database |
| `.schema <table>` | Show CREATE TABLE definition |
| `.clear` | Clear the terminal screen |
| `.version` | Show build and version information |
| `.config` | Show persistent configuration |
| `.config set <section>.<key> <value>` | Update a config value |
| `.config reset <section>.<key>` | Reset a config value |
| `.session-config` | Show session-level configuration |
| `.session-config set <key> <value>` | Update session-only settings |
| `.session-config reset <key> <value>` | Reset a session setting |
| `.exit` | Exit the CLI |

---

## Query Flags

| Flag | Description |
|------|-----------|
| `--expand` | Expand query output to avoid truncation (overrides session-config) |
| `--export <format> [path]` | Export query results (`csv` or `json`) |

✅ Supported export formats as of **v4.0.0**: `{csv, json}`  
❌ `--export` without a format is invalid.

---

## Roadmap

Planned future improvements include:

- [ ] Engine Selection System (`.use mysql` etc.) *(planned for v4.1.0 stable)*
- [ ] Multi-Engine Support (PostgreSQL / SQLite)
- [ ] Saved Engine Connections under pydbms profile system *(v5.x foundation)*
- [ ] Query History (persistent command history)
- [ ] Additional export formats

---

## Author

Anish Sethi  
B.Tech Computer Science & Engineering  
Delhi Technological University (Class of 2029)

---

## License

This project is licensed under the BSD 3-Clause License.  
Visit the [BSD 3-Clause License page](https://opensource.org/license/bsd-3-clause) for more information.
