mediadb

package
v2.16.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 6, 2026 License: GPL-3.0 Imports: 37 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	IndexingStatusRunning   = "running"
	IndexingStatusPending   = "pending"
	IndexingStatusCompleted = "completed"
	IndexingStatusFailed    = "failed"
	IndexingStatusCancelled = "cancelled"
	IndexingStatusCorrupt   = "corrupt"
)

Indexing status constants

View Source 
const (
	DBConfigLastGeneratedAt                 = "LastGeneratedAt"
	DBConfigOptimizationStatus              = "OptimizationStatus"
	DBConfigOptimizationStep                = "OptimizationStep"
	DBConfigIndexingStatus                  = "IndexingStatus"
	DBConfigScrapingStatus                  = "ScrapingStatus"
	DBConfigScrapingOperation               = "ScrapingOperation"
	DBConfigLastIndexedSystem               = "LastIndexedSystem"
	DBConfigIndexingSystems                 = "IndexingSystems"
	DBConfigIndexingPlanSystems             = "IndexingPlanSystems"
	DBConfigBrowseIndexVersion              = "BrowseIndexVersion"
	DBConfigMediaTotalCount                 = "MediaTotalCount"
	DBConfigMediaMissingCount               = "MediaMissingCount"
	DBConfigTemporaryRepairParentDirVersion = "TemporaryRepairParentDirVersion"
	DBConfigIndexGeneration                 = "IndexGeneration"
	DBConfigIndexResumeAttempts             = "IndexResumeAttempts"
	DBConfigIndexResumeCheckpoint           = "IndexResumeCheckpoint"
	DBConfigDisambiguationVersion           = "DisambiguationVersion"
	DBConfigDisambiguationBackfillCursor    = "DisambiguationBackfillCursor"
	DBConfigCanonicalTagVocabHash           = "CanonicalTagVocabHash"
)
View Source 
const SlugSearchCacheFileName = "slug_search_cache.gob"

SlugSearchCacheFileName is the on-disk filename used by the persisted slug search cache, resolved against the cache subdirectory of the data dir.

View Source 
const TagCacheFileName = "tag_cache.gob"

TagCacheFileName is the on-disk filename used by the persisted tag cache, resolved against the cache subdirectory of the data dir.

Variables

View Source 
var ErrDependencyFlush = errors.New("dependency flush failed")

ErrDependencyFlush is returned by Flush when a dependency batch inserter fails. Callers can detect this via errors.Is to distinguish a parent-table flush failure from a local constraint violation.

View Source 
var ErrIndexingInProgress = errors.New("indexing is in progress")

ErrIndexingInProgress is returned by CleanMediaOrphans when media indexing is currently running or pending; deletions during that window could corrupt in-flight scanner state.

View Source 
var ErrNullSQL = errors.New("MediaDB is not connected")
View Source 
var ErrOptimizationInProgress = errors.New("background optimisation is in progress")

ErrOptimizationInProgress is returned by CleanMediaOrphans when background database optimisation is active.

View Source 
var ErrTransactionActive = errors.New("a transaction is currently active")

ErrTransactionActive is returned by CleanMediaOrphans when a batch transaction is currently open.

View Source 
var ErrTransactionRequired = errors.New("reconciling staged media requires an open transaction")

ErrTransactionRequired is returned by ReconcileStagedSystem when called outside the scanner's open batch transaction.

Functions

func BrowseNameFirstChar added in v2.12.0 

func BrowseNameFirstChar(name string) string

BrowseNameFirstChar returns the indexed first-character bucket used by media.browse letter filters.

func BuildLetterFilterSQL added in v2.10.0 

func BuildLetterFilterSQL(letter *string, column string) (clauses []string, args []any)

BuildLetterFilterSQL constructs SQL WHERE clauses for filtering by the first character of a column. Supports single letters (A-Z), "0-9" for numeric starts, and "#" for symbols (non-alphanumeric).

The column parameter is the SQL expression to filter on, e.g., "MediaTitles.Name" or "mt.Name".

Returns clauses and args in the same format as BuildTagFilterSQL.

func BuildTagFilterSQL added in v2.7.0 

func BuildTagFilterSQL(filters []zapscript.TagFilter) (clauses []string, args []any)

BuildTagFilterSQL constructs SQL WHERE clauses and arguments for tag filtering using a hybrid strategy optimized for SQLite performance:

  • AND filters: INTERSECT pattern
  • NOT filters: forward NOT IN anti-set
  • OR filters: EXISTS with OR conditions

Returns a slice of WHERE clause strings and corresponding arguments. Clauses should be joined with " AND " and appended to the main query's WHERE conditions.

func ParentDirForMediaPath added in v2.12.0 

func ParentDirForMediaPath(path string) string

ParentDirForMediaPath returns the immediate browse parent for an indexed media path.

Types

type BatchInserter added in v2.7.0 

type BatchInserter struct {
	// contains filtered or unexported fields
}

BatchInserter manages batched multi-row inserts for a specific table

func NewBatchInserter added in v2.7.0 

func NewBatchInserter(
	ctx context.Context,
	tx *sql.Tx,
	tableName string,
	columns []string,
	batchSize int,
) (*BatchInserter, error)

NewBatchInserter creates a batch inserter for the given table

func NewBatchInserterWithOptions added in v2.7.0 

func NewBatchInserterWithOptions(
	ctx context.Context,
	tx *sql.Tx,
	tableName string,
	columns []string,
	batchSize int,
	orIgnore bool,
) (*BatchInserter, error)

NewBatchInserterWithOptions creates a batch inserter with OR IGNORE option

func (*BatchInserter) Add added in v2.7.0 

func (b *BatchInserter) Add(values ...any) error

Add appends a row to the current batch and auto-flushes when the batch size is reached. Dependency ordering ensures parent tables are flushed before children, preventing FK violations.

func (*BatchInserter) Close added in v2.7.0 

func (b *BatchInserter) Close() error

Close flushes remaining items and closes all cached statements

func (*BatchInserter) Flush added in v2.7.0 

func (b *BatchInserter) Flush() error

Flush executes the current batch and resets the buffer

func (*BatchInserter) SetDependencies added in v2.7.0 

func (b *BatchInserter) SetDependencies(deps ...*BatchInserter)

SetDependencies sets the parent batch inserters that must flush before this one

type MediaDB 

type MediaDB struct {
	// contains filtered or unexported fields
}

func OpenMediaDB 

func OpenMediaDB(ctx context.Context, pl platforms.Platform) (*MediaDB, error)

func (*MediaDB) Allocate 

func (db *MediaDB) Allocate() error

func (*MediaDB) Analyze added in v2.7.0 

func (db *MediaDB) Analyze() error

func (*MediaDB) AnalyzeApproximate added in v2.14.1 

func (db *MediaDB) AnalyzeApproximate() error

AnalyzeApproximate refreshes query-planner statistics before synchronous cache builds. PRAGMA optimize is intentionally used instead of raw ANALYZE: on modern SQLite it bounds analysis work automatically and only refreshes tables likely to benefit, which avoids multi-minute full-index scans on slow MiSTer storage.

func (*MediaDB) ApplyScrapeResult added in v2.12.0 

func (db *MediaDB) ApplyScrapeResult(
	ctx context.Context, mediaDBID, mediaTitleDBID int64, write *database.ScrapeWrite,
) (retErr error)

ApplyScrapeResult writes all scraper metadata for a match in one transaction. The sentinel tag is inserted last so interrupted writes remain retryable.

func (*MediaDB) ApplyScrapeResults added in v2.14.0 

func (db *MediaDB) ApplyScrapeResults(ctx context.Context, targets []database.ScrapeWriteTarget) (retErr error)

ApplyScrapeResults writes multiple scraper payloads in one transaction. Each target's sentinel is written after its metadata, and the whole batch rolls back if any target fails.

func (*MediaDB) BackgroundOperationDone added in v2.7.1 

func (db *MediaDB) BackgroundOperationDone()

BackgroundOperationDone decrements the background operations counter. This should be called when an operation started with TrackBackgroundOperation completes.

func (*MediaDB) BeginBrowseCacheRebuild added in v2.16.0 

func (db *MediaDB) BeginBrowseCacheRebuild()

BeginBrowseCacheRebuild marks a standalone browse-cache rebuild (outside a full RunBackgroundOptimization pass, e.g. the startup self-heal) as in progress, so IsOptimizing reflects it. Call EndBrowseCacheRebuild when the rebuild finishes.

func (*MediaDB) BeginRecovery added in v2.16.0 

func (db *MediaDB) BeginRecovery()

BeginRecovery prevents new background operations from registering, then waits for operations already registered to drain. EndRecovery must follow it.

func (*MediaDB) BeginTransaction 

func (db *MediaDB) BeginTransaction(batchEnabled bool) error

func (*MediaDB) BrowseCacheNeedsRebuild added in v2.16.0 

func (db *MediaDB) BrowseCacheNeedsRebuild(ctx context.Context) (bool, error)

BrowseCacheNeedsRebuild reports whether the browse cache is stale or absent and should be rebuilt. It returns false only when the cache is fresh (matches the current schema version). A stale-but-present cache is served (see the browse dispatch in sql_browse.go) but still needs a background rebuild to correct any drift, so it counts as needing a rebuild here.

func (*MediaDB) BrowseDirCount added in v2.15.1 

func (db *MediaDB) BrowseDirCount(
	ctx context.Context, opts database.BrowseDirCountOptions,
) (int, error)

BrowseDirCount returns the total number of immediate child directories under a path prefix.

func (*MediaDB) BrowseDirectories added in v2.10.0 

func (db *MediaDB) BrowseDirectories(
	ctx context.Context, opts database.BrowseDirectoriesOptions,
) ([]database.BrowseDirectoryResult, error)

BrowseDirectories returns distinct immediate subdirectory names under the given path prefix.

func (*MediaDB) BrowseFileCount added in v2.10.0 

func (db *MediaDB) BrowseFileCount(
	ctx context.Context, opts database.BrowseFileCountOptions,
) (int, error)

BrowseFileCount returns the total number of immediate child files under a path prefix.

func (*MediaDB) BrowseFiles added in v2.10.0 

func (db *MediaDB) BrowseFiles(
	ctx context.Context, opts *database.BrowseFilesOptions,
) ([]database.SearchResultWithCursor, error)

BrowseFiles returns indexed media files that are immediate children of the given path prefix. A malformed-page error here (the cover-flags join reads MediaTitleProperties, where scraped artwork lives) flags the database corrupt so the recovery flow rebuilds it.

func (*MediaDB) BrowseIndex added in v2.15.0 

func (db *MediaDB) BrowseIndex(
	ctx context.Context, opts database.BrowseIndexOptions,
) (database.BrowseIndexResult, error)

BrowseIndex returns the ordered first-character buckets for a browse scope, each with a count and the keyset needed to seek a media.browse page to the bucket's first item.

func (*MediaDB) BrowseRootCounts added in v2.10.0 

func (db *MediaDB) BrowseRootCounts(
	ctx context.Context, rootDirs []string,
) (map[string]*int, error)

BrowseRootCounts returns a map of root directory to count of indexed media under each root. A nil *int means the count is not yet available (cache not populated). A non-nil *int is the actual count (which may be 0).

func (*MediaDB) BrowseRouteCounts added in v2.12.0 

func (db *MediaDB) BrowseRouteCounts(
	ctx context.Context, opts database.BrowseRouteCountsOptions,
) (map[string]database.BrowseRouteCount, error)

BrowseRouteCounts returns populated route counts for system-scoped browse roots.

func (*MediaDB) BrowseSystemRootCandidates added in v2.12.0 

func (db *MediaDB) BrowseSystemRootCandidates(
	ctx context.Context, opts database.BrowseSystemRootCandidatesOptions,
) (database.BrowseSystemRootCandidates, bool, error)

BrowseSystemRootCandidates returns, in two batched queries, the immediate child subdirs of each root that hold media for the requested systems plus a per-root has-any-subtree-media flag. Used by the system-roots browse handler to avoid a per-root query fan-out.

func (*MediaDB) BrowseVirtualSchemes added in v2.10.0 

func (db *MediaDB) BrowseVirtualSchemes(
	ctx context.Context, opts database.BrowseVirtualSchemesOptions,
) ([]database.BrowseVirtualScheme, error)

BrowseVirtualSchemes returns distinct URI schemes present in indexed media.

func (*MediaDB) BumpIndexGeneration added in v2.12.0 

func (db *MediaDB) BumpIndexGeneration() (int64, error)

BumpIndexGeneration increments the index generation counter and returns the new value. Not transactional with cache file writes or status flips: crash recovery relies on (a) a generation mismatch causing persisted cache files from a previous run to be rejected at load time, and (b) IndexingStatus remaining "in_progress" until SetIndexingStatus is called, so an interrupted run is resumed (and re-bumped) on the next boot.

func (*MediaDB) CheckForDuplicateMediaTitles added in v2.7.0 

func (db *MediaDB) CheckForDuplicateMediaTitles() ([]string, error)

CheckForDuplicateMediaTitles returns any MediaTitle records that have duplicate (SystemDBID, Slug) combinations. Used in tests to validate data integrity after selective updates.

func (*MediaDB) CleanMediaOrphans added in v2.12.0 

func (db *MediaDB) CleanMediaOrphans(ctx context.Context) (int64, error)

CleanMediaOrphans deletes every Media row where IsMissing=1, together with the associated MediaTags and MediaProperties. MediaTitles that have no remaining Media rows are also removed, along with their MediaTitleTags and MediaTitleProperties. Tags that are no longer referenced by any join table are pruned. Free pages are left for SQLite to reuse instead of running VACUUM here, which would take an exclusive database lock.

The method returns the count of Media rows deleted. If no missing rows exist, it returns (0, nil) without touching the database.

CleanMediaOrphans refuses to run while media indexing is in progress (status running or pending), while a batch transaction is open, or while background optimisation is active, returning a sentinel error in each case.

func (*MediaDB) ClearCorruptMarker added in v2.15.0 

func (db *MediaDB) ClearCorruptMarker() error

ClearCorruptMarker removes the corrupt marker sidecar. No-op when absent.

func (*MediaDB) ClearScanStage added in v2.16.0 

func (db *MediaDB) ClearScanStage() error

ClearScanStage empties the scanner staging tables. Called at the start of a system's scan so rows left behind by a crashed run never leak into it.

func (*MediaDB) ClearScrapeRunMarkers added in v2.14.1 

func (db *MediaDB) ClearScrapeRunMarkers(ctx context.Context, scraperID, runID string) error

ClearScrapeRunMarkers removes per-run completion markers after a scraper operation reaches a terminal state.

func (*MediaDB) ClearScrapingOperation added in v2.14.0 

func (db *MediaDB) ClearScrapingOperation() error

func (*MediaDB) Close 

func (db *MediaDB) Close() error

func (*MediaDB) CommitTransaction 

func (db *MediaDB) CommitTransaction() error

func (*MediaDB) CommitTransactionWithOptions added in v2.14.1 

func (db *MediaDB) CommitTransactionWithOptions(options database.TransactionOptions) error

func (*MediaDB) ConsumeScrapeImageChanges added in v2.16.0 

func (db *MediaDB) ConsumeScrapeImageChanges() (systems []string, all bool)

ConsumeScrapeImageChanges returns and clears systems whose image properties materially changed in committed scrape writes. all is true when tracking could not resolve a safe targeted set and callers must invalidate everything.

func (*MediaDB) CreateIndexes added in v2.7.0 

func (*MediaDB) CreateIndexes() error

func (*MediaDB) CreateSecondaryIndexes added in v2.10.0 

func (db *MediaDB) CreateSecondaryIndexes() error

CreateSecondaryIndexes recreates dropped secondary indexes after bulk inserts and self-heals any required indexes missing from existing databases. Called synchronously at the end of indexing so the database is fully searchable when indexing completes.

func (*MediaDB) DeleteMediaProperty added in v2.12.0 

func (db *MediaDB) DeleteMediaProperty(ctx context.Context, mediaDBID, typeTagDBID int64) error

DeleteMediaProperty removes the property row for (mediaDBID, typeTagDBID) from MediaProperties. It is a no-op when no matching row exists.

func (*MediaDB) DeleteMediaTag added in v2.11.0 

func (db *MediaDB) DeleteMediaTag(mediaDBID, tagDBID int64) error

func (*MediaDB) DeleteMediaTitleProperty added in v2.12.0 

func (db *MediaDB) DeleteMediaTitleProperty(ctx context.Context, mediaTitleDBID, typeTagDBID int64) error

DeleteMediaTitleProperty removes the property row for (mediaTitleDBID, typeTagDBID) from MediaTitleProperties. It is a no-op when no matching row exists.

func (*MediaDB) DropSecondaryIndexes added in v2.10.0 

func (db *MediaDB) DropSecondaryIndexes() error

DropSecondaryIndexes drops all secondary indexes to speed up bulk inserts. Call before a full reindex, then call CreateSecondaryIndexes after.

func (*MediaDB) DropSlugSearchCacheForSystems added in v2.14.0 

func (db *MediaDB) DropSlugSearchCacheForSystems(systemIDs []string)

func (*MediaDB) EndBrowseCacheRebuild added in v2.16.0 

func (db *MediaDB) EndBrowseCacheRebuild()

EndBrowseCacheRebuild clears the flag set by BeginBrowseCacheRebuild.

func (*MediaDB) EndRecovery added in v2.16.0 

func (db *MediaDB) EndRecovery()

EndRecovery allows background operations to register after recovery completes.

func (*MediaDB) Exists 

func (db *MediaDB) Exists() bool

func (*MediaDB) FindMedia 

func (db *MediaDB) FindMedia(row database.Media) (database.Media, error)

FindMedia implements MediaDBI. Param is by value because the interface is.

func (*MediaDB) FindMediaBySystemAndPath added in v2.12.0 

func (db *MediaDB) FindMediaBySystemAndPath(
	ctx context.Context, systemDBID int64, path string,
) (*database.Media, error)

FindMediaBySystemAndPath returns the Media row for the given system and path, or nil, nil when not found.

func (*MediaDB) FindMediaBySystemAndPathFold added in v2.12.0 

func (db *MediaDB) FindMediaBySystemAndPathFold(
	ctx context.Context, systemDBID int64, path string,
) (*database.Media, error)

FindMediaBySystemAndPathFold returns the Media row for the given system and path using a case-insensitive path comparison, or nil, nil when not found. LOWER() in SQLite covers ASCII only, which is sufficient for filesystem paths.

func (*MediaDB) FindMediaBySystemAndPathSuffix added in v2.13.0 

func (db *MediaDB) FindMediaBySystemAndPathSuffix(
	ctx context.Context, systemDBID int64, filename string,
) ([]database.Media, error)

FindMediaBySystemAndPathSuffix returns all Media rows for the given system whose Path ends with "/" + filename. LIKE wildcards in the filename are escaped so a literal '%' or '_' in the name does not expand.

func (*MediaDB) FindMediaBySystemAndPaths added in v2.12.0 

func (db *MediaDB) FindMediaBySystemAndPaths(
	ctx context.Context, systemDBID int64, paths []string,
) (map[string]database.Media, error)

func (*MediaDB) FindMediaIDsByPaths added in v2.15.0 

func (db *MediaDB) FindMediaIDsByPaths(
	ctx context.Context, paths []string,
) ([]database.MediaPathID, error)

func (*MediaDB) FindMediaTag 

func (db *MediaDB) FindMediaTag(row database.MediaTag) (database.MediaTag, error)

func (*MediaDB) FindMediaTitle 

func (db *MediaDB) FindMediaTitle(row *database.MediaTitle) (database.MediaTitle, error)

func (*MediaDB) FindMediaTitleByDBID added in v2.12.0 

func (db *MediaDB) FindMediaTitleByDBID(ctx context.Context, dbid int64) (*database.MediaTitle, error)

FindMediaTitleByDBID returns the MediaTitle with the given DBID, or nil, nil when not found.

func (*MediaDB) FindMediaTitleBySystemAndSlug added in v2.13.0 

func (db *MediaDB) FindMediaTitleBySystemAndSlug(
	ctx context.Context, systemDBID int64, slug string,
) (*database.MediaTitle, error)

FindMediaTitleBySystemAndSlug returns the MediaTitle matching systemDBID and slug, or nil, nil when not found.

func (*MediaDB) FindMediaTitlesWithoutSentinel added in v2.12.0 

func (db *MediaDB) FindMediaTitlesWithoutSentinel(
	ctx context.Context, systemDBID int64, sentinelTag string,
) ([]database.MediaTitle, error)

FindMediaTitlesWithoutSentinel returns MediaTitle rows for the given system that have no Media row tagged with sentinelTag. sentinelTag must be in "type:value" format (e.g. "scraper.gamelist.xml:scraped").

func (*MediaDB) FindOrInsertMedia 

func (db *MediaDB) FindOrInsertMedia(row database.Media) (database.Media, error)

FindOrInsertMedia implements MediaDBI. Param is by value because the interface is.

func (*MediaDB) FindOrInsertMediaTag 

func (db *MediaDB) FindOrInsertMediaTag(row database.MediaTag) (database.MediaTag, error)

func (*MediaDB) FindOrInsertMediaTitle 

func (db *MediaDB) FindOrInsertMediaTitle(row *database.MediaTitle) (database.MediaTitle, error)

func (*MediaDB) FindOrInsertSystem 

func (db *MediaDB) FindOrInsertSystem(row database.System) (database.System, error)

func (*MediaDB) FindOrInsertTag 

func (db *MediaDB) FindOrInsertTag(row database.Tag) (database.Tag, error)

func (*MediaDB) FindOrInsertTagType 

func (db *MediaDB) FindOrInsertTagType(row database.TagType) (database.TagType, error)

func (*MediaDB) FindSingleContainerLaunchMedia added in v2.14.0 

func (db *MediaDB) FindSingleContainerLaunchMedia(
	ctx context.Context, systemDBID int64, containerPath string,
) (*database.Media, error)

func (*MediaDB) FindSystem 

func (db *MediaDB) FindSystem(row database.System) (database.System, error)

Find* lookups below always use db.sql.Load() rather than db.conn(): callers are external readers (API handlers, zapscript launch, scrapers) that can run concurrently with an active indexing transaction, and borrowing the indexer's own in-flight *sql.Tx from another goroutine risks "transaction has already been committed or rolled back" if it commits mid-read.

func (*MediaDB) FindSystemBySystemID added in v2.7.0 

func (db *MediaDB) FindSystemBySystemID(systemID string) (database.System, error)

func (*MediaDB) FindTag 

func (db *MediaDB) FindTag(row database.Tag) (database.Tag, error)

func (*MediaDB) FindTagType 

func (db *MediaDB) FindTagType(row database.TagType) (database.TagType, error)

func (*MediaDB) FlushBatchInserters added in v2.15.0 

func (db *MediaDB) FlushBatchInserters() error

FlushBatchInserters flushes all pending batch-insert buffers into the open transaction without committing, so freshly inserted rows become visible to reads on the same transaction (e.g. RecomputeSystemDisambiguation). Unlike closeAllBatchInserters it leaves the inserters open for continued use, which lets one transaction span multiple systems. No-op when no transaction or no batch inserters are active. Each inserter's Flush already flushes its FK dependencies first, so the iteration order only needs to be deterministic.

func (*MediaDB) GetAllSystems added in v2.7.0 

func (db *MediaDB) GetAllSystems() ([]database.System, error)

func (*MediaDB) GetAllUsedTags added in v2.7.0 

func (db *MediaDB) GetAllUsedTags(ctx context.Context) ([]database.TagInfo, error)

GetAllUsedTags returns all tags that are actually in use (have media associated) This is optimized for the "all systems" case and avoids expensive system filtering

func (*MediaDB) GetCachedSlugResolution added in v2.7.0 

func (db *MediaDB) GetCachedSlugResolution(
	ctx context.Context, systemID, slug string, tagFilters []zapscript.TagFilter,
) (mediaDBID int64, strategy string, found bool)

GetCachedSlugResolution retrieves a cached slug resolution result. Returns the MediaDBID, strategy name, and true if found; otherwise returns 0, "", false.

func (*MediaDB) GetCachedStats added in v2.7.0 

func (db *MediaDB) GetCachedStats(ctx context.Context, query *database.MediaQuery) (MediaStats, bool)

GetCachedStats returns cached statistics for the given media query, if available. Returns the stats and true if found, or empty stats and false if not cached.

func (*MediaDB) GetDBPath 

func (db *MediaDB) GetDBPath() string

func (*MediaDB) GetExistingMediaUserData added in v2.15.0 

func (db *MediaDB) GetExistingMediaUserData(ctx context.Context) ([]database.MediaUserData, error)

GetExistingMediaUserData reads user-authored data already materialized in media.db — favourites (user:favorite MediaTags) and launcher overrides (launcher-override MediaProperties) — and returns it as MediaUserData rows keyed by (SystemID, Path). It exists so a one-time startup backfill can seed UserDB from versions that wrote this data only to media.db. A row carries whichever of IsFavorite / LauncherOverride applies; both may be set.

func (*MediaDB) GetIndexResumeAttempts added in v2.16.0 

func (db *MediaDB) GetIndexResumeAttempts() (int, error)

GetIndexResumeAttempts returns the number of consecutive automatic resume attempts that found no durable indexing progress since the previous resume. It resets to zero once indexing reaches a clean state or the resume checkpoint moves.

func (*MediaDB) GetIndexResumeCheckpoint added in v2.16.0 

func (db *MediaDB) GetIndexResumeCheckpoint() (string, error)

GetIndexResumeCheckpoint returns the durable indexing checkpoint observed at the previous auto-resume. A changed checkpoint proves the index made progress.

func (*MediaDB) GetIndexingPlanSystems added in v2.16.0 

func (db *MediaDB) GetIndexingPlanSystems() ([]string, error)

func (*MediaDB) GetIndexingStatus added in v2.7.0 

func (db *MediaDB) GetIndexingStatus() (string, error)

func (*MediaDB) GetIndexingSystems added in v2.7.0 

func (db *MediaDB) GetIndexingSystems() ([]string, error)

func (*MediaDB) GetLastGenerated 

func (db *MediaDB) GetLastGenerated() (time.Time, error)

func (*MediaDB) GetLastIndexedSystem added in v2.7.0 

func (db *MediaDB) GetLastIndexedSystem() (string, error)

func (*MediaDB) GetLaunchCommandForMedia added in v2.7.0 

func (db *MediaDB) GetLaunchCommandForMedia(ctx context.Context, systemID, path string) (string, error)

GetLaunchCommandForMedia generates a title-based launch command for the given media.

func (*MediaDB) GetMediaBlob added in v2.12.0 

func (db *MediaDB) GetMediaBlob(ctx context.Context, blobDBID int64) (*database.MediaBlob, error)

GetMediaBlob returns the MediaBlob row for the given DBID, or nil, nil when not found.

func (*MediaDB) GetMediaBlobDataCapped added in v2.13.0 

func (db *MediaDB) GetMediaBlobDataCapped(
	ctx context.Context, blobDBID int64, maxBytes int64,
) (data []byte, contentType string, err error)

GetMediaBlobDataCapped returns blob data only when it is not larger than maxBytes.

func (*MediaDB) GetMediaByDBID added in v2.7.0 

func (db *MediaDB) GetMediaByDBID(ctx context.Context, mediaDBID int64) (database.SearchResultWithCursor, error)

GetMediaByDBID retrieves a single SearchResultWithCursor by Media DBID. This is used to reconstruct the full result from a cached Media DBID.

func (*MediaDB) GetMediaBySystemID added in v2.9.1 

func (db *MediaDB) GetMediaBySystemID(systemID string) ([]database.MediaWithFullPath, error)

GetMediaBySystemID retrieves all media for a specific system. This is used for lazy loading during resume to avoid loading ALL media upfront. TitleSlug is NOT populated: no caller uses it, and fetching it would add a MediaTitles probe per media row to the scanner's hottest state-load query. Non-cancellable context: see GetTitlesBySystemID.

func (*MediaDB) GetMediaProperties added in v2.12.0 

func (db *MediaDB) GetMediaProperties(ctx context.Context, mediaDBID int64) ([]database.MediaProperty, error)

GetMediaProperties returns all MediaProperties rows for the given Media record. TypeTag is populated as "type:value" from the joined Tags/TagTypes rows.

func (*MediaDB) GetMediaPropertiesByMediaDBIDs added in v2.12.0 

func (db *MediaDB) GetMediaPropertiesByMediaDBIDs(
	ctx context.Context, mediaDBIDs []int64,
) (map[int64][]database.MediaProperty, error)

GetMediaPropertiesByMediaDBIDs returns properties grouped by Media DBID. Binary blobs are capped at MaxMediaPropertyBinaryBytes.

func (*MediaDB) GetMediaPropertyMetadata added in v2.13.0 

func (db *MediaDB) GetMediaPropertyMetadata(ctx context.Context, mediaDBID int64) ([]database.MediaProperty, error)

func (*MediaDB) GetMediaPropertyMetadataByMediaDBIDs added in v2.13.0 

func (db *MediaDB) GetMediaPropertyMetadataByMediaDBIDs(
	ctx context.Context, mediaDBIDs []int64,
) (map[int64][]database.MediaProperty, error)

func (*MediaDB) GetMediaTagsByMediaDBID added in v2.12.0 

func (db *MediaDB) GetMediaTagsByMediaDBID(ctx context.Context, mediaDBID int64) ([]database.TagInfo, error)

GetMediaTagsByMediaDBID returns the file-level tags (MediaTags) for a single Media row, ordered by type then tag value.

func (*MediaDB) GetMediaTagsByMediaDBIDs added in v2.12.0 

func (db *MediaDB) GetMediaTagsByMediaDBIDs(
	ctx context.Context, mediaDBIDs []int64,
) (map[int64][]database.TagInfo, error)

func (*MediaDB) GetMediaTitleProperties added in v2.12.0 

func (db *MediaDB) GetMediaTitleProperties(
	ctx context.Context, mediaTitleDBID int64,
) ([]database.MediaProperty, error)

GetMediaTitleProperties returns all MediaTitleProperties rows for the given title. TypeTag is populated as "type:value" from the joined Tags/TagTypes rows.

func (*MediaDB) GetMediaTitlePropertiesByMediaTitleDBIDs added in v2.12.0 

func (db *MediaDB) GetMediaTitlePropertiesByMediaTitleDBIDs(
	ctx context.Context, mediaTitleDBIDs []int64,
) (map[int64][]database.MediaProperty, error)

GetMediaTitlePropertiesByMediaTitleDBIDs returns properties grouped by MediaTitle DBID. Binary blobs are capped at MaxMediaPropertyBinaryBytes.

func (*MediaDB) GetMediaTitlePropertyMetadata added in v2.13.0 

func (db *MediaDB) GetMediaTitlePropertyMetadata(
	ctx context.Context, mediaTitleDBID int64,
) ([]database.MediaProperty, error)

func (*MediaDB) GetMediaTitlePropertyMetadataByMediaTitleDBIDs added in v2.13.0 

func (db *MediaDB) GetMediaTitlePropertyMetadataByMediaTitleDBIDs(
	ctx context.Context, mediaTitleDBIDs []int64,
) (map[int64][]database.MediaProperty, error)

func (*MediaDB) GetMediaTitleTagsByMediaTitleDBID added in v2.12.0 

func (db *MediaDB) GetMediaTitleTagsByMediaTitleDBID(
	ctx context.Context, mediaTitleDBID int64,
) ([]database.TagInfo, error)

GetMediaTitleTagsByMediaTitleDBID returns the title-level tags (MediaTitleTags) for a single MediaTitle row, ordered by type then tag value.

func (*MediaDB) GetMediaTitleTagsByMediaTitleDBIDs added in v2.12.0 

func (db *MediaDB) GetMediaTitleTagsByMediaTitleDBIDs(
	ctx context.Context, mediaTitleDBIDs []int64,
) (map[int64][]database.TagInfo, error)

func (*MediaDB) GetMediaWithTitleAndSystem added in v2.12.0 

func (db *MediaDB) GetMediaWithTitleAndSystem(ctx context.Context, mediaDBID int64) (*database.MediaFullRow, error)

GetMediaWithTitleAndSystem fetches a Media record together with its parent MediaTitle and System via a single JOIN query. Returns nil, nil when the mediaDBID does not exist. IsMissing is NOT filtered.

func (*MediaDB) GetMediaWithTitleAndSystemByIDs added in v2.12.0 

func (db *MediaDB) GetMediaWithTitleAndSystemByIDs(
	ctx context.Context, mediaDBIDs []int64,
) (map[int64]database.MediaFullRow, error)

func (*MediaDB) GetMissingMediaCount added in v2.16.0 

func (db *MediaDB) GetMissingMediaCount() (int, error)

GetMissingMediaCount returns the number of media entries flagged missing — what a media.clean.orphans call would delete.

func (*MediaDB) GetOptimizationStatus added in v2.7.0 

func (db *MediaDB) GetOptimizationStatus() (string, error)

func (*MediaDB) GetOptimizationStep added in v2.7.0 

func (db *MediaDB) GetOptimizationStep() (string, error)

func (*MediaDB) GetScrapeRunMediaIDs added in v2.14.1 

func (db *MediaDB) GetScrapeRunMediaIDs(
	ctx context.Context, scraperID, runID string, systemDBID int64,
) (map[int64]struct{}, error)

GetScrapeRunMediaIDs returns media DBIDs in systemDBID completed during a specific persisted scraper run.

func (*MediaDB) GetScrapedMediaCount added in v2.12.0 

func (db *MediaDB) GetScrapedMediaCount(ctx context.Context, scraperID string) (int, error)

GetScrapedMediaCount returns the number of distinct media rows marked as successfully scraped by the given scraper.

func (*MediaDB) GetScrapedMediaIDs added in v2.12.0 

func (db *MediaDB) GetScrapedMediaIDs(
	ctx context.Context, scraperID string, systemDBID int64,
) (map[int64]struct{}, error)

GetScrapedMediaIDs returns media DBIDs in systemDBID already marked as scraped by scraperID.

func (*MediaDB) GetScrapingOperation added in v2.14.0 

func (db *MediaDB) GetScrapingOperation() (database.ScrapingOperation, bool, error)

func (*MediaDB) GetScrapingStatus added in v2.14.0 

func (db *MediaDB) GetScrapingStatus() (string, error)

func (*MediaDB) GetSystemTagsCached added in v2.7.0 

func (db *MediaDB) GetSystemTagsCached(ctx context.Context, systems []systemdefs.System) ([]database.TagInfo, error)

GetSystemTagsCached retrieves tags for specific systems using the cache table Falls back to the optimized subquery approach if cache is empty

func (*MediaDB) GetTags added in v2.7.0 

func (db *MediaDB) GetTags(ctx context.Context, systems []systemdefs.System) ([]database.TagInfo, error)

func (*MediaDB) GetTitlesBySystemID added in v2.9.1 

func (db *MediaDB) GetTitlesBySystemID(systemID string) ([]database.TitleWithSystem, error)

GetTitlesBySystemID retrieves all media titles for a specific system with their associated system information. This is used for lazy loading during resume to avoid loading ALL titles upfront.

Uses a non-cancellable context: with a cancellable context, mattn/go-sqlite3 spawns a goroutine + channel per rows.Next() call, which is significant overhead on the scanner's bulk per-system reads. The scanner checks for cancellation between queries instead.

func (*MediaDB) GetTitlesWithPreFilter added in v2.7.0 

func (db *MediaDB) GetTitlesWithPreFilter(
	ctx context.Context, systemID string, minLength, maxLength, minWordCount, maxWordCount int,
) ([]database.MediaTitle, error)

GetTitlesWithPreFilter retrieves media titles filtered by slug length and word count ranges. This dramatically reduces the candidate set for fuzzy matching by using indexed pre-filter columns. Uses the composite index idx_media_prefilter (SlugLength, SlugWordCount) for efficient range queries.

func (*MediaDB) GetTotalMediaCount added in v2.7.0 

func (db *MediaDB) GetTotalMediaCount() (int, error)

GetTotalMediaCount returns the total number of media entries in the database.

func (*MediaDB) GetTotalScrapedMediaCount added in v2.12.0 

func (db *MediaDB) GetTotalScrapedMediaCount(ctx context.Context) (int, error)

GetTotalScrapedMediaCount returns the number of distinct media rows marked as successfully scraped by any scraper sentinel tag.

func (*MediaDB) GetZapScriptTagsBySystemAndPath added in v2.10.0 

func (db *MediaDB) GetZapScriptTagsBySystemAndPath(
	ctx context.Context, systemID, path string,
) ([]database.TagInfo, error)

GetZapScriptTagsBySystemAndPath retrieves disambiguating tags for a media item. A tag is disambiguating when sibling media entries (same title) have different values for that tag type (e.g., 2-player vs 4-player variants of the same game). Returns only the target media's tags for tag types listed in the title's precomputed MediaTitles.DisambiguationTypes (see RecomputeTitleDisambiguation). Returns empty slice if no disambiguating tags exist or media not found.

func (*MediaDB) HasAnyMedia added in v2.16.0 

func (db *MediaDB) HasAnyMedia() (bool, error)

HasAnyMedia reports whether at least one media row exists. Cheap (EXISTS with LIMIT semantics) so it is safe to call while an index is running; used to report truthful database existence to clients mid-index.

func (*MediaDB) HasBackgroundOperations added in v2.16.0 

func (db *MediaDB) HasBackgroundOperations() bool

HasBackgroundOperations reports whether this process currently owns media database background work. Persisted running statuses cannot answer this after a crash.

func (*MediaDB) HasMediaPropertyForPath added in v2.16.0 

func (db *MediaDB) HasMediaPropertyForPath(ctx context.Context, systemID, path, property string) (bool, error)

HasMediaPropertyForPath reports whether systemID/path already has property.

func (*MediaDB) IncrementIndexResumeAttempts added in v2.16.0 

func (db *MediaDB) IncrementIndexResumeAttempts() (int, error)

IncrementIndexResumeAttempts bumps the no-progress resume-attempt counter and returns the new value. It bounds repeated resumes only when the durable indexing checkpoint is not moving.

func (*MediaDB) IndexGeneration added in v2.12.0 

func (db *MediaDB) IndexGeneration() (int64, error)

IndexGeneration returns the monotonic counter that's bumped on every successful indexing run. Returns 0 if no indexing has completed yet.

func (*MediaDB) IndexedSystems 

func (db *MediaDB) IndexedSystems() ([]string, error)

IndexedSystems returns all systems indexed in the media database.

func (*MediaDB) InsertMedia 

func (db *MediaDB) InsertMedia(row database.Media) (database.Media, error)

InsertMedia implements MediaDBI. Param is by value because the interface is.

func (*MediaDB) InsertMediaTag 

func (db *MediaDB) InsertMediaTag(row database.MediaTag) (database.MediaTag, error)

func (*MediaDB) InsertMediaTitle 

func (db *MediaDB) InsertMediaTitle(row *database.MediaTitle) (database.MediaTitle, error)

func (*MediaDB) InsertSystem 

func (db *MediaDB) InsertSystem(row database.System) (database.System, error)

func (*MediaDB) InsertTag 

func (db *MediaDB) InsertTag(row database.Tag) (database.Tag, error)

func (*MediaDB) InsertTagType 

func (db *MediaDB) InsertTagType(row database.TagType) (database.TagType, error)

InsertTagType inserts a new TagType into the database.

func (*MediaDB) IntegrityReport added in v2.15.0 

func (db *MediaDB) IntegrityReport() []string

IntegrityReport runs PRAGMA integrity_check and returns the result rows. It captures a corruption fingerprint in the logs — which are uploadable via the support bundle — when the database file itself cannot be retrieved. A healthy database returns a single "ok" row.

func (*MediaDB) InvalidateCountCache added in v2.7.0 

func (db *MediaDB) InvalidateCountCache() error

InvalidateCountCache clears all cached media counts. This should be called after any operation that changes the media database content.

func (*MediaDB) InvalidateSlugCache added in v2.7.0 

func (db *MediaDB) InvalidateSlugCache(ctx context.Context) error

InvalidateSlugCache clears all cached slug resolutions. This should be called after any operation that changes the media database content.

func (*MediaDB) InvalidateSlugCacheForSystems added in v2.7.0 

func (db *MediaDB) InvalidateSlugCacheForSystems(ctx context.Context, systemIDs []string) error

InvalidateSlugCacheForSystems clears cached slug resolutions for specific systems. This is used during selective system reindexing to avoid invalidating the entire cache.

func (*MediaDB) InvalidateSystemTagsCache added in v2.7.0 

func (db *MediaDB) InvalidateSystemTagsCache(ctx context.Context, systems []systemdefs.System) error

InvalidateSystemTagsCache removes cache entries for specific systems Useful for incremental cache updates when only certain systems change If no systems are provided, this is a no-op and returns success.

func (*MediaDB) IsMarkedCorrupt added in v2.15.0 

func (db *MediaDB) IsMarkedCorrupt() bool

IsMarkedCorrupt reports whether the corrupt marker sidecar exists.

func (*MediaDB) IsOptimizing added in v2.16.0 

func (db *MediaDB) IsOptimizing() bool

IsOptimizing reports whether the database is currently undergoing any background optimization-class operation: a full RunBackgroundOptimization pass, or a standalone browse-cache rebuild (see BeginBrowseCacheRebuild). It is the single signal callers should query to show an "optimizing" indicator — they should not need to know which specific operation is running.

This is intentionally process-local, not the persisted OptimizationStatus: a browse-cache rebuild can run for minutes independently of (and possibly overlapping) a full optimization, and writing the persisted status from both would race two operations over who owns "running". Being process-local also means a crash simply drops the flag rather than wedging a persisted status.

func (*MediaDB) LoadCachedSlugSearchCache added in v2.12.0 

func (db *MediaDB) LoadCachedSlugSearchCache() (bool, error)

LoadCachedSlugSearchCache reads the persisted slug search cache from disk and installs it into the atomic pointer. Verifies magic, version, and index generation against the live DB before accepting the file. Returns (false, nil) when the file is missing, stale, or only covers selected systems, so the caller can build a complete cache; (true, nil) when a complete cache was loaded; (false, err) on unrecoverable I/O or decode errors. A valid selective cache is still installed so its covered systems remain searchable while the complete cache is built.

func (*MediaDB) LoadCachedTagCache added in v2.12.0 

func (db *MediaDB) LoadCachedTagCache() (bool, error)

LoadCachedTagCache reads the persisted tag cache from disk and installs it into the atomic pointer. Verifies magic, version, and index generation against the live DB before accepting the file. Returns (false, nil) when the file is missing or stale, so the caller can fall back to a SQL rebuild; (true, nil) when a usable cache was loaded; (false, err) on unrecoverable I/O or decode errors.

func (*MediaDB) MarkCorrupt added in v2.15.0 

func (db *MediaDB) MarkCorrupt(reason string)

MarkCorrupt writes a sidecar marker file next to the database recording that corruption was detected. The marker is the authoritative, DB-independent signal the recovery path keys on: unlike IndexingStatusCorrupt it does not require writing to the (possibly unwritable) database. Best-effort — failures are logged, not returned.

func (*MediaDB) MediaHasTag added in v2.12.0 

func (db *MediaDB) MediaHasTag(ctx context.Context, mediaDBID int64, tagValue string) (bool, error)

MediaHasTag returns true when the given Media record has a tag matching the "type:value" string tagValue. The string is split on the first colon: everything before the colon is matched against TagTypes.Type, everything after is matched against Tags.Tag (padded and unpadded forms are both checked).

func (*MediaDB) MigrateUp 

func (db *MediaDB) MigrateUp() error

func (*MediaDB) NoteCorruption added in v2.15.0 

func (db *MediaDB) NoteCorruption(err error) bool

NoteCorruption flags the database corrupt when err indicates SQLite corruption, so any path that first touches a malformed page (a read, a scraper write, a checkpoint) routes into the recovery flow instead of silently failing. It only writes the marker once — the expensive integrity report is logged later by the recovery orchestration, not on every failing query. Returns true when err was a corruption error.

func (*MediaDB) Open 

func (db *MediaDB) Open() error

func (*MediaDB) PersistSlugSearchCache added in v2.12.0 

func (db *MediaDB) PersistSlugSearchCache() error

PersistSlugSearchCache writes the current in-memory slug search cache to disk via temp file + rename. Atomic against concurrent readers but not durable against a hard power-off — see writePersistedCacheFile for the contract.

func (*MediaDB) PersistTagCache added in v2.12.0 

func (db *MediaDB) PersistTagCache() error

PersistTagCache writes the current in-memory tag cache to disk via temp file + rename. Atomic against concurrent readers but not durable against a hard power-off — see writePersistedCacheFile for the contract.

func (*MediaDB) PopulateBrowseCache added in v2.10.0 

func (db *MediaDB) PopulateBrowseCache(ctx context.Context) error

PopulateBrowseCache rebuilds the BrowseCache table from the current Media data.

Uses a non-cancellable context: the rebuild reads every non-missing Media row (~1M on large libraries), and with a cancellable context mattn/go-sqlite3 spawns a goroutine + channel per rows.Next(), which turned this scan into a 7.6-minute operation on device. Cancellation before the DB work is still honoured by the caller's pauser.Wait; see checkAndHealBrowseCache.

func (*MediaDB) PopulateBrowseCacheForSystems added in v2.16.0 

func (db *MediaDB) PopulateBrowseCacheForSystems(ctx context.Context, systemIDs []string) error

PopulateBrowseCacheForSystems incrementally refreshes browse cache rows for the given systems from committed media. Called after each system's commit during indexing so browse serves fresh results mid-scan without waiting for the end-of-run full rebuild. Systems without a DB row yet are skipped. Uses a non-cancellable context for the same driver reason as PopulateBrowseCache.

func (*MediaDB) PopulateSystemTagsCache added in v2.7.0 

func (db *MediaDB) PopulateSystemTagsCache(ctx context.Context) error

PopulateSystemTagsCache rebuilds the cache table for fast tag lookups by system This should be called after media indexing completes

func (*MediaDB) PopulateSystemTagsCacheForSystems added in v2.7.0 

func (db *MediaDB) PopulateSystemTagsCacheForSystems(ctx context.Context, systems []systemdefs.System) error

PopulateSystemTagsCacheForSystems rebuilds cache for specific systems only Used for incremental cache updates after individual system changes

func (*MediaDB) PruneOrphanedBlobs added in v2.12.0 

func (db *MediaDB) PruneOrphanedBlobs(ctx context.Context) (int64, error)

PruneOrphanedBlobs deletes MediaBlobs rows not referenced by either MediaTitleProperties or MediaProperties. Returns the count of rows deleted.

func (*MediaDB) QuickCheck added in v2.15.0 

func (db *MediaDB) QuickCheck() (bool, error)

QuickCheck runs PRAGMA quick_check(1) and reports whether the database passes. quick_check is a bounded integrity scan — it skips integrity_check's expensive index-vs-table cross-checks and the argument stops it after the first error — so it is cheap enough to confirm suspected corruption before acting on it. Returns ok=true only when SQLite reports the single sentinel row "ok".

func (*MediaDB) RandomGame 

func (db *MediaDB) RandomGame(ctx context.Context, systems []systemdefs.System) (database.SearchResult, error)

RandomGame returns a random game from specified systems.

func (*MediaDB) RandomGameWithQuery added in v2.7.0 

func (db *MediaDB) RandomGameWithQuery(ctx context.Context, query *database.MediaQuery) (database.SearchResult, error)

RandomGameWithQuery returns a random game matching the specified MediaQuery.

func (*MediaDB) RebuildSlugSearchCache added in v2.10.0 

func (db *MediaDB) RebuildSlugSearchCache() error

RebuildSlugSearchCache builds or rebuilds the in-memory slug search cache.

func (*MediaDB) RebuildTagCache added in v2.10.0 

func (db *MediaDB) RebuildTagCache() error

RebuildTagCache builds or rebuilds the in-memory tag cache from the SystemTagsCache SQL table. Should be called after media indexing completes.

func (*MediaDB) RecomputeSystemDisambiguation added in v2.15.0 

func (db *MediaDB) RecomputeSystemDisambiguation(ctx context.Context, systemDBIDs []int64) error

RecomputeSystemDisambiguation recomputes the stored disambiguating tag types for every MediaTitle belonging to the given system DBIDs. Called at index time once a system is fully written so all of its titles are refreshed together.

func (*MediaDB) RecomputeTitleDisambiguation added in v2.15.0 

func (db *MediaDB) RecomputeTitleDisambiguation(ctx context.Context, titleDBIDs []int64) error

RecomputeTitleDisambiguation recomputes the stored disambiguating tag types for the given MediaTitle DBIDs. Callers invoke this after any write that can change a title's set of media or their tags (indexing, scraping, manual tag edits) so reads can rely on the stored, title-global value.

func (*MediaDB) ReconcileStagedSystem added in v2.16.0 

func (db *MediaDB) ReconcileStagedSystem(
	ctx context.Context, systemID string, opts database.ScanReconcileOpts,
) (database.ScanReconcileStats, error)

ReconcileStagedSystem flushes the staging inserters and folds the staged scan of systemID into the media tables with set-based SQL, including the touched -title disambiguation recompute. Must run inside the scanner's open batch transaction; see sqlReconcileStagedSystem for the statement sequence.

func (*MediaDB) Recreate added in v2.16.0 

func (db *MediaDB) Recreate(keepBackup bool) error

Recreate discards the database file and reopens a fresh one. The connection is closed; the main file is either preserved as a <db>.corrupt.bak forensic copy (keepBackup — development builds only) or deleted; the -wal/-shm sidecars are removed (a stale WAL would re-corrupt the new file); and Open() allocates a fresh schema. Before any corrupt marker is cleared, the fresh database is marked pending for reindex and stale search caches are removed. This durable handoff lets startup resume if the process exits before the caller starts indexing. Callers: corruption recovery and the user-requested fresh-start rebuild (media.index with rebuild:true).

func (*MediaDB) RefreshSlugSearchCacheForSystems added in v2.11.0 

func (db *MediaDB) RefreshSlugSearchCacheForSystems(ctx context.Context, systemIDs []string) error

func (*MediaDB) ResetIndexResumeAttempts added in v2.16.0 

func (db *MediaDB) ResetIndexResumeAttempts() error

ResetIndexResumeAttempts clears the no-progress resume-attempt counter and checkpoint, giving a future interrupted index a fresh stall budget.

func (*MediaDB) ResolveSingletonContainerAliases added in v2.14.1 

func (db *MediaDB) ResolveSingletonContainerAliases(
	ctx context.Context,
	systemDBID int64,
	dirCandidates []database.SingletonAliasCandidate,
) ([]database.SingletonContainerAlias, error)

ResolveSingletonContainerAliases implements MediaDBI. It fetches the direct media rows of every candidate child directory in a single ParentDir IN query and returns one SingletonContainerAlias per candidate that collapses to a single logical launch target. Candidates whose recursive FileCount exceeds their direct row count contain nested subdirectories and are omitted, as are ambiguous file sets. Tags and ZapScriptTags are populated via two batch queries plus in-memory disambiguation — the same approach used by the search path.

func (*MediaDB) RollbackTransaction 

func (db *MediaDB) RollbackTransaction() error

RollbackTransaction rolls back the current transaction and cleans up resources

func (*MediaDB) RunBackgroundOptimization added in v2.7.0 

func (db *MediaDB) RunBackgroundOptimization(statusCallback func(optimizing bool), pauser *syncutil.Pauser)

RunBackgroundOptimization performs database optimization operations in the background. This includes creating indexes, running ANALYZE, and vacuuming the database. It can be safely interrupted and resumed later.

func (*MediaDB) SearchMediaByProperty added in v2.16.0 

func (db *MediaDB) SearchMediaByProperty(
	ctx context.Context, systemID, property, value string,
) ([]database.SearchResult, error)

SearchMediaByProperty finds media whose stored property value matches value, optionally scoped to systemID. Empty systemID matches any system.

func (*MediaDB) SearchMediaBySecondarySlug added in v2.7.0 

func (db *MediaDB) SearchMediaBySecondarySlug(
	ctx context.Context, systemID string, secondarySlug string, tagFilters []zapscript.TagFilter,
) ([]database.SearchResultWithCursor, error)

func (*MediaDB) SearchMediaBySlug added in v2.7.0 

func (db *MediaDB) SearchMediaBySlug(
	ctx context.Context, systemID string, slug string, tagFilters []zapscript.TagFilter,
) ([]database.SearchResultWithCursor, error)

func (*MediaDB) SearchMediaBySlugIn added in v2.7.0 

func (db *MediaDB) SearchMediaBySlugIn(
	ctx context.Context, systemID string, slugList []string, tagFilters []zapscript.TagFilter,
) ([]database.SearchResultWithCursor, error)

SearchMediaBySlugIn searches for media items matching any of the provided slugs using an IN clause. This is optimized for searching multiple slug candidates in a single query.

func (*MediaDB) SearchMediaBySlugPrefix added in v2.7.0 

func (db *MediaDB) SearchMediaBySlugPrefix(
	ctx context.Context, systemID string, slugPrefix string, tagFilters []zapscript.TagFilter,
) ([]database.SearchResultWithCursor, error)

func (*MediaDB) SearchMediaPathExact 

func (db *MediaDB) SearchMediaPathExact(
	ctx context.Context, systems []systemdefs.System, query string,
) ([]database.SearchResult, error)

SearchMediaPathExact returns indexed names matching an exact query (case-insensitive).

func (*MediaDB) SearchMediaPathGlob 

func (db *MediaDB) SearchMediaPathGlob(systems []systemdefs.System, query string) ([]database.SearchResult, error)

func (*MediaDB) SearchMediaWithFilters added in v2.7.0 

func (db *MediaDB) SearchMediaWithFilters(
	ctx context.Context,
	filters *database.SearchFilters,
) ([]database.SearchResultWithCursor, error)

func (*MediaDB) SeedCanonicalTagDefinitions added in v2.16.0 

func (db *MediaDB) SeedCanonicalTagDefinitions(ctx context.Context) error

SeedCanonicalTagDefinitions ensures every canonical tag type and value exists, using set-based anti-joined inserts.

func (*MediaDB) SetCachedSlugResolution added in v2.7.0 

func (db *MediaDB) SetCachedSlugResolution(
	ctx context.Context, systemID, slug string, tagFilters []zapscript.TagFilter, mediaDBID int64, strategy string,
) error

SetCachedSlugResolution stores a successful slug resolution in the cache.

func (*MediaDB) SetCachedStats added in v2.7.0 

func (db *MediaDB) SetCachedStats(ctx context.Context, query *database.MediaQuery, stats MediaStats) error

SetCachedStats stores statistics for the given media query in the cache.

func (*MediaDB) SetDBPathForTesting added in v2.7.0 

func (db *MediaDB) SetDBPathForTesting(dbPath string)

SetDBPathForTesting explicitly sets the DB path so test memory DBs can reload.

func (*MediaDB) SetIndexResumeCheckpoint added in v2.16.0 

func (db *MediaDB) SetIndexResumeCheckpoint(checkpoint string) error

SetIndexResumeCheckpoint stores the durable indexing checkpoint observed at auto-resume time so the next boot can detect whether progress moved.

func (*MediaDB) SetIndexingCacheSize added in v2.10.0 

func (db *MediaDB) SetIndexingCacheSize(enable bool)

SetIndexingCacheSize temporarily increases SQLite cache_size for bulk indexing. Call with enable=true before indexing starts, and enable=false after it completes. When enabled, sets 32MB cache (vs default 8MB) to reduce page eviction during heavy insert workloads with non-sequential index keys.

Also switches temp_store to MEMORY for the duration: the GROUP BY temp B-trees built by the post-indexing cache population are only a few MB, and the default temp_store=FILE writes them to slow storage (SD card) on embedded devices.

Both pragmas are per-connection, and the pool exec below only reaches whichever connection happens to be free — not necessarily the one the bulk writer's transaction will pin. BeginTransaction therefore re-applies the current settings on its own connection, which is where the boost matters.

func (*MediaDB) SetIndexingConnBoost added in v2.16.0 

func (db *MediaDB) SetIndexingConnBoost(active bool)

SetIndexingConnBoost widens the connection pool while an index runs (the writer holds a connection near-continuously, which would otherwise leave a single connection for all foreground reads) and restores the steady-state size afterwards. Safe to call around a Recreate: it always acts on the currently-loaded pool.

func (*MediaDB) SetIndexingPlanSystems added in v2.16.0 

func (db *MediaDB) SetIndexingPlanSystems(systemIDs []string) error

func (*MediaDB) SetIndexingStatus added in v2.7.0 

func (db *MediaDB) SetIndexingStatus(status string) error

func (*MediaDB) SetIndexingSystems added in v2.7.0 

func (db *MediaDB) SetIndexingSystems(systemIDs []string) error

func (*MediaDB) SetLastIndexedSystem added in v2.7.0 

func (db *MediaDB) SetLastIndexedSystem(systemID string) error

func (*MediaDB) SetOptimizationStatus added in v2.7.0 

func (db *MediaDB) SetOptimizationStatus(status string) error

func (*MediaDB) SetOptimizationStep added in v2.7.0 

func (db *MediaDB) SetOptimizationStep(step string) error

func (*MediaDB) SetSQLForTesting 

func (db *MediaDB) SetSQLForTesting(ctx context.Context, sqlDB *sql.DB, platform platforms.Platform) error

SetSQLForTesting allows injection of a sql.DB instance for testing purposes. This method should only be used in tests to set up in-memory databases.

func (*MediaDB) SetScrapingOperation added in v2.14.0 

func (db *MediaDB) SetScrapingOperation(operation database.ScrapingOperation) error

func (*MediaDB) SetScrapingStatus added in v2.14.0 

func (db *MediaDB) SetScrapingStatus(status string) error

func (*MediaDB) StageScannedMedia added in v2.16.0 

func (db *MediaDB) StageScannedMedia(media *database.ScanStagedMedia) error

StageScannedMedia appends one scanned file and its tags to the scanner staging tables through the batch inserters. Requires an open batch transaction (BeginTransaction(true)).

func (*MediaDB) SystemIndexed 

func (db *MediaDB) SystemIndexed(system *systemdefs.System) bool

SystemIndexed returns true if a specific system is indexed in the media database.

func (*MediaDB) TemporaryRepairJobsPending added in v2.12.0 

func (db *MediaDB) TemporaryRepairJobsPending(ctx context.Context) (bool, error)

func (*MediaDB) TrackBackgroundOperation added in v2.7.1 

func (db *MediaDB) TrackBackgroundOperation()

TrackBackgroundOperation increments the background operations counter. Call BackgroundOperationDone when the operation completes. This allows external code (like the indexing goroutine) to be tracked.

func (*MediaDB) Truncate 

func (db *MediaDB) Truncate() error

func (*MediaDB) TruncateSystems added in v2.7.0 

func (db *MediaDB) TruncateSystems(systemIDs []string) error

func (*MediaDB) UnsafeGetSQLDb 

func (db *MediaDB) UnsafeGetSQLDb() *sql.DB

func (*MediaDB) UpdateLastGenerated 

func (db *MediaDB) UpdateLastGenerated() error

func (*MediaDB) UpdateMediaTags added in v2.16.1 

func (db *MediaDB) UpdateMediaTags(
	ctx context.Context,
	mediaDBID int64,
	remove []database.MediaTagRef,
	add []database.MediaTagRef,
) error

UpdateMediaTags mutates file-level tags and refreshes only affected cache aggregates. Removals run before additions, so an addition wins when the same tag appears in both lists.

func (*MediaDB) UpsertMediaBlob added in v2.12.0 

func (db *MediaDB) UpsertMediaBlob(ctx context.Context, contentType string, data []byte) (int64, error)

UpsertMediaBlob computes a SHA-256 hash from framed content type and data, inserts a new MediaBlobs row when no matching hash exists (INSERT OR IGNORE), then returns the DBID of the canonical row. Identical content always resolves to the same DBID.

func (*MediaDB) UpsertMediaProperties added in v2.12.0 

func (db *MediaDB) UpsertMediaProperties(ctx context.Context, mediaDBID int64, props []database.MediaProperty) error

UpsertMediaProperties upserts properties into MediaProperties. Conflicts on (MediaDBID, TypeTagDBID) update data columns; DBID is preserved. p.TypeTag must be set to the full "type:value" string; TypeTagDBID is resolved from the Tags table automatically.

When called inside an open batch transaction, the write uses db.conn() instead of opening a second transaction. SQLite WAL allows one writer, so a nested BeginTx here would block behind the batch transaction until busy_timeout.

func (*MediaDB) UpsertMediaTags added in v2.12.0 

func (db *MediaDB) UpsertMediaTags(ctx context.Context, mediaDBID int64, tagInfos []database.TagInfo) error

UpsertMediaTags writes tags to MediaTags for a specific Media row, respecting TagTypes.IsExclusive: exclusive types delete existing tags of that type first; additive types use INSERT OR IGNORE.

func (*MediaDB) UpsertMediaTitleProperties added in v2.12.0 

func (db *MediaDB) UpsertMediaTitleProperties(
	ctx context.Context, mediaTitleDBID int64, props []database.MediaProperty,
) error

UpsertMediaTitleProperties upserts properties into MediaTitleProperties. Conflicts on (MediaTitleDBID, TypeTagDBID) update data columns; DBID is preserved. p.TypeTag must be set to the full "type:value" string; TypeTagDBID is resolved from the Tags table automatically.

func (*MediaDB) UpsertMediaTitleTags added in v2.12.0 

func (db *MediaDB) UpsertMediaTitleTags(ctx context.Context, mediaTitleDBID int64, tagInfos []database.TagInfo) error

UpsertMediaTitleTags writes tags to MediaTitleTags for a specific MediaTitle row.

func (*MediaDB) Vacuum 

func (db *MediaDB) Vacuum() error

func (*MediaDB) WALCheckpoint added in v2.10.0 

func (db *MediaDB) WALCheckpoint() error

WALCheckpoint forces a WAL checkpoint to flush pending writes to the main database file. It holds sqlMu so the TRUNCATE checkpoint is serialized with commits and other writes (matching the in-commit checkpoint in CommitTransactionWithOptions), and is a no-op while a transaction is open — truncating the WAL out from under an active writer on the other pool connection would only ever return SQLITE_BUSY.

func (*MediaDB) WaitForBackgroundOperations added in v2.7.0 

func (db *MediaDB) WaitForBackgroundOperations()

WaitForBackgroundOperations waits for all background operations to complete. This should be called before closing the database to ensure clean shutdown.

type MediaStats added in v2.7.0 

type MediaStats struct {
	Count   int
	MinDBID int64
	MaxDBID int64
}

MediaStats represents cached statistics for a media query

type PreFilterQuery added in v2.7.0 

type PreFilterQuery struct {
	MinLength    int
	MaxLength    int
	MinWordCount int
	MaxWordCount int
}

PreFilterQuery represents pre-filter parameters for efficient fuzzy matching candidate reduction.

type SlugMetadata added in v2.7.0 

type SlugMetadata struct {
	Slug          string
	SecondarySlug string
	SlugLength    int
	SlugWordCount int
}

SlugMetadata contains pre-filter columns computed from a slug. This metadata enables efficient fuzzy matching by reducing the candidate set before applying expensive string similarity algorithms.

func GenerateSlugMetadataFromTokens added in v2.10.0 

func GenerateSlugMetadataFromTokens(
	mediaType slugs.MediaType,
	input string,
	slug string,
	tokens []string,
) SlugMetadata

GenerateSlugMetadataFromTokens computes slug metadata from a pre-computed slug and tokens. This avoids redundant slugification when the slug and tokens have already been computed (e.g., during GetPathFragments). The secondary slug still requires slugification since it is derived from the original title, not the pre-computed slug.

func GenerateSlugWithMetadata added in v2.7.0 

func GenerateSlugWithMetadata(mediaType slugs.MediaType, input string) SlugMetadata

GenerateSlugWithMetadata normalizes input and computes all prefilter metadata. CRITICAL: Uses SlugifyWithTokens to ensure metadata matches the actual slug.

The metadata is computed from the EXACT tokens extracted during the 14-stage normalization pipeline, not from re-tokenization. This ensures consistency between the slug and its metadata.

The mediaType parameter should match the MediaType of the system being indexed, ensuring consistent slugification between indexing and resolution.

If the title contains a secondary title separator (: or -), the secondary slug is also extracted and stored separately to enable efficient secondary title matching.

Example: 

metadata := GenerateSlugWithMetadata(slugs.MediaTypeGame, "The Legend of Zelda: Ocarina of Time")
metadata.Slug         → "legendofzeldaocarinaoftime"
metadata.SlugLength   → 26 (character count)
metadata.SlugWordCount → 6 (token count: legend, of, zelda, ocarina, of, time)
metadata.SecondarySlug → "ocarinaoftime" (secondary title after colon)

type SlugSearchCache added in v2.10.0 

type SlugSearchCache struct {
	// contains filtered or unexported fields
}

SlugSearchCache holds all slug data in memory for fast substring matching. Entries are sorted by systemDBID for contiguous system-filtered scans. A trigram inverted index accelerates unfiltered substring searches.

Mid-scan indexing maintenance mutates the cache logically without touching the entry arrays: dropping a system tombstones its contiguous block (droppedRanges/liveEntries) and a refresh appends the system's new entries as a block at the end with a trigramDelta layer for postings. Tombstoned entries and delta layers accumulate only until the end-of-run full rebuild publishes a compact cache. All fields are immutable after publication via the atomic pointer; writers build a new struct (sharing arrays) and swap.

func (*SlugSearchCache) CanServeSystems added in v2.11.0 

func (c *SlugSearchCache) CanServeSystems(systemIDs []string) bool

func (*SlugSearchCache) ExactSecondarySlugMatch added in v2.10.0 

func (c *SlugSearchCache) ExactSecondarySlugMatch(systemDBIDs []int64, secSlug []byte) []int64

ExactSecondarySlugMatch returns title DBIDs where the secondary slug exactly matches the given bytes.

func (*SlugSearchCache) ExactSlugMatch added in v2.10.0 

func (c *SlugSearchCache) ExactSlugMatch(systemDBIDs []int64, slug []byte) []int64

ExactSlugMatch returns title DBIDs where the slug exactly matches the given bytes.

func (*SlugSearchCache) ExactSlugMatchAny added in v2.10.0 

func (c *SlugSearchCache) ExactSlugMatchAny(systemDBIDs []int64, slugList [][]byte) []int64

ExactSlugMatchAny returns title DBIDs where the slug exactly matches any of the given slugs.

func (*SlugSearchCache) PrefixSlugMatch added in v2.10.0 

func (c *SlugSearchCache) PrefixSlugMatch(systemDBIDs []int64, prefix []byte) []int64

PrefixSlugMatch returns title DBIDs where the slug starts with the given prefix.

func (*SlugSearchCache) RandomEntry added in v2.10.0 

func (c *SlugSearchCache) RandomEntry(systemDBIDs []int64) (int64, bool)

RandomEntry picks a random title DBID from entries matching the system filter.

func (*SlugSearchCache) ResolveSystemDBIDs added in v2.10.0 

func (c *SlugSearchCache) ResolveSystemDBIDs(systemIDs []string) []int64

ResolveSystemDBIDs converts system ID strings to database IDs using the cache's lookup map.

func (*SlugSearchCache) Search added in v2.10.0 

func (c *SlugSearchCache) Search(systemDBIDs []int64, variantGroups [][][]byte) []int64

Search finds all title DBIDs matching the given system filter and variant groups. systemDBIDs is the system filter (empty = no filter). variantGroups is AND-of-ORs: each group is a set of byte variants for one query word (OR'd together), and all groups must match (AND'd together).

func (*SlugSearchCache) Size added in v2.10.0 

func (c *SlugSearchCache) Size() int

Size returns the approximate memory footprint of the cache in bytes.

func (*SlugSearchCache) TrigramIndexSize added in v2.10.0 

func (c *SlugSearchCache) TrigramIndexSize() int

TrigramIndexSize returns the memory footprint of the trigram index in bytes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.