Metadata-Version: 2.4
Name: freesimplesql
Version: 0.2.5
Summary: A SQLite database browser, editor and AI query builder using FreeSimpleGUI
Project-URL: Homepage, https://github.com/fxyzbtc/freesimplesql
Project-URL: Repository, https://github.com/fxyzbtc/freesimplesql
Project-URL: Bug Tracker, https://github.com/fxyzbtc/freesimplesql/issues
Project-URL: Documentation, https://github.com/fxyzbtc/freesimplesql#readme
License: MIT
Keywords: ai,browser,database,editor,gui,sql,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.7
Requires-Dist: faker>=18.13.0
Requires-Dist: freesimplegui>=5.2.0.post1
Requires-Dist: loguru>=0.7.3
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: requests>=2.31.0
Requires-Dist: sqlmodel>=0.0.24
Description-Content-Type: text/markdown

# FreeSimpleSQL

[![GitHub](https://img.shields.io/badge/github-fxyzbtc/freesimplesql-blue?logo=github)](https://github.com/fxyzbtc/freesimplesql)
[![PyPI](https://img.shields.io/pypi/v/freesimplesql)](https://pypi.org/project/freesimplesql/)
[![Python](https://img.shields.io/pypi/pyversions/freesimplesql)](https://pypi.org/project/freesimplesql/)

![Screenshot](https://github.com/fxyzbtc/freesimplesql/blob/master/screenshot.png?raw=true)

**FreeSimpleSQL** is a powerful AI-enhanced SQL database browser for SQLite with an intuitive GUI. Generate SQL queries from natural language, edit records, manage databases, and customize your experience with theme support.

## ✨ Features

### 🤖 AI-Powered SQL Generation
- **Natural Language to SQL**: Describe what you want in plain English, and let AI generate the SQL query for you
- **OpenRouter Integration**: Support for multiple AI models including Google Gemini, Claude, and more
- **Editable Results**: AI-generated queries can be manually edited before execution
- **Query History**: Track both your natural language prompts and the executed SQL queries

### 🗄️ Database Management
- **SQLite Browser**: View, search, and paginate through database records
- **Record Editing**: Double-click any row to edit records with built-in validation
- **Export/Import**: Backup and restore databases with a single click
- **Schema Viewer**: Built-in schema inspector to understand your database structure

### 🎨 User Experience
- **Theme Switching**: Choose from 100+ built-in themes with instant live preview
- **Resizable Split Panes**: Customize your workspace layout
- **Auto-save Settings**: API keys, model preferences, and themes persist across sessions
- **Pagination**: Efficiently browse large datasets with configurable page sizes

### 🛠️ Technical Features
- **Zero Manual Setup**: Generates sample data automatically on first run
- **Type Validation**: Automatic validation for IP addresses, JSON, timestamps, and more
- **Error Handling**: Comprehensive error messages with troubleshooting tips
- **Pure Python**: No external database dependencies beyond SQLite

## 🚀 Quick Start

### Installation

```sh
pip install freesimplesql
```

Or clone from GitHub and run directly:

```sh
git clone https://github.com/fxyzbtc/freesimplesql.git
cd freesimplesql
uv sync
python -m freesimplesql
```

### Running the Application

```sh
# Run as a module
uv run python -m freesimplesql

# Or run the executable (if built)
freesimplesql.exe
```

## 🔧 Configuration

### AI Integration Setup

1. **Get an API Key**: Sign up at [OpenRouter](https://openrouter.ai/keys) to get your free API key
2. **Configure in App**: Enter your API key in the AI Builder Settings section
3. **Select a Model**: Choose from available models (free models are available!)
4. **Start Generating**: Write natural language prompts and generate SQL instantly

### Settings Persistence

Your settings are automatically saved to `settings.json`:
- API URL and Model selection
- API Key (encrypted storage recommended for production)
- Selected theme
- All settings persist across sessions

## 📖 Usage Examples

### AI-Generated Queries

```
Prompt: "Show all error messages from yesterday"
Generated SQL: SELECT * FROM message WHERE msg_name = 'ERROR' AND timestamp > '2026-01-09'
```

```
Prompt: "Find messages with 'timeout' in content"
Generated SQL: SELECT * FROM message WHERE msg_content LIKE '%timeout%'
```

### Manual Editing

After AI generation, you can:
- Edit the SQL query directly in the text editor
- Click "Search" to execute your customized query
- View results in the paginated table below

### Record Editing

1. Double-click any row in the results table
2. Edit fields in the modal dialog
3. Validation ensures data integrity:
   - IP addresses must be valid IPv4/IPv6
   - JSON content is validated
   - Timestamps follow ISO format
   - Serial numbers must be integers

## 🎨 Theme Options

Choose from themes including:
- DarkBlue3 (developer favorite)
- SystemDefaultForReal (clean & professional)
- DarkGrey
- LightGreen
- And 100+ more!

Changes apply instantly without restart.

## 📊 Database Schema

The default schema includes a `message` table with:
- `id`: Primary key
- `sn`: Serial number
- `timestamp`: Message timestamp
- `src_ip`, `dst_ip`: Source and destination IPs
- `msg_name`: Message type (INFO, WARNING, ERROR, etc.)
- `msg_content`: JSON message payload
- `hexvalue`: Hex-encoded content

## 🔒 Security Notes

- API keys are stored in plaintext in `settings.json` - use environment variables in production
- The application runs locally - your data never leaves your machine
- OpenRouter communications are encrypted via HTTPS

## 🐛 Troubleshooting

### "No cookie auth credentials found" (401 Error)
- Verify your API key is correct (should start with `sk-or-...` for OpenRouter)
- Check that you're using the correct API endpoint
- Ensure your key has credits/permissions

### "KeyError" on Reset
- This has been fixed in the latest version
- Update to the latest release

## 🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

## 📄 License

MIT License - see LICENSE file for details

## 🙏 Acknowledgments

- Built with [FreeSimpleGUI](https://github.com/spyoungtech/FreeSimpleGUI)
- Powered by [SQLModel](https://sqlmodel.tiangolo.com/)
- AI integration via [OpenRouter](https://openrouter.ai)

---

**Made with ❤️ for developers who want simple, powerful database tools**