ghostbase-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 4yk5
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,165 @@
1
+ Metadata-Version: 2.4
2
+ Name: ghostbase-cli
3
+ Version: 0.1.0
4
+ Summary: A fast, keyboard-driven terminal database studio for SQLite, PostgreSQL & MySQL
5
+ Author-email: 4yk5 <contact.4yk5@proton.me>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/4yk5/GhostBase
8
+ Project-URL: Repository, https://github.com/4yk5/GhostBase
9
+ Project-URL: Issues, https://github.com/4yk5/GhostBase/issues
10
+ Keywords: database,sql,tui,terminal,cli,sqlite,postgres,postgresql,mysql,dbeaver,datagrip,query,developer-tools
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Environment :: Console
14
+ Classifier: Topic :: Database
15
+ Classifier: Topic :: Database :: Front-Ends
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: textual>=8.0.0
20
+ Requires-Dist: rich>=14.0.0
21
+ Requires-Dist: psycopg2-binary>=2.9.0
22
+ Requires-Dist: pymysql>=1.1.0
23
+ Dynamic: license-file
24
+
25
+ ```
26
+ ____ _ _ ____
27
+ / ___| |__ ___ ___| |_| __ ) __ _ ___ ___
28
+ | | _| '_ \ / _ \/ __| __| _ \ / _` / __|/ _ \
29
+ | |_| | | | | (_) \__ \ |_| |_) | (_| \__ \ __/
30
+ \____|_| |_|\___/|___/\__|____/ \__,_|___/\___|
31
+
32
+ ```
33
+
34
+ # GhostBase 👻🗄️
35
+
36
+ > **A fast, keyboard-driven terminal database studio for SQLite, PostgreSQL, and MySQL.**
37
+ > *No Java runtimes. No 1.5GB RAM bloat. Built-in production safety guard, instant SQL beautifier & zero-config `.env` connect.*
38
+
39
+ [![CI](https://github.com/4yk5/GhostBase/actions/workflows/ci.yml/badge.svg)](https://github.com/4yk5/GhostBase/actions)
40
+ [![PyPI](https://img.shields.io/pypi/v/ghostbase-cli.svg)](https://pypi.org/project/ghostbase-cli/)
41
+ [![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
42
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
43
+ [![UI: Textual](https://img.shields.io/badge/UI-Textual-bd93f9.svg)](https://github.com/Textualize/textual)
44
+
45
+ ---
46
+
47
+ ## ⚡ Why GhostBase?
48
+
49
+ Opening **DBeaver** or **DataGrip** just to run a quick `SELECT`, inspect an index, or check foreign keys is painful:
50
+ - ❌ **1.5 GB+ RAM bloat:** Heavy Java/Eclipse runtimes that spin your laptop fans.
51
+ 👉 **GhostBase idles at ~25 MB RAM.**
52
+ - ❌ **15-Second Cold Starts:** Splash screens, driver updates, and workspace indexing.
53
+ 👉 **GhostBase starts in under 120 ms directly in your terminal.**
54
+ - ❌ **Accidental Destructive Queries on Production:** Running `DELETE` or `UPDATE` without a `WHERE` clause can wipe production tables.
55
+ 👉 **GhostBase intercepts destructive queries automatically with double-confirmation and one-key Read-Only Safe Mode (`Ctrl + S`).**
56
+ - ❌ **Messy, Unformatted Queries:** Manually formatting and indenting long SQL statements.
57
+ 👉 **GhostBase auto-formats and beautifies messy SQL queries with one keypress (`Ctrl + B`).**
58
+ - ❌ **Tedious Connection Setup:** Typing credentials into multi-tab dialogs.
59
+ 👉 **GhostBase auto-detects `DATABASE_URL` from your local `.env` file.**
60
+ - ❌ **Seeding & Migrating Data:** Manually writing `INSERT INTO` statements to replicate test rows.
61
+ 👉 **GhostBase exports query results directly into executable SQL `INSERT` statements (`Ctrl + I`).**
62
+ - ❌ **Exporting for GitHub / Jira / Notion:** Exporting CSV, then finding a website to convert to Markdown.
63
+ 👉 **One-key instant Markdown table export (`Ctrl + M`) directly into clean GitHub Flavored Markdown.**
64
+
65
+ ---
66
+
67
+ ## 🚀 Killer Features
68
+
69
+ - 🛡️ **Production Safety Guard & Safe Mode (`Ctrl + S`):**
70
+ - Intercepts dangerous statements (`DELETE`/`UPDATE` without `WHERE`, `DROP TABLE`, `TRUNCATE`).
71
+ - In **Safe Mode**, all destructive operations are strictly blocked.
72
+ - In normal mode, requires explicit double-confirmation before execution.
73
+ - ✨ **1-Key SQL Beautifier (`Ctrl + B`):**
74
+ - Instantly cleans up whitespace, capitalizes SQL keywords, and indents sub-clauses (`FROM`, `WHERE`, `AND`, `OR`, `JOIN`, `ORDER BY`).
75
+ - ⚡ **1-Key Query Plan (`Ctrl + P`):**
76
+ - Run instant execution plans (`EXPLAIN QUERY PLAN` / `EXPLAIN`) on any query to see index usage and bottlenecks.
77
+ - 🔌 **Universal Database Support:** Connects natively to **SQLite**, **PostgreSQL**, and **MySQL**.
78
+ - 🔍 **Zero-Config `.env` Auto-Connect:** Just run `ghostbase` in any project folder; it automatically picks up `DATABASE_URL` or standard database environment variables.
79
+ - 🔎 **Real-time Table Search (`Ctrl + F`):** Type in the search bar to filter dozens of tables and views instantly.
80
+ - 📊 **Explorer with Tables & Views:** Browse tables and views with live row counts.
81
+ - 📐 **Instant Schema & Foreign Keys:** See primary keys, column types, nullability, and foreign key references at a glance.
82
+ - 💾 **Multi-Format Exports:** Instant SQL `INSERT`s (`Ctrl + I`), Markdown (`Ctrl + M`), CSV (`Ctrl + E`), and JSON (`Ctrl + J`).
83
+ - 📜 **Query History:** Cycle through your last 20 queries with `Ctrl + ↑` and `Ctrl + ↓`.
84
+ - 🎨 **Clean Cyberpunk Aesthetic:** Fast, high-contrast, zero-flicker terminal interface.
85
+
86
+ ---
87
+
88
+ ## 📦 Installation & Quick Start
89
+
90
+ ### Via pip
91
+
92
+ ```bash
93
+ pip install ghostbase-cli
94
+ ```
95
+
96
+ ### From Source
97
+
98
+ ```bash
99
+ git clone https://github.com/4yk5/GhostBase.git
100
+ cd GhostBase
101
+ pip install -r requirements.txt
102
+ ```
103
+
104
+ ---
105
+
106
+ ## 💻 How to Use
107
+
108
+ ### 1. Auto-connect to current project (`.env`)
109
+ ```bash
110
+ # Automatically finds DATABASE_URL or DB_HOST in your current directory's .env
111
+ ghostbase
112
+ ```
113
+
114
+ ### 2. Connect to SQLite
115
+ ```bash
116
+ ghostbase path/to/database.db
117
+ ```
118
+
119
+ ### 3. Connect to PostgreSQL
120
+ ```bash
121
+ ghostbase postgresql://user:password@localhost:5432/my_database
122
+ ```
123
+
124
+ ### 4. Connect to MySQL
125
+ ```bash
126
+ ghostbase mysql://user:password@localhost:3306/my_database
127
+ ```
128
+
129
+ ### 5. Launch in Safe / Read-Only Mode
130
+ ```bash
131
+ ghostbase postgresql://prod-db:5432/main --read-only
132
+ ```
133
+
134
+ ---
135
+
136
+ ## ⌨️ Keyboard Shortcuts
137
+
138
+ | Shortcut | Description |
139
+ | :--- | :--- |
140
+ | `Ctrl + R` | **Execute SQL Query** (runs the query with safety validation) |
141
+ | `Ctrl + P` | **1-Key EXPLAIN** (instant query execution plan and performance inspector) |
142
+ | `Ctrl + B` | **Beautify SQL** (auto-formats, capitalizes keywords and indents clauses) |
143
+ | `Ctrl + S` | **Toggle Safe Mode** (enable/disable destructive query protection) |
144
+ | `Ctrl + N` | **New Query** (clears editor for a clean query) |
145
+ | `Ctrl + F` | **Find Table** (focuses table search filter) |
146
+ | `Ctrl + I` | **Export to SQL INSERTs** (generates executable `INSERT INTO` statements) |
147
+ | `Ctrl + M` | **Export to Markdown** (GitHub / Jira / Notion ready table) |
148
+ | `Ctrl + E` | **Export to CSV** (exports current table/query to CSV) |
149
+ | `Ctrl + J` | **Export to JSON** (exports current table/query to JSON) |
150
+ | `Ctrl + ↑` / `Ctrl + ↓` | **Query History** (cycle through previous queries) |
151
+ | `Tab` / `Shift + Tab` | Navigate between explorer, search, editor, and data table |
152
+ | `Ctrl + Q` | **Quit GhostBase** |
153
+
154
+ ---
155
+
156
+ ## 📬 Contact & Inquiries
157
+
158
+ For partnerships, feature requests, or business inquiries:
159
+ 📧 **[contact.4yk5@proton.me](mailto:contact.4yk5@proton.me)**
160
+
161
+ ---
162
+
163
+ ## 📄 License
164
+
165
+ Released under the [MIT License](LICENSE).
@@ -0,0 +1,141 @@
1
+ ```
2
+ ____ _ _ ____
3
+ / ___| |__ ___ ___| |_| __ ) __ _ ___ ___
4
+ | | _| '_ \ / _ \/ __| __| _ \ / _` / __|/ _ \
5
+ | |_| | | | | (_) \__ \ |_| |_) | (_| \__ \ __/
6
+ \____|_| |_|\___/|___/\__|____/ \__,_|___/\___|
7
+
8
+ ```
9
+
10
+ # GhostBase 👻🗄️
11
+
12
+ > **A fast, keyboard-driven terminal database studio for SQLite, PostgreSQL, and MySQL.**
13
+ > *No Java runtimes. No 1.5GB RAM bloat. Built-in production safety guard, instant SQL beautifier & zero-config `.env` connect.*
14
+
15
+ [![CI](https://github.com/4yk5/GhostBase/actions/workflows/ci.yml/badge.svg)](https://github.com/4yk5/GhostBase/actions)
16
+ [![PyPI](https://img.shields.io/pypi/v/ghostbase-cli.svg)](https://pypi.org/project/ghostbase-cli/)
17
+ [![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
18
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
19
+ [![UI: Textual](https://img.shields.io/badge/UI-Textual-bd93f9.svg)](https://github.com/Textualize/textual)
20
+
21
+ ---
22
+
23
+ ## ⚡ Why GhostBase?
24
+
25
+ Opening **DBeaver** or **DataGrip** just to run a quick `SELECT`, inspect an index, or check foreign keys is painful:
26
+ - ❌ **1.5 GB+ RAM bloat:** Heavy Java/Eclipse runtimes that spin your laptop fans.
27
+ 👉 **GhostBase idles at ~25 MB RAM.**
28
+ - ❌ **15-Second Cold Starts:** Splash screens, driver updates, and workspace indexing.
29
+ 👉 **GhostBase starts in under 120 ms directly in your terminal.**
30
+ - ❌ **Accidental Destructive Queries on Production:** Running `DELETE` or `UPDATE` without a `WHERE` clause can wipe production tables.
31
+ 👉 **GhostBase intercepts destructive queries automatically with double-confirmation and one-key Read-Only Safe Mode (`Ctrl + S`).**
32
+ - ❌ **Messy, Unformatted Queries:** Manually formatting and indenting long SQL statements.
33
+ 👉 **GhostBase auto-formats and beautifies messy SQL queries with one keypress (`Ctrl + B`).**
34
+ - ❌ **Tedious Connection Setup:** Typing credentials into multi-tab dialogs.
35
+ 👉 **GhostBase auto-detects `DATABASE_URL` from your local `.env` file.**
36
+ - ❌ **Seeding & Migrating Data:** Manually writing `INSERT INTO` statements to replicate test rows.
37
+ 👉 **GhostBase exports query results directly into executable SQL `INSERT` statements (`Ctrl + I`).**
38
+ - ❌ **Exporting for GitHub / Jira / Notion:** Exporting CSV, then finding a website to convert to Markdown.
39
+ 👉 **One-key instant Markdown table export (`Ctrl + M`) directly into clean GitHub Flavored Markdown.**
40
+
41
+ ---
42
+
43
+ ## 🚀 Killer Features
44
+
45
+ - 🛡️ **Production Safety Guard & Safe Mode (`Ctrl + S`):**
46
+ - Intercepts dangerous statements (`DELETE`/`UPDATE` without `WHERE`, `DROP TABLE`, `TRUNCATE`).
47
+ - In **Safe Mode**, all destructive operations are strictly blocked.
48
+ - In normal mode, requires explicit double-confirmation before execution.
49
+ - ✨ **1-Key SQL Beautifier (`Ctrl + B`):**
50
+ - Instantly cleans up whitespace, capitalizes SQL keywords, and indents sub-clauses (`FROM`, `WHERE`, `AND`, `OR`, `JOIN`, `ORDER BY`).
51
+ - ⚡ **1-Key Query Plan (`Ctrl + P`):**
52
+ - Run instant execution plans (`EXPLAIN QUERY PLAN` / `EXPLAIN`) on any query to see index usage and bottlenecks.
53
+ - 🔌 **Universal Database Support:** Connects natively to **SQLite**, **PostgreSQL**, and **MySQL**.
54
+ - 🔍 **Zero-Config `.env` Auto-Connect:** Just run `ghostbase` in any project folder; it automatically picks up `DATABASE_URL` or standard database environment variables.
55
+ - 🔎 **Real-time Table Search (`Ctrl + F`):** Type in the search bar to filter dozens of tables and views instantly.
56
+ - 📊 **Explorer with Tables & Views:** Browse tables and views with live row counts.
57
+ - 📐 **Instant Schema & Foreign Keys:** See primary keys, column types, nullability, and foreign key references at a glance.
58
+ - 💾 **Multi-Format Exports:** Instant SQL `INSERT`s (`Ctrl + I`), Markdown (`Ctrl + M`), CSV (`Ctrl + E`), and JSON (`Ctrl + J`).
59
+ - 📜 **Query History:** Cycle through your last 20 queries with `Ctrl + ↑` and `Ctrl + ↓`.
60
+ - 🎨 **Clean Cyberpunk Aesthetic:** Fast, high-contrast, zero-flicker terminal interface.
61
+
62
+ ---
63
+
64
+ ## 📦 Installation & Quick Start
65
+
66
+ ### Via pip
67
+
68
+ ```bash
69
+ pip install ghostbase-cli
70
+ ```
71
+
72
+ ### From Source
73
+
74
+ ```bash
75
+ git clone https://github.com/4yk5/GhostBase.git
76
+ cd GhostBase
77
+ pip install -r requirements.txt
78
+ ```
79
+
80
+ ---
81
+
82
+ ## 💻 How to Use
83
+
84
+ ### 1. Auto-connect to current project (`.env`)
85
+ ```bash
86
+ # Automatically finds DATABASE_URL or DB_HOST in your current directory's .env
87
+ ghostbase
88
+ ```
89
+
90
+ ### 2. Connect to SQLite
91
+ ```bash
92
+ ghostbase path/to/database.db
93
+ ```
94
+
95
+ ### 3. Connect to PostgreSQL
96
+ ```bash
97
+ ghostbase postgresql://user:password@localhost:5432/my_database
98
+ ```
99
+
100
+ ### 4. Connect to MySQL
101
+ ```bash
102
+ ghostbase mysql://user:password@localhost:3306/my_database
103
+ ```
104
+
105
+ ### 5. Launch in Safe / Read-Only Mode
106
+ ```bash
107
+ ghostbase postgresql://prod-db:5432/main --read-only
108
+ ```
109
+
110
+ ---
111
+
112
+ ## ⌨️ Keyboard Shortcuts
113
+
114
+ | Shortcut | Description |
115
+ | :--- | :--- |
116
+ | `Ctrl + R` | **Execute SQL Query** (runs the query with safety validation) |
117
+ | `Ctrl + P` | **1-Key EXPLAIN** (instant query execution plan and performance inspector) |
118
+ | `Ctrl + B` | **Beautify SQL** (auto-formats, capitalizes keywords and indents clauses) |
119
+ | `Ctrl + S` | **Toggle Safe Mode** (enable/disable destructive query protection) |
120
+ | `Ctrl + N` | **New Query** (clears editor for a clean query) |
121
+ | `Ctrl + F` | **Find Table** (focuses table search filter) |
122
+ | `Ctrl + I` | **Export to SQL INSERTs** (generates executable `INSERT INTO` statements) |
123
+ | `Ctrl + M` | **Export to Markdown** (GitHub / Jira / Notion ready table) |
124
+ | `Ctrl + E` | **Export to CSV** (exports current table/query to CSV) |
125
+ | `Ctrl + J` | **Export to JSON** (exports current table/query to JSON) |
126
+ | `Ctrl + ↑` / `Ctrl + ↓` | **Query History** (cycle through previous queries) |
127
+ | `Tab` / `Shift + Tab` | Navigate between explorer, search, editor, and data table |
128
+ | `Ctrl + Q` | **Quit GhostBase** |
129
+
130
+ ---
131
+
132
+ ## 📬 Contact & Inquiries
133
+
134
+ For partnerships, feature requests, or business inquiries:
135
+ 📧 **[contact.4yk5@proton.me](mailto:contact.4yk5@proton.me)**
136
+
137
+ ---
138
+
139
+ ## 📄 License
140
+
141
+ Released under the [MIT License](LICENSE).