5 changed files with 320 additions and 81 deletions
@ -0,0 +1,153 @@ |
|||
--- |
|||
description: |
|||
globs: |
|||
alwaysApply: true |
|||
--- |
|||
# Absurd SQL - Cursor Development Guide |
|||
|
|||
## Project Overview |
|||
Absurd SQL is a backend implementation for sql.js that enables persistent SQLite databases in the browser by using IndexedDB as a block storage system. This guide provides rules and best practices for developing with this project in Cursor. |
|||
|
|||
## Project Structure |
|||
``` |
|||
absurd-sql/ |
|||
├── src/ # Source code |
|||
├── dist/ # Built files |
|||
├── package.json # Dependencies and scripts |
|||
├── rollup.config.js # Build configuration |
|||
└── jest.config.js # Test configuration |
|||
``` |
|||
|
|||
## Development Rules |
|||
|
|||
### 1. Worker Thread Requirements |
|||
- All SQL operations MUST be performed in a worker thread |
|||
- Main thread should only handle worker initialization and communication |
|||
- Never block the main thread with database operations |
|||
|
|||
### 2. Code Organization |
|||
- Keep worker code in separate files (e.g., `*.worker.js`) |
|||
- Use ES modules for imports/exports |
|||
- Follow the project's existing module structure |
|||
|
|||
### 3. Required Headers |
|||
When developing locally or deploying, ensure these headers are set: |
|||
``` |
|||
Cross-Origin-Opener-Policy: same-origin |
|||
Cross-Origin-Embedder-Policy: require-corp |
|||
``` |
|||
|
|||
### 4. Browser Compatibility |
|||
- Primary target: Modern browsers with SharedArrayBuffer support |
|||
- Fallback mode: Safari (with limitations) |
|||
- Always test in both modes |
|||
|
|||
### 5. Database Configuration |
|||
Recommended database settings: |
|||
```sql |
|||
PRAGMA journal_mode=MEMORY; |
|||
PRAGMA page_size=8192; -- Optional, but recommended |
|||
``` |
|||
|
|||
### 6. Development Workflow |
|||
1. Install dependencies: |
|||
```bash |
|||
yarn add @jlongster/sql.js absurd-sql |
|||
``` |
|||
|
|||
2. Development commands: |
|||
- `yarn build` - Build the project |
|||
- `yarn jest` - Run tests |
|||
- `yarn serve` - Start development server |
|||
|
|||
### 7. Testing Guidelines |
|||
- Write tests for both SharedArrayBuffer and fallback modes |
|||
- Use Jest for testing |
|||
- Include performance benchmarks for critical operations |
|||
|
|||
### 8. Performance Considerations |
|||
- Use bulk operations when possible |
|||
- Monitor read/write performance |
|||
- Consider using transactions for multiple operations |
|||
- Avoid unnecessary database connections |
|||
|
|||
### 9. Error Handling |
|||
- Implement proper error handling for: |
|||
- Worker initialization failures |
|||
- Database connection issues |
|||
- Concurrent access conflicts (in fallback mode) |
|||
- Storage quota exceeded scenarios |
|||
|
|||
### 10. Security Best Practices |
|||
- Never expose database operations directly to the client |
|||
- Validate all SQL queries |
|||
- Implement proper access controls |
|||
- Handle sensitive data appropriately |
|||
|
|||
### 11. Code Style |
|||
- Follow ESLint configuration |
|||
- Use async/await for asynchronous operations |
|||
- Document complex database operations |
|||
- Include comments for non-obvious optimizations |
|||
|
|||
### 12. Debugging |
|||
- Use `jest-debug` for debugging tests |
|||
- Monitor IndexedDB usage in browser dev tools |
|||
- Check worker communication in console |
|||
- Use performance monitoring tools |
|||
|
|||
## Common Patterns |
|||
|
|||
### Worker Initialization |
|||
```javascript |
|||
// Main thread |
|||
import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread'; |
|||
|
|||
function init() { |
|||
let worker = new Worker(new URL('./index.worker.js', import.meta.url)); |
|||
initBackend(worker); |
|||
} |
|||
``` |
|||
|
|||
### Database Setup |
|||
```javascript |
|||
// Worker thread |
|||
import initSqlJs from '@jlongster/sql.js'; |
|||
import { SQLiteFS } from 'absurd-sql'; |
|||
import IndexedDBBackend from 'absurd-sql/dist/indexeddb-backend'; |
|||
|
|||
async function setupDatabase() { |
|||
let SQL = await initSqlJs({ locateFile: file => file }); |
|||
let sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend()); |
|||
SQL.register_for_idb(sqlFS); |
|||
|
|||
SQL.FS.mkdir('/sql'); |
|||
SQL.FS.mount(sqlFS, {}, '/sql'); |
|||
|
|||
return new SQL.Database('/sql/db.sqlite', { filename: true }); |
|||
} |
|||
``` |
|||
|
|||
## Troubleshooting |
|||
|
|||
### Common Issues |
|||
1. SharedArrayBuffer not available |
|||
- Check COOP/COEP headers |
|||
- Verify browser support |
|||
- Test fallback mode |
|||
|
|||
2. Worker initialization failures |
|||
- Check file paths |
|||
- Verify module imports |
|||
- Check browser console for errors |
|||
|
|||
3. Performance issues |
|||
- Monitor IndexedDB usage |
|||
- Check for unnecessary operations |
|||
- Verify transaction usage |
|||
|
|||
## Resources |
|||
- [Project Demo](https://priceless-keller-d097e5.netlify.app/) |
|||
- [Example Project](https://github.com/jlongster/absurd-example-project) |
|||
- [Blog Post](https://jlongster.com/future-sql-web) |
|||
- [SQL.js Documentation](https://github.com/sql-js/sql.js/) |
Loading…
Reference in new issue