Browse Source
- Fix logToDb() to use actual database schema: 'date' and 'message' columns - Change INSERT query from non-existent 'timestamp, level' to existing 'date, message' - Change DELETE cleanup to use 'date' column instead of 'timestamp' - Embed log level in message text as '[LEVEL] message' instead of separate column - Use toDateString() format to match schema instead of toISOString() Resolves: "table logs has no column named timestamp" infinite error loop Critical: Enables Electron app initialization by matching code to existing schema Impact: Stops database logging from crashing and allows normal app startupstreamline-attempt
Matthew Raymer
4 days ago
6 changed files with 127 additions and 606 deletions
@ -0,0 +1,6 @@ |
|||
--- |
|||
description: |
|||
globs: |
|||
alwaysApply: true |
|||
--- |
|||
All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions. |
|||
@ -1,267 +0,0 @@ |
|||
--- |
|||
description: |
|||
globs: |
|||
alwaysApply: true |
|||
--- |
|||
# wa-sqlite Usage Guide |
|||
|
|||
## Table of Contents |
|||
- [1. Overview](#1-overview) |
|||
- [2. Installation](#2-installation) |
|||
- [3. Basic Setup](#3-basic-setup) |
|||
- [3.1 Import and Initialize](#31-import-and-initialize) |
|||
- [3.2 Basic Database Operations](#32-basic-database-operations) |
|||
- [4. Virtual File Systems (VFS)](#4-virtual-file-systems-vfs) |
|||
- [4.1 Available VFS Options](#41-available-vfs-options) |
|||
- [4.2 Using a VFS](#42-using-a-vfs) |
|||
- [5. Best Practices](#5-best-practices) |
|||
- [5.1 Error Handling](#51-error-handling) |
|||
- [5.2 Transaction Management](#52-transaction-management) |
|||
- [5.3 Prepared Statements](#53-prepared-statements) |
|||
- [6. Performance Considerations](#6-performance-considerations) |
|||
- [7. Common Issues and Solutions](#7-common-issues-and-solutions) |
|||
- [8. TypeScript Support](#8-typescript-support) |
|||
|
|||
## 1. Overview |
|||
wa-sqlite is a WebAssembly build of SQLite that enables SQLite database operations in web browsers and JavaScript environments. It provides both synchronous and asynchronous builds, with support for custom virtual file systems (VFS) for persistent storage. |
|||
|
|||
## 2. Installation |
|||
```bash |
|||
npm install wa-sqlite |
|||
# or |
|||
yarn add wa-sqlite |
|||
``` |
|||
|
|||
## 3. Basic Setup |
|||
|
|||
### 3.1 Import and Initialize |
|||
```javascript |
|||
// Choose one of these imports based on your needs: |
|||
// - wa-sqlite.mjs: Synchronous build |
|||
// - wa-sqlite-async.mjs: Asynchronous build (required for async VFS) |
|||
// - wa-sqlite-jspi.mjs: JSPI-based async build (experimental, Chromium only) |
|||
import SQLiteESMFactory from 'wa-sqlite/dist/wa-sqlite.mjs'; |
|||
import * as SQLite from 'wa-sqlite'; |
|||
|
|||
async function initDatabase() { |
|||
// Initialize SQLite module |
|||
const module = await SQLiteESMFactory(); |
|||
const sqlite3 = SQLite.Factory(module); |
|||
|
|||
// Open database (returns a Promise) |
|||
const db = await sqlite3.open_v2('myDatabase'); |
|||
return { sqlite3, db }; |
|||
} |
|||
``` |
|||
|
|||
### 3.2 Basic Database Operations |
|||
```javascript |
|||
async function basicOperations() { |
|||
const { sqlite3, db } = await initDatabase(); |
|||
|
|||
try { |
|||
// Create a table |
|||
await sqlite3.exec(db, ` |
|||
CREATE TABLE IF NOT EXISTS users ( |
|||
id INTEGER PRIMARY KEY, |
|||
name TEXT NOT NULL, |
|||
email TEXT UNIQUE |
|||
) |
|||
`); |
|||
|
|||
// Insert data |
|||
await sqlite3.exec(db, ` |
|||
INSERT INTO users (name, email) |
|||
VALUES ('John Doe', 'john@example.com') |
|||
`); |
|||
|
|||
// Query data |
|||
const results = []; |
|||
await sqlite3.exec(db, 'SELECT * FROM users', (row, columns) => { |
|||
results.push({ row, columns }); |
|||
}); |
|||
|
|||
return results; |
|||
} finally { |
|||
// Always close the database when done |
|||
await sqlite3.close(db); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## 4. Virtual File Systems (VFS) |
|||
|
|||
### 4.1 Available VFS Options |
|||
wa-sqlite provides several VFS implementations for persistent storage: |
|||
|
|||
1. **IDBBatchAtomicVFS** (Recommended for general use) |
|||
- Uses IndexedDB with batch atomic writes |
|||
- Works in all contexts (Window, Worker, Service Worker) |
|||
- Supports WAL mode |
|||
- Best performance with `PRAGMA synchronous=normal` |
|||
|
|||
2. **IDBMirrorVFS** |
|||
- Keeps files in memory, persists to IndexedDB |
|||
- Works in all contexts |
|||
- Good for smaller databases |
|||
|
|||
3. **OPFS-based VFS** (Origin Private File System) |
|||
- Various implementations available: |
|||
- AccessHandlePoolVFS |
|||
- OPFSAdaptiveVFS |
|||
- OPFSCoopSyncVFS |
|||
- OPFSPermutedVFS |
|||
- Better performance but limited to Worker contexts |
|||
|
|||
### 4.2 Using a VFS |
|||
```javascript |
|||
import { IDBBatchAtomicVFS } from 'wa-sqlite/src/examples/IDBBatchAtomicVFS.js'; |
|||
import SQLiteESMFactory from 'wa-sqlite/dist/wa-sqlite-async.mjs'; |
|||
import * as SQLite from 'wa-sqlite'; |
|||
|
|||
async function initDatabaseWithVFS() { |
|||
const module = await SQLiteESMFactory(); |
|||
const sqlite3 = SQLite.Factory(module); |
|||
|
|||
// Register VFS |
|||
const vfs = await IDBBatchAtomicVFS.create('myApp', module); |
|||
sqlite3.vfs_register(vfs, true); |
|||
|
|||
// Open database with VFS |
|||
const db = await sqlite3.open_v2('myDatabase'); |
|||
|
|||
// Configure for better performance |
|||
await sqlite3.exec(db, 'PRAGMA synchronous = normal'); |
|||
await sqlite3.exec(db, 'PRAGMA journal_mode = WAL'); |
|||
|
|||
return { sqlite3, db }; |
|||
} |
|||
``` |
|||
|
|||
## 5. Best Practices |
|||
|
|||
### 5.1 Error Handling |
|||
```javascript |
|||
async function safeDatabaseOperation() { |
|||
const { sqlite3, db } = await initDatabase(); |
|||
|
|||
try { |
|||
await sqlite3.exec(db, 'SELECT * FROM non_existent_table'); |
|||
} catch (error) { |
|||
if (error.code === SQLite.SQLITE_ERROR) { |
|||
console.error('SQL error:', error.message); |
|||
} else { |
|||
console.error('Database error:', error); |
|||
} |
|||
} finally { |
|||
await sqlite3.close(db); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 5.2 Transaction Management |
|||
```javascript |
|||
async function transactionExample() { |
|||
const { sqlite3, db } = await initDatabase(); |
|||
|
|||
try { |
|||
await sqlite3.exec(db, 'BEGIN TRANSACTION'); |
|||
|
|||
// Perform multiple operations |
|||
await sqlite3.exec(db, 'INSERT INTO users (name) VALUES (?)', ['Alice']); |
|||
await sqlite3.exec(db, 'INSERT INTO users (name) VALUES (?)', ['Bob']); |
|||
|
|||
await sqlite3.exec(db, 'COMMIT'); |
|||
} catch (error) { |
|||
await sqlite3.exec(db, 'ROLLBACK'); |
|||
throw error; |
|||
} finally { |
|||
await sqlite3.close(db); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 5.3 Prepared Statements |
|||
```javascript |
|||
async function preparedStatementExample() { |
|||
const { sqlite3, db } = await initDatabase(); |
|||
|
|||
try { |
|||
// Prepare statement |
|||
const stmt = await sqlite3.prepare(db, 'SELECT * FROM users WHERE id = ?'); |
|||
|
|||
// Execute with different parameters |
|||
await sqlite3.bind(stmt, 1, 1); |
|||
while (await sqlite3.step(stmt) === SQLite.SQLITE_ROW) { |
|||
const row = sqlite3.row(stmt); |
|||
console.log(row); |
|||
} |
|||
|
|||
// Reset and reuse |
|||
await sqlite3.reset(stmt); |
|||
await sqlite3.bind(stmt, 1, 2); |
|||
// ... execute again |
|||
|
|||
await sqlite3.finalize(stmt); |
|||
} finally { |
|||
await sqlite3.close(db); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## 6. Performance Considerations |
|||
|
|||
1. **VFS Selection** |
|||
- Use IDBBatchAtomicVFS for general-purpose applications |
|||
- Consider OPFS-based VFS for better performance in Worker contexts |
|||
- Use MemoryVFS for temporary databases |
|||
|
|||
2. **Configuration** |
|||
- Set appropriate page size (default is usually fine) |
|||
- Use WAL mode for better concurrency |
|||
- Consider `PRAGMA synchronous=normal` for better performance |
|||
- Adjust cache size based on your needs |
|||
|
|||
3. **Concurrency** |
|||
- Use transactions for multiple operations |
|||
- Be aware of VFS-specific concurrency limitations |
|||
- Consider using Web Workers for heavy database operations |
|||
|
|||
## 7. Common Issues and Solutions |
|||
|
|||
1. **Database Locking** |
|||
- Use appropriate transaction isolation levels |
|||
- Implement retry logic for busy errors |
|||
- Consider using WAL mode |
|||
|
|||
2. **Storage Limitations** |
|||
- Be aware of browser storage quotas |
|||
- Implement cleanup strategies |
|||
- Monitor database size |
|||
|
|||
3. **Cross-Context Access** |
|||
- Use appropriate VFS for your context |
|||
- Consider message passing for cross-context communication |
|||
- Be aware of storage access limitations |
|||
|
|||
## 8. TypeScript Support |
|||
wa-sqlite includes TypeScript definitions. The main types are: |
|||
|
|||
```typescript |
|||
type SQLiteCompatibleType = number | string | Uint8Array | Array<number> | bigint | null; |
|||
|
|||
interface SQLiteAPI { |
|||
open_v2(filename: string, flags?: number, zVfs?: string): Promise<number>; |
|||
exec(db: number, sql: string, callback?: (row: any[], columns: string[]) => void): Promise<number>; |
|||
close(db: number): Promise<number>; |
|||
// ... other methods |
|||
} |
|||
``` |
|||
|
|||
## Additional Resources |
|||
|
|||
- [Official GitHub Repository](https://github.com/rhashimoto/wa-sqlite) |
|||
- [Online Demo](https://rhashimoto.github.io/wa-sqlite/demo/) |
|||
- [API Reference](https://rhashimoto.github.io/wa-sqlite/docs/) |
|||
- [FAQ](https://github.com/rhashimoto/wa-sqlite/issues?q=is%3Aissue+label%3Afaq+) |
|||
- [Discussion Forums](https://github.com/rhashimoto/wa-sqlite/discussions) |
|||
Loading…
Reference in new issue