# How to Use the SQLite Handler for .db Files in the Browser: A Complete Guide

> Learn how to use the SQLite handler to convert .db files to CSV directly in your browser convert SQLite databases online without server-side processing using the official SQLite WebAssembly module

- Repository: [p2r3/convert](https://github.com/p2r3/convert)
- Tags: how-to-guide
- Published: 2026-02-19

---

**The SQLite handler (`sqlite3Handler`) enables browser-based conversion of SQLite .db files to CSV by loading the official SQLite WebAssembly module, deserializing the database into memory, and exporting each table as a separate CSV file without any server-side processing.**

The p2r3/convert repository provides a client-side file conversion framework that runs entirely in the browser. By implementing the `FormatHandler` interface, the SQLite handler for .db files allows developers to parse SQLite databases and extract tabular data as CSV using WebAssembly, eliminating the need for backend infrastructure.

## How the SQLite Handler Works

### Architecture Overview

The handler follows the generic `FormatHandler` contract defined in [`src/FormatHandler.ts`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts). It acts as a bridge between the browser's file API and the SQLite WebAssembly runtime, converting binary `.db` files into structured CSV exports entirely within the client's memory space.

### Registration and Format Declaration

In [`src/handlers/index.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/index.ts), the handler is instantiated and registered with the global handler list at lines 55-56:

```typescript
import sqlite3Handler from "./sqlite.ts";
// ...
handlers.push(new sqlite3Handler());

```

This registration enables the application to recognize files with the `.db` extension and MIME type `application/vnd.sqlite3`.

The handler declares its capabilities in [`src/handlers/sqlite.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/sqlite.ts) through the `supportedFormats` array (lines 12-26), specifying SQLite3 as input and CSV as the output format:

```typescript
supportedFormats = [
  {
    id: "sqlite3",
    name: "SQLite3 Database",
    extension: "db",
    mimeType: "application/vnd.sqlite3",
  },
  {
    id: "csv",
    name: "CSV",
    extension: "csv",
    mimeType: "text/csv",
    lossy: true,
    description: "Table data only; indexes and triggers are not preserved",
  },
];

```

### WASM Initialization and Database Loading

When conversion begins, the handler lazily loads the official SQLite WebAssembly module from `@sqlite.org/sqlite-wasm`. In [`src/handlers/sqlite.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/sqlite.ts) at line 50, the initialization occurs:

```typescript
const sqlite3 = await sqlite3InitModule();

```

The handler then deserializes the uploaded `.db` file into the WASM memory heap. At lines 54-68, the process allocates memory using `sqlite3.wasm.allocFromTypedArray` and attaches the buffer to an in-memory database instance via `sqlite3.capi.sqlite3_deserialize`:

```typescript
const p = sqlite3.wasm.allocFromTypedArray(bytes);
const db = new sqlite3.oo1.DB(":memory:", "ct");
sqlite3.capi.sqlite3_deserialize(
  db.pointer,
  "main",
  p,
  bytes.length,
  bytes.length,
  sqlite3.capi.SQLITE_DESERIALIZE_FREEONCLOSE
);

```

## Step-by-Step Implementation Guide

### Registering the Handler

To enable SQLite support in your Convert instance, ensure the handler is imported and registered. The standard entry point in [`src/handlers/index.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/index.ts) automatically pushes `sqlite3Handler` to the global `handlers` array:

```typescript
import "./src/handlers/index.ts"; // Side-effect: registers all handlers including SQLite

```

### Converting a .db File to CSV

Use the central `convertFiles` method from [`src/main.ts`](https://github.com/p2r3/convert/blob/main/src/main.ts) to process user-uploaded files. This example demonstrates reading a file from an HTML input element and converting it to multiple CSV files (one per table):

```typescript
import convert from "./src/main.ts";

// HTML file input element
const fileInput = document.querySelector<HTMLInputElement>("#db-file");

fileInput?.addEventListener("change", async (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (!file) return;

  // Read file into Uint8Array
  const bytes = new Uint8Array(await file.arrayBuffer());
  const input = { name: file.name, bytes };

  // Perform conversion
  const csvFiles = await convert.convertFiles(
    [input],
    "sqlite3", // Input format ID from supportedFormats
    "csv"      // Output format ID
  );

  // Download each table as a separate CSV
  csvFiles.forEach(({ name, bytes }) => {
    const blob = new Blob([bytes], { type: "text/csv;charset=utf-8" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = `${name}.csv`;
    a.click();
    URL.revokeObjectURL(url);
  });
});

```

### Direct Handler Invocation

For advanced use cases, instantiate the handler directly to bypass the generic conversion facade:

```typescript
import sqlite3Handler from "./src/handlers/sqlite.ts";

const handler = new sqlite3Handler();
await handler.init(); // Loads the WASM module

const csvFiles = await handler.doConvert(
  [{ name: "data.db", bytes: fileBytes }],
  { internal: "sqlite3", id: "sqlite3", name: "SQLite3" },
  { internal: "csv", id: "csv", name: "CSV" }
);

```

## Key Source Files and Methods

Understanding the codebase structure helps when extending or debugging the SQLite handler:

- **[`src/handlers/sqlite.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/sqlite.ts)** – Core implementation containing the `sqlite3Handler` class, `doConvert` method, and `getTables` helper.
- **[`src/handlers/index.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/index.ts)** – Registration point where the handler is instantiated and pushed to the global `handlers` array (lines 55-56).
- **[`src/FormatHandler.ts`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts)** – Defines the `FormatHandler` interface and `FileData` contract used across all handlers.
- **[`src/main.ts`](https://github.com/p2r3/convert/blob/main/src/main.ts)** – Exposes the `convertFiles` orchestration method that routes files to appropriate handlers based on format IDs.
- **[`package.json`](https://github.com/p2r3/convert/blob/main/package.json)** – Declares the `@sqlite.org/sqlite-wasm` dependency required for in-browser SQLite parsing.

## Summary

- The **SQLite handler** (`sqlite3Handler`) enables fully client-side conversion of `.db` files to CSV using WebAssembly.
- The handler registers itself in [`src/handlers/index.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/index.ts) and declares support for SQLite3 input and CSV output in [`src/handlers/sqlite.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/sqlite.ts).
- It utilizes the official `@sqlite.org/sqlite-wasm` package to deserialize database files into memory and execute SQL queries.
- The `getTables()` method enumerates tables using `sqlite_master`, while `doConvert()` exports each table as a separate CSV file.
- Developers can invoke the handler through the central `convertFiles()` API or instantiate `sqlite3Handler` directly for fine-grained control.

## Frequently Asked Questions

### What dependencies are required to use the SQLite handler in the browser?

The handler requires the `@sqlite.org/sqlite-wasm` package, which provides the official SQLite WebAssembly build. This dependency is declared in [`package.json`](https://github.com/p2r3/convert/blob/main/package.json) and is loaded lazily when the handler's `init()` method is called, ensuring the WASM runtime is only fetched when needed.

### Can the SQLite handler export database objects other than tables?

No, the current implementation only exports table data. According to the `supportedFormats` definition in [`src/handlers/sqlite.ts`](https://github.com/p2r3/convert/blob/main/src/handlers/sqlite.ts), the conversion is **lossy** and specifically excludes indexes, triggers, views, and other database objects. Only the data rows from tables found in `sqlite_master` are converted to CSV format.

### Is the SQLite handler compatible with all SQLite .db file versions?

The handler relies on the official `@sqlite.org/sqlite-wasm` package, which supports standard SQLite 3 database formats. However, compatibility depends on the specific WASM build version specified in the project's dependencies. Databases using very recent SQLite features or non-standard extensions may require updating the WASM dependency in [`package.json`](https://github.com/p2r3/convert/blob/main/package.json).

### How does the handler handle large .db files in the browser?

The handler loads the entire database file into WebAssembly memory using `sqlite3.wasm.allocFromTypedArray` and `sqlite3.capi.sqlite3_deserialize`. This means the entire `.db` file must fit within the browser's available memory and the WASM heap limits. For extremely large databases, this may cause performance issues or out-of-memory errors, as the current implementation does not support streaming or chunked processing.