Function Overriding API

Intercepts SELECT queries going to the main active database. Every time an extension calls HPR.dbQuery_E(), this hook fires first. You can return fake/mock data, filter out sensitive rows, or redirect queries entirely. The return format is an array of tables, where each table is a row with column-name → value pairs.

HPR.overrides.dbQuery = function(sql, params)
    -- Intercept app_usage queries and return mock data
    if sql:find("app_usage") then
        return {
            { name = "VS Code", duration = "7200000" },
            { name = "Firefox", duration = "3600000" },
        }
    end
    return nil  -- all other queries run normally
end

Intercepts write operations — INSERT, UPDATE, DELETE, and any other non-SELECT SQL statements. This is a powerful safety net: you can block destructive writes, log all mutations for auditing, or conditionally prevent data from being recorded. Return any value to prevent the write from hitting the database.

HPR.overrides.dbExecute = function(sql, params)
    -- Never allow any DELETE operations
    if sql:upper():find("DELETE") then
        print("[BLOCKED] Attempted DELETE: " .. sql)
        return true  -- blocks the execution
    end
    
    -- Log all writes for auditing
    print("[DB WRITE] " .. sql)
    return nil  -- let it through
end

Like dbQuery, but for queries targeting a specific database file path rather than the main active database. Extensions can query arbitrary .db files on disk, and this hook lets you intercept those. Useful for mocking historical data or redirecting queries to a different database entirely.

HPR.overrides.dbQueryPath = function(dbPath, sql, params)
    print("[dbQueryPath] " .. dbPath .. " → " .. sql)
    
    -- Block queries to databases outside HPR's data dir
    if not dbPath:find("HPR") then
        print("[BLOCKED] Query to external db!")
        return {}  -- return empty results
    end
    return nil
end

Intercepts SELECT queries against the currently loaded historical database. When users view past data (e.g., "show me last Tuesday's stats"), HPR loads a historical .db file. This hook lets you mock historical data for testing, inject computed/aggregated values, or filter out rows you don't want displayed.

HPR.overrides.dbQueryHistorical = function(sql, params)
    -- Return fake data for demo mode
    if sql:find("app_usage") then
        return {
            { name = "Productivity Suite", duration = "14400000" },
            { name = "Research", duration = "10800000" },
            { name = "Communication", duration = "3600000" },
        }
    end
    return nil
end

Returns the file path of the currently loaded historical database. Other extensions or internal code might use this to know which .db file is active for historical queries. Override this to spoof the path — useful for pointing the system at a custom database location or for testing purposes.

HPR.overrides.getLoadedHistDbPath = function()
    -- Always report our custom test database
    return "/home/user/.local/share/HPR/test_data/demo.db"
end

Resolves which .db file to use for a given date. HPR organizes data by date (e.g., 01-06-2026.db) in month-based folders. Override this to implement custom database storage schemes — maybe you want all databases in one flat folder, or you want to redirect to a network-mounted path, or you're building a backup system.

HPR.overrides.getDbPathForDate = function(date)
    -- Store all databases in a flat directory
    return "/mnt/nas/hpr-data/" .. date .. ".db"
end