crowd-funder-for-time-pwa/.cursor/rules/database/absurd-sql.mdc

---
globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts,
  **/src/registerSQLWorker.js, **/
services/AbsurdSqlDatabaseService.ts
alwaysApply: false
---

# Absurd SQL - Cursor Development Guide

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Database development guidelines

## 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/)

---

**Status**: Active database development guidelines
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: Absurd SQL, SQL.js, IndexedDB
**Stakeholders**: Development team, Database team

- [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/)

## Model Implementation Checklist

### Before Absurd SQL Implementation

- [ ] **Browser Support**: Verify SharedArrayBuffer and COOP/COEP support
- [ ] **Worker Setup**: Plan worker thread initialization and communication
- [ ] **Database Planning**: Plan database schema and initialization
- [ ] **Performance Planning**: Plan performance monitoring and optimization

### During Absurd SQL Implementation

- [ ] **Worker Initialization**: Set up worker threads with proper communication
- [ ] **Database Setup**: Initialize SQLite database with IndexedDB backend
- [ ] **File System**: Configure SQLiteFS with proper mounting
- [ ] **Error Handling**: Implement proper error handling for worker failures

### After Absurd SQL Implementation

- [ ] **Cross-Browser Testing**: Test across different browsers and devices
- [ ] **Performance Validation**: Monitor IndexedDB usage and performance
- [ ] **Worker Validation**: Verify worker communication and database operations
- [ ] **Documentation**: Update Absurd SQL implementation documentation