qlocalclonedb

qlocalclonedb — Clone a Staging Tenant into a Named Local DB

Clones a staging tenant's the Postgres provider DB into a side-by-side local Postgres database. Lets multiple cloned tenants coexist (e.g. {{LOCAL_DEV_DB_NAME}} for Example Tenant plus local_acme_corp_db for Acme Corp) so you can switch between them without re-cloning.

Input: $ARGUMENTS

• --tenant <name> — exact staging tenant name (use --list to discover) — REQUIRED unless --list
• --db-name <db> — local Postgres DB name to create (default: local_<sanitized_tenant>_db)
• --list — list available staging tenants and exit; nothing else happens
• --staging-url <url> — staging GLOBAL_DATABASE_URL (overrides .env.dev). Pass inline once if .env.dev is missing
• --remote-url <url> — full Postgres URL for the tenant DB to dump from, bypassing the DB provider API lookup. Use this when the tenant's app.account_registry row points at a different DB provider branch than the one you want to clone (e.g. the registry pins main/production but you actually want develop). Supply the pooled DB provider endpoint URL, e.g. postgresql://<role>:<pw>@<pooler-host>.example-postgres.com/<db>?sslmode=require. When this is set, the local DB_PROVIDER_API_KEY is not used to fetch the connection string.
• --branch-endpoint <ep-id> — DB provider endpoint ID for a specific branch (e.g. <branch-endpoint-id>). Lighter-weight alternative to --remote-url: the skill assembles the full URL from the endpoint ID, the tenant's db_database_name / db_role_name from app.account_registry, and the password from the existing tenant URL pattern. Useful when you know "I want develop branch" but not the full connection string. Requires --tenant so role/database can be resolved.
• --reclone — drop the local DB if it already exists before recreating

Defaults: requires either .env.dev in {{PRIMARY_REPO_NAME}}/ OR --staging-url. The local DB_PROVIDER_API_KEY (from {{PRIMARY_REPO_NAME}}/.env) is reused — except when --remote-url or --branch-endpoint is set, in which case the API lookup is skipped.

When to override the branch. app.account_registry stores ONE the Postgres provider branch_id per tenant. In multi-environment DB provider projects (e.g. one project hosting main + develop + per-PR preview branches), that pin usually points at main. If you're testing a fix against data that only exists on the develop branch, the default clone path pulls the wrong data — records may be missing, record_hash_id may be NULL, record_mappings rows may differ. Symptom: clone succeeds, but the rules_engine resolver returns no applicable policies because the lines aren't categorised under the expected scope. Use --remote-url or --branch-endpoint to target the right branch explicitly.