fastapi-sqlite-ui 1.0.0__tar.gz

fastapi_sqlite_ui-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.db
+*.db-journal
+*.log
+.DS_Store

fastapi_sqlite_ui-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hoangtuvungcao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_sqlite_ui-1.0.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: fastapi-sqlite-ui
+Version: 1.0.0
+Summary: A lightweight, plug-and-play SQLite administration panel UI for FastAPI.
+Author: hoangtuvungcao
+License: MIT
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: fastapi>=0.100.0
+Description-Content-Type: text/markdown
+
+# fastapi-sqlite-ui
+
+A lightweight, plug-and-play SQLite administration panel UI for FastAPI applications.
+
+*Giao diện quản lý SQLite Admin Panel gọn nhẹ, cắm-là-chạy dành cho các ứng dụng FastAPI.*
+
+---
+
+## Design & Layout (Thiết kế & Bố cục)
+
+### English
+The user interface utilizes standard modern design practices:
+- **Dark Theme**: High-contrast dark mode (`#0b0f19`) featuring subtle borders and glassmorphism.
+- **Icons & Typography**: Uses Google Font *Inter* for readability and *Lucide Icons* for user interface control mapping.
+- **Transitions**: Smooth micro-interactions for modal triggers and status notifications.
+
+### Tiếng Việt
+Giao diện người dùng sử dụng các nguyên lý thiết kế hiện đại:
+- **Chủ đề tối (Dark Theme)**: Chế độ tối độ tương phản cao (`#0b0f19`) kết hợp đường viền mỏng và hiệu ứng mờ kính (glassmorphism).
+- **Biểu tượng & Font chữ**: Sử dụng font chữ *Inter* để tối ưu khả năng đọc và *Lucide Icons* để mô tả điều hướng trực quan.
+- **Hiệu ứng chuyển động**: Các tương tác nhỏ (micro-interactions) mượt mà cho các sự kiện mở modal và thông báo trạng thái.
+
+---
+
+## Features (Tính năng)
+
+### English
+- **Plug & Play**: Single function call to mount the APIRouter.
+- **Data Browser**: Paginated table view with search filters on text columns.
+- **Schema Inspector**: Structured view of columns, data types, primary keys, and foreign keys.
+- **Full CRUD**: Complete row insert, update, and delete support with schema-aware input fields.
+- **Raw SQL Console**: Text-area input for executing arbitrary raw SQL statements with elapsed time metrics.
+- **Read-Only Mode**: Toggle option to restrict database modifications.
+- **Self-contained SPA**: No asset build steps required by the parent Python server.
+
+### Tiếng Việt
+- **Tích hợp nhanh**: Chỉ cần gọi một hàm để gắn APIRouter vào ứng dụng.
+- **Duyệt dữ liệu**: Hiển thị bảng dạng phân trang kèm bộ lọc tìm kiếm trên các cột văn bản.
+- **Kiểm tra cấu trúc**: Xem cấu trúc cột, kiểu dữ liệu, khóa chính và khóa ngoại.
+- **Hỗ trợ CRUD**: Thao tác thêm, sửa, xóa các dòng dữ liệu thông qua các biểu mẫu tự động tương thích theo cấu trúc bảng.
+- **Trình chạy SQL Raw**: Nhập và thực thi trực tiếp các câu lệnh SQL tự do có đo lường thời gian phản hồi.
+- **Chế độ chỉ đọc (Read-Only)**: Cấu hình tùy chọn để chặn các thao tác ghi dữ liệu.
+- **SPA tự đóng gói**: Không yêu cầu bước biên dịch tài nguyên tĩnh từ phía server Python.
+
+---
+
+## Installation (Cài đặt)
+
+```bash
+pip install fastapi-sqlite-ui
+```
+
+Make sure you have `fastapi` and `uvicorn` installed.
+
+---
+
+## Usage (Cách dùng)
+
+```python
+from fastapi import FastAPI
+from fastapi_sqlite_ui import mount_sqlite_ui
+
+app = FastAPI()
+
+# Mount the SQLite UI at /admin
+mount_sqlite_ui(
+    app,
+    db_path="./mydb.sqlite",
+    mount_path="/admin",
+    read_only=False
+)
+```
+
+---
+
+## Options (Cấu hình)
+
+The `mount_sqlite_ui` function takes the following parameters:
+
+| Parameter | Type | Default | Description / Mô tả |
+| :--- | :--- | :--- | :--- |
+| `app` | `FastAPI` | *Required* | The FastAPI application instance. / *Đối tượng ứng dụng FastAPI.* |
+| `db_path` | `str` | *Required* | Path to the SQLite database file. / *Đường dẫn đến tệp cơ sở dữ liệu SQLite.* |
+| `mount_path` | `str` | `"/admin"` | URL prefix for the administration dashboard. / *Tiền tố đường dẫn URL cho trang quản trị.* |
+| `read_only` | `bool` | `False` | Hides CRUD actions and blocks write queries if True. / *Nếu là True, ẩn giao diện CRUD và chặn các câu lệnh ghi dữ liệu.* |
+
+---
+
+## License
+
+MIT License.

fastapi_sqlite_ui-1.0.0/README.md

@@ -0,0 +1,91 @@
+# fastapi-sqlite-ui
+
+A lightweight, plug-and-play SQLite administration panel UI for FastAPI applications.
+
+*Giao diện quản lý SQLite Admin Panel gọn nhẹ, cắm-là-chạy dành cho các ứng dụng FastAPI.*
+
+---
+
+## Design & Layout (Thiết kế & Bố cục)
+
+### English
+The user interface utilizes standard modern design practices:
+- **Dark Theme**: High-contrast dark mode (`#0b0f19`) featuring subtle borders and glassmorphism.
+- **Icons & Typography**: Uses Google Font *Inter* for readability and *Lucide Icons* for user interface control mapping.
+- **Transitions**: Smooth micro-interactions for modal triggers and status notifications.
+
+### Tiếng Việt
+Giao diện người dùng sử dụng các nguyên lý thiết kế hiện đại:
+- **Chủ đề tối (Dark Theme)**: Chế độ tối độ tương phản cao (`#0b0f19`) kết hợp đường viền mỏng và hiệu ứng mờ kính (glassmorphism).
+- **Biểu tượng & Font chữ**: Sử dụng font chữ *Inter* để tối ưu khả năng đọc và *Lucide Icons* để mô tả điều hướng trực quan.
+- **Hiệu ứng chuyển động**: Các tương tác nhỏ (micro-interactions) mượt mà cho các sự kiện mở modal và thông báo trạng thái.
+
+---
+
+## Features (Tính năng)
+
+### English
+- **Plug & Play**: Single function call to mount the APIRouter.
+- **Data Browser**: Paginated table view with search filters on text columns.
+- **Schema Inspector**: Structured view of columns, data types, primary keys, and foreign keys.
+- **Full CRUD**: Complete row insert, update, and delete support with schema-aware input fields.
+- **Raw SQL Console**: Text-area input for executing arbitrary raw SQL statements with elapsed time metrics.
+- **Read-Only Mode**: Toggle option to restrict database modifications.
+- **Self-contained SPA**: No asset build steps required by the parent Python server.
+
+### Tiếng Việt
+- **Tích hợp nhanh**: Chỉ cần gọi một hàm để gắn APIRouter vào ứng dụng.
+- **Duyệt dữ liệu**: Hiển thị bảng dạng phân trang kèm bộ lọc tìm kiếm trên các cột văn bản.
+- **Kiểm tra cấu trúc**: Xem cấu trúc cột, kiểu dữ liệu, khóa chính và khóa ngoại.
+- **Hỗ trợ CRUD**: Thao tác thêm, sửa, xóa các dòng dữ liệu thông qua các biểu mẫu tự động tương thích theo cấu trúc bảng.
+- **Trình chạy SQL Raw**: Nhập và thực thi trực tiếp các câu lệnh SQL tự do có đo lường thời gian phản hồi.
+- **Chế độ chỉ đọc (Read-Only)**: Cấu hình tùy chọn để chặn các thao tác ghi dữ liệu.
+- **SPA tự đóng gói**: Không yêu cầu bước biên dịch tài nguyên tĩnh từ phía server Python.
+
+---
+
+## Installation (Cài đặt)
+
+```bash
+pip install fastapi-sqlite-ui
+```
+
+Make sure you have `fastapi` and `uvicorn` installed.
+
+---
+
+## Usage (Cách dùng)
+
+```python
+from fastapi import FastAPI
+from fastapi_sqlite_ui import mount_sqlite_ui
+
+app = FastAPI()
+
+# Mount the SQLite UI at /admin
+mount_sqlite_ui(
+    app,
+    db_path="./mydb.sqlite",
+    mount_path="/admin",
+    read_only=False
+)
+```
+
+---
+
+## Options (Cấu hình)
+
+The `mount_sqlite_ui` function takes the following parameters:
+
+| Parameter | Type | Default | Description / Mô tả |
+| :--- | :--- | :--- | :--- |
+| `app` | `FastAPI` | *Required* | The FastAPI application instance. / *Đối tượng ứng dụng FastAPI.* |
+| `db_path` | `str` | *Required* | Path to the SQLite database file. / *Đường dẫn đến tệp cơ sở dữ liệu SQLite.* |
+| `mount_path` | `str` | `"/admin"` | URL prefix for the administration dashboard. / *Tiền tố đường dẫn URL cho trang quản trị.* |
+| `read_only` | `bool` | `False` | Hides CRUD actions and blocks write queries if True. / *Nếu là True, ẩn giao diện CRUD và chặn các câu lệnh ghi dữ liệu.* |
+
+---
+
+## License
+
+MIT License.

fastapi_sqlite_ui-1.0.0/fastapi_sqlite_ui/__init__.py

@@ -0,0 +1,16 @@
+from .router import sqlite_ui_router
+
+def mount_sqlite_ui(app, db_path: str, mount_path: str = "/admin", read_only: bool = False):
+    """
+    Mount the SQLite Admin UI APIRouter into your FastAPI application.
+    
+    Args:
+        app: The FastAPI application instance.
+        db_path: Path to the SQLite database file.
+        mount_path: URL prefix under which the UI and API will be mounted (default: "/admin").
+        read_only: If True, hides mutation actions (add/edit/delete) and blocks write queries.
+    """
+    router = sqlite_ui_router(db_path, read_only)
+    app.include_router(router, prefix=mount_path)
+
+__all__ = ["sqlite_ui_router", "mount_sqlite_ui"]

fastapi_sqlite_ui-1.0.0/fastapi_sqlite_ui/driver.py

@@ -0,0 +1,174 @@
+import sqlite3
+import re
+
+class SQLiteDriver:
+    def __init__(self, db_path: str, read_only: bool = False):
+        self.db_path = db_path
+        self.read_only = read_only
+
+    def _get_connection(self):
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _serialize_value(self, val):
+        if isinstance(val, bytes):
+            return f"<BLOB: {len(val)} bytes>"
+        return val
+
+    def execute(self, sql: str, params: tuple = ()) -> dict:
+        if self.read_only:
+            # Check if write statement
+            is_write = not re.match(r'^\s*(select|pragma|explain|show|desc)', sql, re.IGNORECASE)
+            if is_write:
+                return {"rows": [], "columns": [], "error": "Database is in read-only mode"}
+
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        try:
+            cursor.execute(sql, params)
+            
+            # Check if query returned rows (e.g. SELECT)
+            rows_data = []
+            columns = []
+            affected_rows = None
+
+            if cursor.description:
+                columns = [desc[0] for desc in cursor.description]
+                rows = cursor.fetchall()
+                rows_data = [
+                    {col: self._serialize_value(row[col]) for col in columns}
+                    for row in rows
+                ]
+            else:
+                conn.commit()
+                affected_rows = cursor.rowcount
+
+            return {
+                "rows": rows_data,
+                "columns": columns,
+                "affectedRows": affected_rows
+            }
+        except sqlite3.Error as e:
+            return {"rows": [], "columns": [], "error": str(e)}
+        finally:
+            conn.close()
+
+    def get_tables(self) -> list:
+        res = self.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+        if "error" in res:
+            raise Exception(res["error"])
+        return [row["name"] for row in res["rows"]]
+
+    def get_table_info(self, table: str) -> dict:
+        sanitized_table = re.sub(r'[^a-zA-Z0-9_]', '', table)
+        
+        col_res = self.execute(f'PRAGMA table_info("{sanitized_table}")')
+        if "error" in col_res:
+            raise Exception(col_res["error"])
+
+        fk_res = self.execute(f'PRAGMA foreign_key_list("{sanitized_table}")')
+        if "error" in fk_res:
+            raise Exception(fk_res["error"])
+
+        columns = []
+        for r in col_res["rows"]:
+            columns.append({
+                "name": r["name"],
+                "type": r["type"],
+                "notNull": r["notnull"] == 1,
+                "defaultValue": r["dflt_value"],
+                "primaryKey": r["pk"] == 1 or r["pk"] is True
+            })
+
+        foreign_keys = []
+        for r in fk_res["rows"]:
+            foreign_keys.append({
+                "id": r["id"],
+                "seq": r["seq"],
+                "table": r["table"],
+                "from": r["from"],
+                "to": r["to"],
+                "onUpdate": r["on_update"],
+                "onDelete": r["on_delete"],
+                "match": r["match"]
+            })
+
+        return {
+            "name": table,
+            "columns": columns,
+            "foreignKeys": foreign_keys
+        }
+
+    def get_rows(self, table: str, limit: int, offset: int, search: str = "") -> dict:
+        sanitized_table = re.sub(r'[^a-zA-Z0-9_]', '', table)
+        info = self.get_table_info(table)
+        
+        where_clause = ""
+        params = []
+
+        if search and info["columns"]:
+            # Find columns that are of type text
+            search_terms = []
+            for c in info["columns"]:
+                c_type = c["type"].upper()
+                if any(t in c_type for t in ['TEXT', 'VARCHAR', 'CHAR', 'CLOB']) or c_type == '':
+                    search_terms.append(f'"{c["name"].replace(chr(34), chr(34)+chr(34))}" LIKE ?')
+            
+            if search_terms:
+                where_clause = f" WHERE {' OR '.join(search_terms)}"
+                wild_card_search = f"%{search}%"
+                for _ in search_terms:
+                    params.append(wild_card_search)
+
+        # Count total rows
+        count_sql = f'SELECT COUNT(*) as count FROM "{sanitized_table}"{where_clause}'
+        count_res = self.execute(count_sql, tuple(params))
+        total = count_res["rows"][0]["count"] if count_res["rows"] else 0
+
+        # Fetch rows
+        select_sql = f'SELECT * FROM "{sanitized_table}"{where_clause} LIMIT ? OFFSET ?'
+        select_res = self.execute(select_sql, tuple(params + [limit, offset]))
+
+        return {
+            "rows": select_res["rows"],
+            "total": total
+        }
+
+    def insert_row(self, table: str, data: dict) -> dict:
+        sanitized_table = re.sub(r'[^a-zA-Z0-9_]', '', table)
+        columns = [f'"{c.replace(chr(34), chr(34)+chr(34))}"' for c in data.keys()]
+        placeholders = [', '.join(['?'] * len(data))]
+        values = list(data.values())
+
+        sql = f'INSERT INTO "{sanitized_table}" ({", ".join(columns)}) VALUES ({", ".join(placeholders)})'
+        res = self.execute(sql, tuple(values))
+        if "error" in res:
+            raise Exception(res["error"])
+        return res
+
+    def update_row(self, table: str, pk: dict, data: dict) -> dict:
+        sanitized_table = re.sub(r'[^a-zA-Z0-9_]', '', table)
+        
+        set_terms = [f'"{c.replace(chr(34), chr(34)+chr(34))}" = ?' for c in data.keys()]
+        set_values = list(data.values())
+
+        where_terms = [f'"{c.replace(chr(34), chr(34)+chr(34))}" = ?' for c in pk.keys()]
+        where_values = list(pk.values())
+
+        sql = f'UPDATE "{sanitized_table}" SET {", ".join(set_terms)} WHERE {" AND ".join(where_terms)}'
+        res = self.execute(sql, tuple(set_values + where_values))
+        if "error" in res:
+            raise Exception(res["error"])
+        return res
+
+    def delete_row(self, table: str, pk: dict) -> dict:
+        sanitized_table = re.sub(r'[^a-zA-Z0-9_]', '', table)
+        where_terms = [f'"{c.replace(chr(34), chr(34)+chr(34))}" = ?' for c in pk.keys()]
+        where_values = list(pk.values())
+
+        sql = f'DELETE FROM "{sanitized_table}" WHERE {" AND ".join(where_terms)}'
+        res = self.execute(sql, tuple(where_values))
+        if "error" in res:
+            raise Exception(res["error"])
+        return res

fastapi_sqlite_ui-1.0.0/fastapi_sqlite_ui/router.py

@@ -0,0 +1,120 @@
+# pyrefly: ignore [missing-import]
+from fastapi import APIRouter, Request
+# pyrefly: ignore [missing-import]
+from fastapi.responses import HTMLResponse, JSONResponse
+from .driver import SQLiteDriver
+from .ui import get_html_template
+
+def sqlite_ui_router(db_path: str, read_only: bool = False) -> APIRouter:
+    router = APIRouter()
+    driver = SQLiteDriver(db_path, read_only)
+
+    @router.get("/", response_class=HTMLResponse)
+    def index(request: Request):
+        path = request.url.path
+        base_path = path[:-1] if path.endswith('/') else path
+        return get_html_template(base_path)
+
+    @router.get("/index.html", response_class=HTMLResponse)
+    def index_html(request: Request):
+        path = request.url.path
+        base_path = path[:-11] if path.endswith('/index.html') else path
+        return get_html_template(base_path)
+
+    @router.get("/api/tables")
+    def list_tables():
+        try:
+            tables = driver.get_tables()
+            return {
+                "success": True,
+                "tables": tables,
+                "readOnly": read_only
+            }
+        except Exception as e:
+            return JSONResponse(status_code=500, content={"success": False, "error": str(e)})
+
+    @router.get("/api/tables/{table_name}")
+    def table_data(table_name: str, page: int = 1, limit: int = 10, search: str = ""):
+        try:
+            offset = (page - 1) * limit
+            info = driver.get_table_info(table_name)
+            data = driver.get_rows(table_name, limit, offset, search)
+            return {
+                "success": True,
+                "info": info,
+                "rows": data["rows"],
+                "total": data["total"]
+            }
+        except Exception as e:
+            return JSONResponse(status_code=500, content={"success": False, "error": str(e)})
+
+    @router.post("/api/query")
+    async def run_query(request: Request):
+        try:
+            body = await request.json()
+            sql = body.get("sql")
+            params = body.get("params", [])
+            
+            if not sql:
+                return JSONResponse(status_code=400, content={"success": False, "error": "SQL query is required"})
+                
+            res = driver.execute(sql, tuple(params))
+            if "error" in res:
+                return {"success": False, "error": res["error"]}
+                
+            return {
+                "success": True,
+                "rows": res["rows"],
+                "columns": res["columns"],
+                "affectedRows": res["affectedRows"]
+            }
+        except Exception as e:
+            return JSONResponse(status_code=500, content={"success": False, "error": str(e)})
+
+    @router.post("/api/tables/{table_name}")
+    async def add_row(table_name: str, request: Request):
+        if read_only:
+            return JSONResponse(status_code=403, content={"success": False, "error": "Database is in read-only mode"})
+        try:
+            body = await request.json()
+            data = body.get("data")
+            if not data:
+                return JSONResponse(status_code=400, content={"success": False, "error": "Data is required"})
+                
+            driver.insert_row(table_name, data)
+            return {"success": True}
+        except Exception as e:
+            return JSONResponse(status_code=500, content={"success": False, "error": str(e)})
+
+    @router.put("/api/tables/{table_name}")
+    async def edit_row(table_name: str, request: Request):
+        if read_only:
+            return JSONResponse(status_code=403, content={"success": False, "error": "Database is in read-only mode"})
+        try:
+            body = await request.json()
+            pk = body.get("pk")
+            data = body.get("data")
+            if not pk or not data:
+                return JSONResponse(status_code=400, content={"success": False, "error": "pk and data are required"})
+                
+            driver.update_row(table_name, pk, data)
+            return {"success": True}
+        except Exception as e:
+            return JSONResponse(status_code=500, content={"success": False, "error": str(e)})
+
+    @router.delete("/api/tables/{table_name}")
+    async def delete_row(table_name: str, request: Request):
+        if read_only:
+            return JSONResponse(status_code=403, content={"success": False, "error": "Database is in read-only mode"})
+        try:
+            body = await request.json()
+            pk = body.get("pk")
+            if not pk:
+                return JSONResponse(status_code=400, content={"success": False, "error": "pk is required"})
+                
+            driver.delete_row(table_name, pk)
+            return {"success": True}
+        except Exception as e:
+            return JSONResponse(status_code=500, content={"success": False, "error": str(e)})
+
+    return router