Module persistence 

Query persistence subsystem.

This module provides persistence for user aliases and query history, enabling users to save and reuse frequently used queries.

Architecture

The persistence subsystem uses a binary index format (postcard) for efficient storage and fast access. Data is stored in two locations:

• Global: ~/.config/sqry/global.index.user - cross-project aliases
• Local: .sqry-index.user in project root - project-specific aliases

All file operations are atomic (using temp file + rename) to prevent corruption from crashes or concurrent access.

Components

• UserMetadataIndex: Main interface for loading/saving user metadata
• AliasManager: High-level API for managing saved query aliases
• HistoryManager: High-level API for managing query history
• PersistenceConfig: Configuration for paths and limits

Example

use std::sync::Arc;
use sqry_cli::persistence::{
    UserMetadataIndex, PersistenceConfig, StorageScope, AliasManager
};

// Open the index
let config = PersistenceConfig::default();
let index = Arc::new(UserMetadataIndex::open(Some("."), config)?);

// Create an alias manager
let aliases = AliasManager::new(index.clone());
aliases.save("my-query", "search", &["main".into()], None, StorageScope::Global)?;

// Retrieve the alias
let alias = aliases.get("my-query")?;
println!("Command: {} {:?}", alias.alias.command, alias.alias.args);

Structs

AliasExportFile

JSON export format for aliases (for backup/restore via ).

AliasManager

Manager for saved query aliases.

AliasWithScope

Alias with its storage scope for listing.

HistoryEntry

A single entry in the query history.

HistoryManager

Manager for query history.

HistoryState

History state stored in the user metadata index.

HistoryStats

Statistics about the command history.

ImportResult

Result of an import operation.

PersistenceConfig

Configuration for the persistence subsystem.

SavedAlias

A saved query alias.

UserMetadata

Root structure for user metadata stored in the index.

UserMetadataIndex

User metadata index providing atomic access to alias and history storage.

Enums

AliasError

Error type for alias operations.

AliasNameError

Error type for alias name validation.

HistoryError

Error type for history operations.

ImportConflictStrategy

Import conflict resolution strategies.

StorageScope

Storage scope for aliases.

Constants

DEFAULT_MAX_HISTORY_ENTRIES

Default maximum number of history entries to retain.

DEFAULT_MAX_INDEX_BYTES

Default maximum size of the user metadata index in bytes (10 MB).

ENV_CONFIG_DIR

Environment variable for overriding the global config directory.

ENV_NO_HISTORY

Environment variable to disable history recording.

ENV_NO_REDACT

Environment variable to disable secret redaction (default: enabled).

GLOBAL_INDEX_FILE

Global index file name.

LOCAL_INDEX_FILE

Local index file name.

MAX_ALIAS_LENGTH

Maximum alias name length.

MIN_ALIAS_LENGTH

Minimum alias name length.

REDACTED_PLACEHOLDER

Placeholder for redacted secrets.

USER_METADATA_VERSION

Current version of the user metadata format. Increment when making breaking changes to the schema.

Functions

contains_secrets

Check if a string contains potential secrets.

global_config_dir

Get the default global config directory.

open_shared_index

Create a shared user metadata index.

parse_duration

Parse a duration string like “30d”, “1w”, “24h”.

redact_secrets

Redact potential secrets from command arguments.

suggest_alias_name

Suggest a valid alias name based on an invalid input.

validate_alias_name

Validate an alias name according to the specification.