A modern, web-based SQLite database browser and query tool built for Val Town. Execute SQL queries, browse database schema, and export results with a clean, intuitive interface.

• 🔍 Database Schema Browser - View all tables and views with visual icons
• ✨ SQL Code Editor - Syntax highlighting with CodeMirror
• ⚡ Query Execution - Execute SQL queries with real-time results
• 📊 Paginated Results - Handle large datasets (100 rows per page)
• 💾 Export Data - Download results as CSV or JSON
• 🎨 Dark Mode - Automatic theme switching with warm color palette
• 💬 Query Persistence - Saves queries per table in localStorage
• ⌨️ Keyboard Shortcuts - Cmd/Ctrl+Enter to run queries
• 🔒 OAuth Authentication - Secure Val Town authentication
• 🛡️ Error Boundaries - Graceful error handling and recovery

• React 18.2.0 - UI framework
• CodeMirror 6 - SQL editor with syntax highlighting
• TailwindCSS - Styling (via Play CDN)
• TypeScript - Type safety with strict mode

• Hono 4 - Lightweight web framework
• Turso/libSQL - SQLite database (via Val Town)
• Deno - Runtime environment

• Biome - Linting and formatting
• TypeScript Strict Mode - Enhanced type safety

• A Val Town account
• Basic knowledge of SQL and TypeScript

1. Clone the repository

   git clone <your-repo-url>
   cd project-sqlite

2. Install Deno (if not already installed)

   curl -fsSL https://deno.land/x/install/install.sh | sh

3. Type check the code

   deno check --allow-import backend/index.http.ts
   deno check --allow-import frontend/main.tsx

4. Run linting

   deno run -A npm:@biomejs/biome check .

5. Format code

   deno run -A npm:@biomejs/biome format --write .

1. Create a new Val

   • Go to Val Town
   • Create a new HTTP Val

2. Copy the code

   • Copy the contents of backend/index.http.ts
   • Paste into your new Val

3. Upload frontend files

   • Upload all files from /frontend directory
   • Upload all files from /shared directory

4. Set up OAuth

   • The app automatically uses Val Town's OAuth middleware
   • No additional configuration needed

5. Access your app

   • Your app will be available at https://[username]-[valname].web.val.run

project-sqlite/
├── backend/
│   └── index.http.ts          # Main Hono server (API routes)
├── frontend/
│   ├── components/            # React components
│   │   ├── EditorSection.tsx  # SQL editor with controls
│   │   ├── ErrorBoundary.tsx  # Error boundary wrapper
│   │   ├── Table.tsx          # Paginated results table
│   │   ├── TablesList.tsx     # Schema sidebar
│   │   └── ThemeToggle.tsx    # Dark mode toggle
│   ├── hooks/                 # Custom React hooks
│   │   ├── useCodeEditor.ts   # Editor state management
│   │   ├── useDownload.ts     # Export functionality
│   │   ├── useQueryExecution.ts # Query execution
│   │   └── useTableSelection.ts # Table selection
│   ├── App.tsx                # Main application component
│   ├── index.html             # HTML template
│   └── main.tsx               # React entry point
├── shared/
│   ├── types.ts               # Shared TypeScript types
│   ├── exportHelpers.ts       # CSV/JSON export utilities
│   └── sqlHelpers.ts          # SQL parsing utilities
├── deno.json                  # Deno configuration
├── biome.json                 # Biome configuration
└── README.md                  # This file

1. Select a table from the sidebar to auto-populate the editor with SELECT * FROM [table]
2. Write or edit your SQL query in the editor
3. Press Cmd/Ctrl+Enter or click the "Run Query" button
4. View results in the paginated table below

The editor supports multiple SQL statements. It will execute the statement at your cursor position when you press Cmd/Ctrl+Enter.

1. Execute a query to get results
2. Click "Download CSV" or "Download JSON"
3. File downloads automatically with the results

• Cmd/Ctrl+Enter - Execute query at cursor
• Click table name - Auto-populate SELECT query

Returns all tables and views in the database.

Response:

{
  "tables": [{ "name": "users", "type": "table" }],
  "views": [{ "name": "active_users", "type": "view" }]
}

Executes a SQL query.

Request:

{
  "query": "SELECT * FROM users LIMIT 10"
}

Response:

{
  "success": true,
  "data": {
    "columns": ["id", "name", "email"],
    "rows": [[1, "Alice", "alice@example.com"]]
  }
}

Downloads query results as CSV.

Downloads query results as JSON.

• Component-based - Small, focused React components (~60 lines avg)
• Custom hooks - Separation of concerns for state management
• Error boundaries - Graceful error handling
• LocalStorage - Query persistence per table

• RESTful API - JSON over HTTP
• OAuth middleware - Val Town authentication
• Type-safe - Full TypeScript with strict mode
• Error handling - Proper type guards and error messages

• Strict TypeScript - noImplicitAny and strict enabled
• No any types - All values properly typed
• Type guards - Safe error handling with getErrorMessage()
• Shared types - Common types in /shared/types.ts

deno check --allow-import backend/index.http.ts
deno check --allow-import frontend/main.tsx

deno run -A npm:@biomejs/biome check .

deno run -A npm:@biomejs/biome format --write .

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strict": true,
    "lock": true
  }
}

• Tab indentation (2 spaces)
• Line width: 100 characters
• Recommended linter rules
• Auto-organize imports

• Pagination - 100 rows per page prevents browser freeze
• Efficient rendering - React memoization for optimal performance
• Lazy loading - Code splitting potential with React.lazy
• CDN assets - TailwindCSS loaded from CDN

• OAuth authentication - Required for all API routes
• Parameterized queries - SQL injection protection via Val Town SQLite
• HTTPS - Enforced by Val Town platform
• Type safety - Prevents common runtime errors

• Admin tool only - Not designed for public-facing applications
• Single database - Works with Val Town's SQLite instance
• No query history - Future enhancement planned
• 100 row pagination - Configurable in Table.tsx

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run type checks and linting
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

• Use TypeScript strict mode
• Follow existing component patterns
• Add type annotations
• Keep components under 100 lines
• Write descriptive commit messages

This project was migrated from HTMX to React on November 14, 2024. See MIGRATION_GUIDE.md for details on the migration process.

• MIGRATION_GUIDE.md - Details on the HTMX → React migration
• AGENTS.md - Guidelines for AI code generation

If you encounter type errors, ensure strict mode is enabled:

deno check --allow-import <file>

Make sure all dependencies are properly imported:

deno cache --reload backend/index.http.ts

Ensure your Val has the correct permissions and all files are uploaded.

MIT License - feel free to use this project for your own purposes.

• Built for Val Town
• Uses Turso libSQL database
• Powered by Hono web framework
• Editor by CodeMirror

For issues or questions:

1. Check existing documentation
2. Search issues in the repository
3. Create a new issue with details

Built with ❤️ for Val Town