PhysiCellModelManager.jl Upgrade

continueMilestoneUpgrade(version::VersionNumber, auto_upgrade::Bool)

Print a warning about the schema change at version and prompt the user to confirm unless auto_upgrade is true. Returns true if the upgrade should proceed, false if the user aborted.

Call this at the top of any upgradeToMilestone implementation that makes large or destructive changes to the database schema.

populateTableOnFeatureSubset(db::SQLite.DB, source_table::String, target_table::String; column_mapping::Dict{String,String}=Dict{String,String}())

Populate a target_table with rows from source_table. Columns in source_table that exist (possibly under a different name) in target_table are copied; extras are ignored. Use column_mapping to rename columns during the copy (source_name => target_name).

upgradePackage(sim::AbstractSimulator, db::SQLite.DB, from_version::VersionNumber, to_version::VersionNumber, auto_upgrade::Bool)

Drive the database migration from from_version to to_version for the simulator framework sim.

For each milestone v in upgradeMilestones(sim) with from_version < v ≤ to_version, calls upgradeToMilestone(sim, v, auto_upgrade). After a successful milestone upgrade the version table is updated immediately so that a partial upgrade is recoverable. If any milestone fails the chain is aborted and false is returned.

After all milestones pass, if to_version is beyond the last milestone the version table is stamped with to_version (a "no schema change" bump).

A to_version beyond the version loaded in this session is refused, leaving the version table untouched.

getDBPackageVersion(sim::AbstractSimulator, db::SQLite.DB)::VersionNumber

Return the package version recorded in db under dbVersionTableName(sim).

If the table does not exist it is created and stamped with the version this session is running. Throws if that version cannot be determined.

Arguments

• sim::AbstractSimulator: the active simulator backend.
• db::SQLite.DB: the project database.

Returns

The recorded VersionNumber.

Example

ModelManager.getDBPackageVersion(simulator(), centralDB())

getInstalledVersion(sim::AbstractSimulator)::VersionNumber

Return the version of sim's package as installed in the active environment — what Pkg.status prints, and what Pkg.update changes.

Not necessarily the version running: migrations target the version loaded in this session, and the two differ when the environment changes while a session is open.

The package is the one defining typeof(sim).

Arguments

• sim::AbstractSimulator: the active simulator backend.

Returns

The installed VersionNumber.

Example

ModelManager.getInstalledVersion(simulator())

resolvePackageVersion(sim::AbstractSimulator, db::SQLite.DB; auto_upgrade::Bool=false)::Bool

Compare the version recorded in db with the version loaded in this session and upgrade to it if needed. Returns true when the database is ready to use, false when it is not.

When no loaded version can be determined, the project opens unmigrated and untracked, with a warning.

Arguments

• sim::AbstractSimulator: the active simulator backend.
• db::SQLite.DB: the project database.

Keywords

• auto_upgrade::Bool=false: apply migrations without prompting.

Returns

true if the database is at the loaded version, already or after a successful migration, and also when no loaded version can be determined; false if the database is ahead of the loaded version, or a migration failed.

Example

ModelManager.resolvePackageVersion(simulator(), centralDB(); auto_upgrade=true)