Initialize persistent province-wide habitat tables

Creates <schema>.streams and <schema>.streams_habitat_<sp> (one per species) with IF NOT EXISTS. Idempotent — safe to call before every per-WSG run, and safe under concurrent first-time provisioning (multiple workers can race; only one CREATE wins).

Usage

lnk_persist_init(conn, cfg, species, force_recreate = FALSE)

Arguments

conn: DBI connection.
cfg: An lnk_config object with cfg$pipeline$schema set.
species: Character vector of species codes (uppercased) to create streams_habitat_<sp> tables for. Typically derived via lnk_pipeline_species() or unique(loaded$parameters_fresh$species_code).
force_recreate: Logical. When TRUE, drop any existing target tables whose DDL doesn't match the expected shape — specifically, tables that have unexpected GENERATED ALWAYS columns. Default FALSE errors loud instead so the operator can audit before the destructive recreate. Use when spinning a new host from a snapshot whose fwapg volume carries stale fresh.streams DDL (e.g. cypher snapshots baked when frs_col_generate() had been run on the persist schema). See link#162 Phase 7 hardening.

Value

conn invisibly.

Details

Per-WSG data accumulates into these tables via lnk_pipeline_persist() after each run. Queryable cross-WSG for cartography, intrinsic potential maps, and per-crossing upstream rollups.

Column shape mirrors bcfp's bcfishpass.streams + bcfishpass.habitat_linear_<sp> for familiarity. Driven by the cols_streams / cols_habitat vectors at the top of this file — single source of truth shared with lnk_pipeline_persist().

Examples

if (FALSE) { # \dontrun{
conn <- lnk_db_conn()
cfg <- lnk_config("bcfishpass")
loaded <- lnk_load_overrides(cfg)
species <- unique(loaded$parameters_fresh$species_code)

# First-time setup or healthy state: idempotent CREATE IF NOT EXISTS.
lnk_persist_init(conn, cfg, species)

# If a snapshot-baked DB has stale GENERATED columns on fresh.streams:
lnk_persist_init(conn, cfg, species, force_recreate = TRUE)
} # }