Database storage

Persist, query, and retrieve your analysis results with any database.

Overview

Reveilio can route analysis results to a database so you can store, query, and retrieve them later. Four backends are supported out of the box:

Installation

SQLite works out of the box (it is part of the Python standard library). For other backends, install the relevant extra:

# PostgreSQL
pip install reveilio[postgresql]

# MySQL
pip install reveilio[mysql]

# MongoDB
pip install reveilio[mongodb]

# All database backends at once
pip install reveilio[all-db]

Connecting to a database

Call reveilio.connect_db() once at program start to establish a connection. All subsequent export_* and import_* calls use this connection automatically.

SQLite

The simplest option — no server, no credentials, just a file path.

import reveilio

reveilio.connect_db(
    "sqlite",
    filepath="my_analyses.db",      # creates file if it doesn't exist
)

If you omit filepath, it defaults to reveilio.db in the current directory.

PostgreSQL

reveilio.connect_db(
    "postgresql",
    host="localhost",
    port=5432,
    database="recruitment",
    username="admin",
    password="secret",
)

Environment fallbacks: REVEILIO_DB_HOST, REVEILIO_DB_PORT, REVEILIO_DB_NAME, REVEILIO_DB_USER, REVEILIO_DB_PASSWORD.

MySQL

reveilio.connect_db(
    "mysql",
    host="db.example.com",
    port=3306,
    database="hiring",
    username="root",
    password="secret",
)

MongoDB

reveilio.connect_db(
    "mongodb",
    host="localhost",
    port=27017,
    database="reveilio",
    username="admin",               # optional
    password="secret",              # optional
)

Connection string override

For any backend, you can pass a full connection string instead of individual parameters:

reveilio.connect_db(
    "postgresql",
    connection_string="postgresql://user:pass@host:5432/mydb",
)

Environment variables

Every connection parameter can be set via environment variables. This is useful for production deployments where credentials should not be in code:

Exporting results to the database

After running an analysis, export the results to the database:

Single result

# Analyze and export
result = reveilio.analyze_resume("resume.pdf", jd)
analysis_id = reveilio.export_result(result, job_title="Backend Engineer")
print(f"Stored as: {analysis_id}")

Batch export

# Analyze a folder and export all results
results = reveilio.analyze_folder("./resumes", jd)
ids = reveilio.export_results(results, job_title="Backend Engineer")
print(f"Stored {len(ids)} analyses")

Each result is assigned a unique analysis_id (UUID). You can also pass your own ID:

reveilio.export_result(result, analysis_id="my-custom-id-001")

Importing results from the database

Load by ID

result = reveilio.import_result("analysis-uuid-here")
print(result.overall_score, result.recommendation)

Load recent results

# Load the 10 most recent analyses
results = reveilio.import_results(limit=10)

# Load with pagination
page_2 = reveilio.import_results(limit=10, offset=10)

# Sort by score instead of date
top_scores = reveilio.import_results(order_by="overall_score", descending=True)

List analyses (metadata only)

When you just need a summary without the full analysis data:

entries = reveilio.list_analyses(limit=20)
for entry in entries:
    print(f"{entry['candidate_name']}: {entry['overall_score']} - {entry['recommendation']}")

Returns dicts with: analysis_id, candidate_name, overall_score, confidence_level, recommendation, job_title, created_at.

Querying with filters

Use query_results() to find analyses matching specific criteria. All filters are optional and combined with AND logic:

# Candidates scoring above 80
top = reveilio.query_results(min_score=80)

# Shortlisted candidates for a specific role
shortlisted = reveilio.query_results(
    recommendation="Shortlist",
    job_title="Backend Engineer",
)

# Search by candidate name
matches = reveilio.query_results(candidate_name="John")

# Combine multiple filters
precise = reveilio.query_results(
    min_score=70,
    max_score=95,
    recommendation="Shortlist",
    limit=50,
)

Deleting results

# Delete by analysis ID
deleted = reveilio.delete_result("analysis-uuid-here")
if deleted:
    print("Record removed")

Disconnecting

Close the database connection when you are done:

reveilio.disconnect_db()

Calling connect_db() again after disconnecting opens a fresh connection. If you call connect_db() while already connected, the old connection is closed automatically before opening the new one.

Switching databases at runtime

Just call connect_db() again. The previous connection is closed automatically:

# Start with SQLite for local dev
reveilio.connect_db("sqlite", filepath="dev.db")
reveilio.export_results(results)

# Switch to PostgreSQL for production
reveilio.connect_db("postgresql", host="prod-db.internal", database="hiring", ...)
reveilio.export_results(results)

Database schema

Reveilio automatically creates the required table (or collection for MongoDB) on first connection. The schema stores both queryable metadata columns and the full analysis payload as JSON:

Indexes are created on analysis_id (unique), candidate_name, overall_score, and recommendation for fast querying.

Custom table name

By default the table is called reveilio_analyses. You can change it:

reveilio.connect_db("sqlite", table_name="q1_hiring_2026")

Full workflow example

import reveilio

# 1. Configure LLM
reveilio.configure(provider="gemini", api_key="AIza...")

# 2. Connect to database
reveilio.connect_db("sqlite", filepath="hiring_q1.db")

# 3. Run analysis
jd = reveilio.JobDescription.from_file("backend_jd.pdf")
results = reveilio.analyze_folder("./resumes", jd)

# 4. Export to database
ids = reveilio.export_results(results, job_title="Backend Engineer")
print(f"Saved {len(ids)} candidates")

# 5. Query later
shortlisted = reveilio.query_results(
    recommendation="Shortlist",
    min_score=75,
)
for r in shortlisted:
    name = r.candidate_data.name if r.candidate_data else "Unknown"
    print(f"  {name}: {r.overall_score}/100 — {r.recommendation}")

# 6. Generate PDF reports for shortlisted
for r in shortlisted:
    name = r.candidate_data.name.replace(" ", "_") if r.candidate_data else "candidate"
    reveilio.save_report_pdf(r, f"reports/{name}.pdf")

# 7. Disconnect when done
reveilio.disconnect_db()

Continue to Guides.