Local Database & SQLite Migrations
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The mausVoice application utilizes a local SQLite database to manage persistent application state, user preferences, transcriptions, and encryption keys. This localized data strategy ensures that the application can function with zero network calls for transcription when using local models, while keeping sensitive data like API keys encrypted on the user's machine using XChaCha20-Poly1305.
The database architecture follows a "Rust is the API, TypeScript is the Brain" pattern. Rust handles the native capabilities, including the SQLite database connection and migration management via the tauri-plugin-sql plugin, while the TypeScript frontend orchestrates business logic and interacts with the database through defined Tauri commands.
Sources: llms.txt, apps/desktop/README.md, CLAUDE.md
Database Architecture
The database is centered around a single file named mausvoice.db. The system handles the initialization of the database file, management of the connection string, and the execution of schema migrations.
Data Flow Overview
The data flow starts from user or native events in the TypeScript frontend, which calls specific repositories. these repositories then invoke Tauri commands that interface with the Rust database layer.
The application flow ensures that business logic remains in TypeScript while Rust provides the interface to the underlying SQLite storage.
Sources: llms.txt, CLAUDE.md, apps/desktop/src-tauri/src/db/mod.rs:14-15
Connection & Constants
The database connection is managed using the following constants:
| Constant | Value | Description |
|---|---|---|
DB_FILENAME | mausvoice.db | The physical filename of the SQLite database. |
DB_CONNECTION | sqlite:mausvoice.db | The connection string used by the SQL plugin. |
Sources: apps/desktop/src-tauri/src/db/mod.rs:14-15
Filesystem & Path Management
The application manages specific paths for the database, logs, and storage. It also includes an idempotent migration path for users upgrading from the legacy "Voquill" branding.
Legacy Database Migration
When the application starts, it checks for the existence of the current database. If it is missing, it attempts to migrate data from the legacy app identifier directory (com.voquill.desktop) and database file (voquill.db). This migration includes the main database file as well as SQLite sidecar files (-wal and -shm).
Migration System
Migrations are handled via the tauri-plugin-sql migration engine. Each migration is stored as an SQL file in src-tauri/src/db/migrations/, included in the Rust binary using include_str!, and registered in the migrations() function.
Migration Management Rules
- Naming Convention: Files are named
NNN_description.sql. - Irregular Versioning: Migration version numbers are not always sequential. Specific versions (e.g., 021, 069, 070) are intentionally absent to prevent re-running migrations that were rebased during early development.
- Persistence: Once a migration is applied, it must never be renumbered.
Sources: CLAUDE.md, apps/desktop/src-tauri/src/db/mod.rs:59-70
Key Schema Migrations
The database schema has evolved through numerous migrations to support new features. Below are significant migration versions:
| Version | Description | Source File Reference |
|---|---|---|
| 1 | Initial schema creation | 000_schema.sql |
| 3 | Transcriptions table | 002_transcriptions.sql |
| 10 | API keys table | 009_api_keys.sql |
| 16 | User preferences table | 015_user_preferences.sql |
| 19 | Tones (Writing Styles) table | 018_tones.sql |
| 63 | Conversations & Chat Messages | 063_conversations_and_chat_messages.sql |
Sources: apps/desktop/src-tauri/src/db/mod.rs:73-294
Query Modules
The database logic is organized into specific query modules in the db directory, each focusing on a distinct domain of the application:
api_key_queries: Managing encrypted keys.transcription_queries: Storing and retrieving voice-to-text history.preferences_queries: Handling global application settings.tone_queries: Managing AI writing styles.hotkey_queries: Storing custom global shortcut configurations.
Sources: apps/desktop/src-tauri/src/db/mod.rs:1-12
Summary
The Local Database & SQLite Migrations system provides a robust, versioned foundation for mausVoice's data persistence. By leveraging native Rust capabilities for file operations and migrations while exposing a type-safe API to the TypeScript "Brain," the application maintains high performance and data integrity across platform-specific installs and version updates.
Sources: llms.txt, apps/desktop/src-tauri/src/db/mod.rs