|
| 1 | +# sqlgram 🗂️ |
| 2 | + |
| 3 | +A modern, interactive PostgreSQL schema visualizer that transforms your SQL |
| 4 | +CREATE TABLE statements into beautiful, professional database diagrams. |
| 5 | + |
| 6 | +[](https://opensource.org/licenses/MIT) |
| 7 | +[](https://www.typescriptlang.org/) |
| 8 | +[](https://reactjs.org/) |
| 9 | +[](https://vitejs.dev/) |
| 10 | + |
| 11 | +## ✨ Features |
| 12 | + |
| 13 | +### 🎯 Core Functionality |
| 14 | + |
| 15 | +- **SQL to Diagram**: Instantly convert PostgreSQL CREATE TABLE statements into |
| 16 | + interactive diagrams |
| 17 | +- **Real-time Parsing**: Live error detection and syntax validation using |
| 18 | + `sql-parser-cst` |
| 19 | +- **Relationship Mapping**: Automatic detection and visualization of foreign key |
| 20 | + relationships |
| 21 | +- **Smart Layout**: Auto-arranged diagrams using Dagre layout algorithm |
| 22 | + |
| 23 | +### 🔧 Developer Experience |
| 24 | + |
| 25 | +- **Monaco Editor Integration**: Full-featured SQL editor with syntax |
| 26 | + highlighting and error markers |
| 27 | +- **Inline Error Display**: See SQL errors directly in the editor with precise |
| 28 | + line/column positioning |
| 29 | +- **Theme Support**: Light/Dark mode with system preference detection |
| 30 | +- **Export Functionality**: Download your SQL schemas (disabled for invalid SQL) |
| 31 | +- **Import/Export**: Load SQL files or save your work |
| 32 | + |
| 33 | +### 📱 User Interface |
| 34 | + |
| 35 | +- **Responsive Design**: Works seamlessly on desktop, tablet, and mobile devices |
| 36 | +- **Modern UI**: Built with Tailwind CSS and Radix UI components |
| 37 | +- **Touch-Friendly**: Optimized for mobile interactions and touch gestures |
| 38 | +- **Accessibility**: Full keyboard navigation and screen reader support |
| 39 | + |
| 40 | +### 🔍 Advanced Features |
| 41 | + |
| 42 | +- **Relationship Types**: Displays One-to-One, One-to-Many, Many-to-One, and |
| 43 | + Many-to-Many relationships |
| 44 | +- **Validation Status**: Clear indicators for SQL validity with error counts |
| 45 | +- **Table Details**: Complete column information including types, constraints, |
| 46 | + and keys |
| 47 | +- **Interactive Diagrams**: Pan, zoom, and explore your database schema |
| 48 | + |
| 49 | +## 🚀 Quick Start |
| 50 | + |
| 51 | +### Prerequisites |
| 52 | + |
| 53 | +- Node.js 18+ |
| 54 | +- npm or pnpm |
| 55 | + |
| 56 | +### Installation |
| 57 | + |
| 58 | +1. **Clone the repository** |
| 59 | + |
| 60 | +```bash |
| 61 | +git clone https://github.com/paripsky/sqlgram.git |
| 62 | +cd sqlgram |
| 63 | +``` |
| 64 | + |
| 65 | +2. **Install dependencies** |
| 66 | + |
| 67 | +```bash |
| 68 | +npm install |
| 69 | +# or |
| 70 | +pnpm install |
| 71 | +``` |
| 72 | + |
| 73 | +3. **Start development server** |
| 74 | + |
| 75 | +```bash |
| 76 | +npm run dev |
| 77 | +# or |
| 78 | +pnpm dev |
| 79 | +``` |
| 80 | + |
| 81 | +4. **Open in browser** Navigate to `http://localhost:5173` |
| 82 | + |
| 83 | +### Build for Production |
| 84 | + |
| 85 | +```bash |
| 86 | +npm run build |
| 87 | +# or |
| 88 | +pnpm build |
| 89 | +``` |
| 90 | + |
| 91 | +## 📖 Usage |
| 92 | + |
| 93 | +### Basic Example |
| 94 | + |
| 95 | +1. **Enter your SQL schema** in the editor: |
| 96 | + |
| 97 | +```sql |
| 98 | +CREATE TABLE users ( |
| 99 | + id SERIAL PRIMARY KEY, |
| 100 | + username VARCHAR(50) NOT NULL UNIQUE, |
| 101 | + email VARCHAR(100) NOT NULL UNIQUE, |
| 102 | + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP |
| 103 | +); |
| 104 | + |
| 105 | +CREATE TABLE posts ( |
| 106 | + id SERIAL PRIMARY KEY, |
| 107 | + title VARCHAR(200) NOT NULL, |
| 108 | + content TEXT, |
| 109 | + user_id INTEGER NOT NULL REFERENCES users(id), |
| 110 | + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP |
| 111 | +); |
| 112 | +``` |
| 113 | + |
| 114 | +2. **Watch the magic happen** ✨ - Your schema automatically appears as an |
| 115 | + interactive diagram! |
| 116 | + |
| 117 | +3. **Explore relationships** - See how your tables connect with labeled |
| 118 | + relationship lines |
| 119 | + |
| 120 | +### Supported SQL Features |
| 121 | + |
| 122 | +- ✅ CREATE TABLE statements |
| 123 | +- ✅ Primary keys (SERIAL, INTEGER PRIMARY KEY) |
| 124 | +- ✅ Foreign key relationships (REFERENCES) |
| 125 | +- ✅ Column constraints (NOT NULL, UNIQUE) |
| 126 | +- ✅ Data types (VARCHAR, INTEGER, TEXT, TIMESTAMP, BOOLEAN, etc.) |
| 127 | +- ✅ Default values |
| 128 | +- ✅ Composite primary keys |
| 129 | +- ✅ Junction tables (many-to-many relationships) |
| 130 | + |
| 131 | +### Error Handling |
| 132 | + |
| 133 | +sqlgram provides comprehensive error detection: |
| 134 | + |
| 135 | +- **Syntax Errors**: Real-time SQL syntax validation |
| 136 | +- **Missing References**: Detection of broken foreign key references |
| 137 | +- **Type Mismatches**: Validation of data type consistency |
| 138 | +- **Inline Markers**: Errors highlighted directly in the editor |
| 139 | + |
| 140 | +## 🛠️ Tech Stack |
| 141 | + |
| 142 | +### Frontend |
| 143 | + |
| 144 | +- **React 18** - Modern React with hooks and concurrent features |
| 145 | +- **TypeScript** - Type-safe development with full IntelliSense |
| 146 | +- **Vite** - Lightning-fast build tool and development server |
| 147 | +- **Tailwind CSS** - Utility-first CSS framework |
| 148 | + |
| 149 | +### Components & UI |
| 150 | + |
| 151 | +- **Radix UI** - Unstyled, accessible component primitives |
| 152 | +- **Lucide React** - Beautiful, customizable icons |
| 153 | +- **React Flow** - Interactive node-based diagrams |
| 154 | +- **Monaco Editor** - VS Code editor experience in the browser |
| 155 | + |
| 156 | +### Data Processing |
| 157 | + |
| 158 | +- **sql-parser-cst** - Robust PostgreSQL SQL parser |
| 159 | +- **Dagre** - Directed graph layout algorithm |
| 160 | + |
| 161 | +## 🎨 Theme Support |
| 162 | + |
| 163 | +sqlgram supports three theme modes: |
| 164 | + |
| 165 | +- **Light Mode** - Clean, bright interface |
| 166 | +- **Dark Mode** - Easy on the eyes for extended use |
| 167 | +- **System** - Automatically follows your OS preference |
| 168 | + |
| 169 | +The Monaco editor theme automatically syncs with your selected theme preference. |
| 170 | + |
| 171 | +## 📱 Mobile Support |
| 172 | + |
| 173 | +sqlgram is fully responsive and optimized for mobile devices: |
| 174 | + |
| 175 | +- Touch-friendly interface with appropriate touch targets |
| 176 | +- Tabbed layout on mobile for better space utilization |
| 177 | +- Optimized diagram controls for touch interaction |
| 178 | +- Prevents zoom on form inputs for better UX |
| 179 | + |
| 180 | +## 🤝 Contributing |
| 181 | + |
| 182 | +We welcome contributions! Here's how you can help: |
| 183 | + |
| 184 | +### Development Setup |
| 185 | + |
| 186 | +1. Fork the repository |
| 187 | +2. Create a feature branch: `git checkout -b feature/amazing-feature` |
| 188 | +3. Make your changes |
| 189 | +4. Run tests: `npm run test` |
| 190 | +5. Commit your changes: `git commit -m 'Add amazing feature'` |
| 191 | +6. Push to the branch: `git push origin feature/amazing-feature` |
| 192 | +7. Open a Pull Request |
| 193 | + |
| 194 | +### Code Style |
| 195 | + |
| 196 | +- Use TypeScript for all new code |
| 197 | +- Follow the existing ESLint configuration |
| 198 | +- Write meaningful commit messages |
| 199 | +- Add JSDoc comments for complex functions |
| 200 | + |
| 201 | +## 📝 License |
| 202 | + |
| 203 | +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file |
| 204 | +for details. |
| 205 | + |
| 206 | +## 🙏 Acknowledgments |
| 207 | + |
| 208 | +- **sql-parser-cst** - For robust SQL parsing capabilities |
| 209 | +- **React Flow** - For the amazing diagram visualization |
| 210 | +- **Monaco Editor** - For bringing VS Code editor experience to the web |
| 211 | +- **Radix UI** - For accessible, unstyled component primitives |
| 212 | +- **Tailwind CSS** - For the utility-first CSS framework |
| 213 | + |
| 214 | +## 🔮 Roadmap |
| 215 | + |
| 216 | +- [ ] Support for additional SQL dialects (MySQL, SQLite) |
| 217 | +- [ ] Schema comparison and diff visualization |
| 218 | +- [ ] Export to various formats (PNG, SVG, PDF) |
| 219 | +- [ ] Collaborative editing features |
| 220 | +- [ ] Schema version history |
| 221 | +- [ ] Integration with popular databases |
| 222 | +- [ ] Advanced relationship editing |
| 223 | +- [ ] Custom diagram themes |
| 224 | + |
| 225 | +## 📞 Support |
| 226 | + |
| 227 | +- **Documentation**: Check this README and inline help |
| 228 | +- **Issues**: Report bugs on |
| 229 | + [GitHub Issues](https://github.com/paripsky/sqlgram/issues) |
| 230 | +- **Discussions**: Join conversations in |
| 231 | + [GitHub Discussions](https://github.com/paripsky/sqlgram/discussions) |
| 232 | + |
| 233 | +## 🌟 Show Your Support |
| 234 | + |
| 235 | +If sqlgram helps you visualize your database schemas, please consider: |
| 236 | + |
| 237 | +- ⭐ Starring the repository |
| 238 | +- 🐛 Reporting bugs |
| 239 | +- 💡 Suggesting new features |
| 240 | +- 🤝 Contributing code |
| 241 | +- 📢 Sharing with colleagues |
| 242 | + |
| 243 | +--- |
| 244 | + |
| 245 | +<div align="center"> |
| 246 | + <p>Built with ❤️ for developers, by developers</p> |
| 247 | + <p><strong>sqlgram</strong> - Making database schemas beautiful, one diagram at a time</p> |
| 248 | +</div> |
0 commit comments