{"record":{"id":"d03a33b64c48d8c8","repo":"iflytek/astron-agent","slug":"missing-required-mysql-environment-variables-for-migration","errorCode":null,"errorMessage":"Missing required MySQL environment variables for migration: {missing_envs}","messagePattern":"Missing required MySQL environment variables for migration: (.+?)","errorType":"console","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"core/plugin/link/extensions/database_migration.py","lineNumber":59,"sourceCode":"    mysql_host = os.getenv(const.MYSQL_HOST_KEY)\n    mysql_port = os.getenv(const.MYSQL_PORT_KEY)\n    mysql_user = os.getenv(const.MYSQL_USER_KEY)\n    mysql_password = os.getenv(const.MYSQL_PASSWORD_KEY)\n    mysql_db = os.getenv(const.MYSQL_DB_KEY)\n\n    missing_envs = [\n        key\n        for key, value in [\n            (const.MYSQL_HOST_KEY, mysql_host),\n            (const.MYSQL_PORT_KEY, mysql_port),\n            (const.MYSQL_USER_KEY, mysql_user),\n            (const.MYSQL_PASSWORD_KEY, mysql_password),\n            (const.MYSQL_DB_KEY, mysql_db),\n        ]\n        if not value\n    ]\n    if missing_envs:\n        raise ValueError(\n            \"Missing required MySQL environment variables for migration: \"\n            f\"{', '.join(missing_envs)}\"\n        )\n\n\ndef _build_alembic_config(link_dir: Path) -> Config:\n    \"\"\"Build Alembic config from local link module files.\"\"\"\n    alembic_dir = link_dir / \"alembic\"\n    alembic_ini = link_dir / \"alembic.ini\"\n    if not alembic_ini.exists():\n        logging.error(\"alembic.ini not found: %s\", alembic_ini)\n        raise FileNotFoundError(f\"alembic.ini not found: {alembic_ini}\")\n\n    config = Config(str(alembic_ini))\n    config.set_main_option(\"script_location\", str(alembic_dir))\n    return config\n\n","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/plugin/link/extensions/database_migration.py#L41-L77","documentation":"The link plugin's database migration runner validates that all required MySQL environment variables (host, port, user, password, database) are present before invoking Alembic. _check_db_url collects the env keys whose values are empty/missing and raises a ValueError listing them. This is a fail-fast guard so the migration never runs against a partially configured database.","triggerScenarios":"Running run_database_migration (e.g. on service startup or a migration script) when any of the const.MYSQL_*_KEY environment variables — MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DB — is unset or set to an empty string.","commonSituations":"Deploying without the MySQL section of the .env / docker-compose / Helm values; renaming env vars in a new release so old deployments keep stale keys; running migrations locally without sourcing the env file; CI jobs missing secret injection.","solutions":["Set all required MySQL env vars (host, port, user, password, db) in the environment or .env file before running migrations","Check deployment config (docker-compose env_file, Helm secrets) actually injects the MYSQL_* variables into the container","Source the correct env file in local/CI shells (e.g. `set -a; . .env; set +a`) before invoking the migration","Fix env var name mismatches between const.py keys and the actual exported variable names"],"exampleFix":"// before\n# .env\nMYSQL_HOST=\nMYSQL_DB=link\n// after\n# .env\nMYSQL_HOST=127.0.0.1\nMYSQL_PORT=3306\nMYSQL_USER=root\nMYSQL_PASSWORD=secret\nMYSQL_DB=link","handlingStrategy":"validation","validationCode":"import os\nrequired = [\"MYSQL_HOST\", \"MYSQL_PORT\", \"MYSQL_USER\", \"MYSQL_PASSWORD\", \"MYSQL_DB\"]\nmissing = [k for k in required if not os.getenv(k)]\nif missing:\n    raise SystemExit(f\"Missing MySQL env vars: {', '.join(missing)}\")","typeGuard":null,"tryCatchPattern":"try:\n    run_database_migration()\nexcept ValueError as e:\n    if \"Missing required MySQL\" in str(e):\n        sys.exit(f\"Config error: {e}\")\n    raise","preventionTips":["Keep required env vars documented and validated at service startup","Use docker-compose env_file / Helm secrets so vars are injected consistently","Fail fast with the same _check_db_url check in CI before migrations","Watch for env key renames between releases and update deployment configs"],"tags":["mysql","environment","configuration","migration"],"backgroundTag":"missing-env-var","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}