Skip to main content
The database functions module provides thread-safe operations for storing and retrieving TorBox download metadata using TinyDB as a local cache.

​
Database connection management

​
getDatabase

def getDatabase(name: str = "db")
Returns a TinyDB database instance with thread-safe storage. Uses a connection pool pattern to avoid creating multiple connections to the same database.
​
name
str
default:"db"
The database name (corresponds to {name}.json file).
​
return
TinyDB | None
The TinyDB database instance, or None if connection fails.
Connection pooling:
  • Creates a single shared connection per database name
  • Automatically creates the database file if it doesn’t exist
  • Thread-safe initialization using a global lock
Example: 
from functions.databaseFunctions import getDatabase

db = getDatabase("torrents")
if db:
    print(f"Connected to database: torrents.json")

​
getDatabaseLock

def getDatabaseLock(name: str = "db")
Returns the threading lock for a specified database. Each database has its own lock to prevent race conditions.
​
name
str
default:"db"
The database name.
​
return
threading.Lock | None
The lock object for the database, or None if the database doesn’t exist.
Example: 
from functions.databaseFunctions import getDatabase, getDatabaseLock

db = getDatabase("torrents")
lock = getDatabaseLock("torrents")

with lock:
    # Perform thread-safe operations
    all_data = db.all()

​
Data operations

​
insertData

def insertData(data: dict, type: str)
Inserts a data record into the database with thread safety.
​
data
dict
required
The data dictionary to insert.
​
type
str
required
The database type/name (e.g., “torrents”, “usenet”, “webdl”).
​
return
tuple
A tuple containing:
  • success (bool): True if insertion succeeded
  • message (str): Success or error message
Thread safety: Acquires the database lock before inserting to prevent concurrent write conflicts. Example: 
from functions.databaseFunctions import insertData

file_data = {
    "item_id": 12345,
    "file_name": "movie.mkv",
    "file_size": 1024000000,
    "metadata_title": "The Matrix",
    "metadata_years": 1999,
}

success, message = insertData(file_data, "torrents")
if success:
    print("Data inserted successfully")
else:
    print(f"Error: {message}")

​
getAllData

def getAllData(type: str)
Retrieves all data from a database with thread safety.
​
type
str
required
The database type/name to query.
​
return
tuple
A tuple containing:
  • data (list | None): List of all records, or None on error
  • success (bool): True if retrieval succeeded
  • message (str): Success or error message
Example: 
from functions.databaseFunctions import getAllData

data, success, message = getAllData("torrents")

if success:
    print(f"Retrieved {len(data)} records")
    for record in data:
        print(f"- {record.get('metadata_title')}")
else:
    print(f"Error: {message}")

​
clearDatabase

def clearDatabase(type: str)
Clears all records from a database with thread safety.
​
type
str
required
The database type/name to clear.
​
return
tuple
A tuple containing:
  • success (bool): True if clearing succeeded
  • message (str): Success or error message
Warning: This operation is irreversible and removes all data from the database. Example: 
from functions.databaseFunctions import clearDatabase

success, message = clearDatabase("torrents")
if success:
    print("Database cleared")
else:
    print(f"Error: {message}")

​
Connection cleanup

​
closeDatabase

def closeDatabase(name: str = "db")
Closes a specific database connection and removes it from the connection pool.
​
name
str
default:"db"
The database name to close.
​
return
tuple
A tuple containing:
  • success (bool): True if closing succeeded or database wasn’t open
  • message (str): Success or error message
Example: 
from functions.databaseFunctions import closeDatabase

success, message = closeDatabase("torrents")
print(message)  # "Database closed successfully." or "Database was not open."

​
closeAllDatabases

def closeAllDatabases()
Closes all open database connections.
​
return
tuple
A tuple containing:
  • success (bool): Always True
  • message (str): Summary message indicating number of connections closed
Example: 
from functions.databaseFunctions import closeAllDatabases

success, message = closeAllDatabases()
print(message)  # "Closed 3 database connections."

​
Thread safety model

All database operations in this module are thread-safe:
  1. Global lock: Protects the connection pool during database initialization
  2. Per-database locks: Each database has its own lock for data operations
  3. Automatic locking: All data operations acquire locks before accessing the database
Example of manual locking: 
from functions.databaseFunctions import getDatabase, getDatabaseLock

db = getDatabase("torrents")
lock = getDatabaseLock("torrents")

with lock:
    # Multiple operations performed atomically
    count = len(db.all())
    if count > 0:
        db.truncate()
        print(f"Cleared {count} records")

​
Database storage format

Databases are stored as JSON files:
  • torrents.json - Torrent download cache
  • usenet.json - Usenet download cache
  • webdl.json - WebDL download cache
Each record is a dictionary containing file metadata, download links, and media information as returned by process_file in the TorBox functions module.

​
Error handling

All functions return tuple-based results for consistent error handling: 
success, message = insertData(data, "torrents")
if not success:
    # Handle error
    print(f"Database error: {message}")
For functions that return data: 
data, success, message = getAllData("torrents")
if not success:
    # Handle error
    print(f"Database error: {message}")
else:
    # Use data
    process_files(data)

Build docs developers (and LLMs) love

Get started for freeTalk to us