Struct Database

pub struct Database { /* private fields */ }

Handle for interacting with the paper database.

This struct manages an async connection to a SQLite database and provides methods for storing and retrieving paper metadata. It uses SQLite’s full-text search capabilities for efficient paper discovery.

The database is automatically initialized with the required schema when opened. If the database file doesn’t exist, it will be created.

Implementations

impl Database

pub async fn open(path: impl AsRef<Path>) -> Result<Self, LearnerError>

Opens an existing database or creates a new one at the specified path.

This method will:

1. Create the database file if it doesn’t exist
2. Initialize the schema using migrations
3. Set up full-text search indexes

Arguments

• path - Path where the database file should be created or opened

Returns

Returns a Result containing either:

• A Database handle for database operations
• A LearnerError if database creation or initialization fails

Examples

// Open in a specific location
let db = Database::open("papers.db").await?;

// Or use the default location
let db = Database::open(Database::default_path()).await?;

pub fn default_path() -> PathBuf

Returns the default path for the database file.

The path is constructed as follows:

• On Unix: ~/.local/share/learner/learner.db
• On macOS: ~/Library/Application Support/learner/learner.db
• On Windows: %APPDATA%\learner\learner.db
• Fallback: ./learner.db in the current directory

Examples

let path = learner::database::Database::default_path();
println!("Database will be stored at: {}", path.display());

pub async fn save_paper(&self, paper: &Paper) -> Result<i64, LearnerError>

Saves a paper and its authors to the database.

This method will:

1. Insert the paper’s metadata into the papers table
2. Insert all authors into the authors table
3. Update the full-text search index

The operation is performed in a transaction to ensure data consistency.

Arguments

• paper - The paper to save

Returns

Returns a Result containing either:

• The database ID of the saved paper
• A LearnerError if the save operation fails

Examples

let db = Database::open("papers.db").await?;
let paper = Paper::new("2301.07041").await?;
let id = db.save_paper(&paper).await?;
println!("Saved paper with ID: {}", id);

pub async fn get_paper_by_source_id( &self, source: &Source, source_id: &str, ) -> Result<Option<Paper>, LearnerError>

Retrieves a paper using its source and identifier.

This method looks up a paper based on its origin (e.g., arXiv, DOI) and its source-specific identifier. It also fetches all associated author information.

Arguments

• source - The paper’s source system (arXiv, IACR, DOI)
• source_id - The source-specific identifier

Returns

Returns a Result containing either:

• Some(Paper) if found
• None if no matching paper exists
• A LearnerError if the query fails

Examples

let db = Database::open("papers.db").await?;
if let Some(paper) = db.get_paper_by_source_id(&Source::Arxiv, "2301.07041").await? {
  println!("Found paper: {}", paper.title);
}

pub async fn search_papers( &self, query: &str, ) -> Result<Vec<Paper>, LearnerError>

Searches for papers using full-text search.

This method uses SQLite’s FTS5 module to perform full-text search across:

• Paper titles
• Paper abstracts

Results are ordered by relevance using FTS5’s built-in ranking algorithm.

Arguments

• query - The search query using FTS5 syntax

Returns

Returns a Result containing either:

• A vector of matching papers
• A LearnerError if the search fails

Examples

let db = learner::database::Database::open("papers.db").await?;

// Simple word search
let papers = db.search_papers("quantum").await?;

// Phrase search
let papers = db.search_papers("\"neural networks\"").await?;

// Complex query
let papers = db.search_papers("machine learning NOT regression").await?;

pub fn default_pdf_path() -> PathBuf

Returns the default path for PDF storage.

The path is constructed as follows:

• On Unix: ~/Documents/learner/papers
• On macOS: ~/Documents/learner/papers
• On Windows: Documents\learner\papers
• Fallback: ./papers in the current directory

Examples

let path = learner::database::Database::default_pdf_path();
println!("PDFs will be stored at: {}", path.display());

pub async fn set_config( &self, key: &str, value: &str, ) -> Result<(), LearnerError>

Sets a configuration value in the database.

Arguments

• key - The configuration key
• value - The value to store

Returns

Returns a Result indicating success or failure

pub async fn get_config( &self, key: &str, ) -> Result<Option<String>, LearnerError>

Gets a configuration value from the database.

Arguments

• key - The configuration key to retrieve

Returns

Returns a Result containing either:

• Some(String) with the configuration value
• None if the key doesn’t exist

pub async fn record_pdf( &self, paper_id: i64, path: PathBuf, filename: String, status: &str, error: Option<String>, ) -> Result<i64, LearnerError>

Records a PDF file location and status for a paper.

Arguments

• paper_id - The database ID of the paper
• path - Full path to the file
• filename - The filename
• status - Download status (‘success’, ‘failed’, ‘pending’)
• error - Optional error message if download failed

Returns

Returns a Result containing the file ID on success

pub async fn get_pdf_status( &self, paper_id: i64, ) -> Result<Option<(PathBuf, String, String, Option<String>)>, LearnerError>

Gets the PDF status for a paper.

Arguments

• paper_id - The database ID of the paper

Returns

Returns a Result containing either:

• Some((PathBuf, String, String, Option)) with the path, filename, status, and error
• None if no PDF entry exists