Database

pyconvexity.core.database

Database connection and schema management for PyConvexity.

Provides clean abstractions for database operations with proper connection management, schema validation, and resource cleanup.

DatabaseContext

Context manager for database connections with automatic cleanup.

Provides a clean way to manage database connections with proper resource cleanup and error handling.

database_context(db_path: str, read_only: bool = False) -> Generator[sqlite3.Connection, None, None]

Context manager function for database connections.

Parameters:

Name	Type	Description	Default
db_path	str	Path to the SQLite database file	required
read_only	bool	If True, open in read-only mode	False

Yields:

Type	Description
Connection	sqlite3.Connection: Database connection with proper configuration

Example

with database_context("model.db") as conn: cursor = conn.execute("SELECT * FROM networks") networks = cursor.fetchall()

open_connection(db_path: str, read_only: bool = False) -> sqlite3.Connection

Open database connection with proper settings.

Parameters:

Name	Type	Description	Default
db_path	str	Path to the SQLite database file	required
read_only	bool	If True, open in read-only mode	False

Returns:

Type	Description
Connection	sqlite3.Connection: Configured database connection

Raises:

Type	Description
ConnectionError	If database connection fails

validate_database(conn: sqlite3.Connection) -> None

Validate database schema has required tables.

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection to validate	required

Raises:

Type	Description
ValidationError	If required tables are missing

create_database_with_schema(db_path: str) -> None

Create a new database and apply the complete schema.

Parameters:

Name	Type	Description	Default
db_path	str	Path where the new database should be created	required

Raises:

Type	Description
DatabaseError	If schema files cannot be found or applied

get_database_info(conn: sqlite3.Connection) -> dict

Get information about the database structure and contents.

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection	required

Returns:

Type	Description
dict	Dictionary with database information

check_database_compatibility(conn: sqlite3.Connection) -> dict

Check if database is compatible with current PyConvexity version.

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection	required

Returns:

Type	Description
dict	Dictionary with compatibility information

vacuum_database(conn: sqlite3.Connection) -> None

Run VACUUM to reclaim database space and defragment.

VACUUM rebuilds the database file, repacking it into a minimal amount of disk space. This is useful after deleting large amounts of data or after many INSERT/UPDATE/DELETE operations.

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection	required

Note

VACUUM can take a significant amount of time on large databases and requires temporary disk space up to twice the size of the original database.

analyze_database(conn: sqlite3.Connection) -> None

Run ANALYZE to update query planner statistics.

ANALYZE gathers statistics about the contents of tables and indices. These statistics are used by the query planner to help make better choices about how to perform queries.

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection	required

optimize_database(conn: sqlite3.Connection) -> dict

Run complete database optimization (VACUUM + ANALYZE).

This performs both VACUUM and ANALYZE operations in the correct order: 1. VACUUM first to reclaim space and defragment 2. ANALYZE to update statistics with the new layout

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection	required

Returns:

Type	Description
dict	Dictionary with optimization results including before/after size information

get_database_size_info(conn: sqlite3.Connection) -> dict

Get detailed information about database size and space usage.

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection	required

Returns:

Type	Description
dict	Dictionary with size information including total, used, and free space

should_optimize_database(conn: sqlite3.Connection, free_space_threshold_percent: float = 10.0) -> bool

Check if database would benefit from optimization based on free space.

Parameters:

Name	Type	Description	Default
conn	Connection	Database connection	required
free_space_threshold_percent	float	Threshold percentage of free space to trigger optimization	10.0

Returns:

Type	Description
bool	True if optimization is recommended, False otherwise