database-operations

tumma72's avatarfrom tumma72

SQLite database, DBManager, HybridStorage, and schema operations for GMailArchiver. Use when working with database queries, transactions, mbox offsets, FTS5 search, or data integrity. Triggers on: database, SQLite, DBManager, HybridStorage, schema, transaction, mbox offset, FTS5, integrity, migration.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 23, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill provides comprehensive technical guidance for managing the SQLite data layer within the GMailArchiver ecosystem. It specializes in DBManager operations, HybridStorage patterns, and schema management, ensuring robust data integrity, efficient FTS5 full-text search indexing, and seamless transaction handling for email archiving workflows.

Use Cases

  • Developing and optimizing complex SQLite queries and transactions to ensure high-performance data persistence.
  • Managing database schema migrations and versioning using SchemaManager to maintain system stability during updates.
  • Implementing and troubleshooting FTS5 search indexes to enable fast, full-text search capabilities across large email archives.
  • Performing data integrity audits and consistency checks between SQLite records and mbox file offsets using specialized CLI commands.
  • Architecting atomic write patterns and hybrid storage solutions to prevent data corruption in high-concurrency environments.
namedatabase-operations
description>-
or data integrity. Triggers ondatabase, SQLite, DBManager, HybridStorage,

Database Operations in GMailArchiver

This skill provides guidance on database operations for GMailArchiver.

Source Documentation

Always read the authoritative sources for current database design:

  1. src/gmailarchiver/data/ARCHITECTURE.md - Data layer architecture:

    • DBManager responsibilities and interface
    • HybridStorage atomic write patterns
    • SchemaManager version handling
    • Transaction management
    • Integrity validation
  2. docs/ARCHITECTURE.md - System-wide data architecture:

    • Database schema (tables, columns, relationships)
    • FTS5 search index configuration
    • Data integrity architecture
    • Safety guarantees
  3. CLAUDE.md - Quick reference:

    • Database schema summary
    • Key interfaces overview
    • CLI commands for database operations

Key Components

Read these files for implementation details:

  • src/gmailarchiver/data/db_manager.py - DBManager class
  • src/gmailarchiver/data/hybrid_storage.py - HybridStorage class
  • src/gmailarchiver/data/schema_manager.py - SchemaManager class

Database CLI Commands

uv run gmailarchiver db-info           # Show database statistics
uv run gmailarchiver verify-integrity  # Check schema and constraints
uv run gmailarchiver verify-consistency # Check DB ↔ mbox sync
uv run gmailarchiver verify-offsets    # Validate mbox offsets
uv run gmailarchiver repair --backfill # Fix issues

Usage

When working with database code:

  1. Read src/gmailarchiver/data/ARCHITECTURE.md for current design
  2. Check docs/ARCHITECTURE.md for schema details
  3. If schema or patterns change, update the documentation (not this skill)

The source documentation is the single source of truth - this skill just points you there.