Add a new CDM version¶
The example adds CDM 5.6 from a release v5.6.0. Replace both with the real names.
Every omop-codegen command below needs a running Postgres and its settings, in env vars or
a .env file in the repository root, as in Run locally. Without them the
generator tries localhost:5432.
1. Check the release¶
One release archive of OHDSI/CommonDataModel holds every CDM version. Download it and check that the new version has the usual files:
uv run python -c "from pathlib import Path; from omop_codegen.download import fetch_release; print(fetch_release('v5.6.0', Path('downloads')))"
ls downloads/v5.6.0/*/inst/ddl/5.6/postgresql downloads/v5.6.0/*/inst/csv
| Needed file | Read by |
|---|---|
inst/ddl/5.6/postgresql/OMOPCDM_postgresql_5.6_<part>.sql for ddl, primary_keys, indices, constraints |
cdm_versions.py |
inst/csv/OMOP_CDMv5.6_Table_Level.csv with cdmTableName, tableDescription, userGuidance, etlConventions |
enrich.py |
inst/csv/OMOP_CDMv5.6_Field_Level.csv with cdmTableName, cdmFieldName, userGuidance, etlConventions |
enrich.py |
If a name changed, adapt those two modules first.
2. Register the version¶
| File | Change |
|---|---|
generator/src/omop_codegen/cdm_versions.py |
add CdmVersion("5.6") to CDM_VERSIONS |
generator/src/omop_codegen/config.py |
add "5.6" to the CDM_VERSIONS default, set OMOP_CDM_RELEASE_TAG to "v5.6.0" |
generator/src/omop_codegen/omop_policy.py |
add "5.6" to CANDIDATE_KEYS, start with a copy of the previous version's keys |
generator/tests/test_codegen.py |
test_cdm_versions lists the versions |
packages/dzdomop/src/omopmodel/vocab/cli.py |
CDM_VERSIONS, the choices of dzdomop load-vocab --cdm-version |
The new tag is used for the old versions too. Their DDL and docs may change with it: step 6 shows how.
3. Generate into a scratch folder¶
| Problem | Fix |
|---|---|
| A DDL script fails on Postgres | An upstream bug: add a DDL_PATCHES entry with a link to the upstream issue (OMOP policy) |
No description for ... in the log |
A table or column is missing in the CSV specs. Fine if upstream forgot it, a bug if enrich.py reads the wrong column. |
... already has a primary key, it needs no candidate key |
Upstream added a primary key: delete that candidate key |
KeyError: '<table>' from mark_candidate_keys |
The table is gone: delete its candidate key |
4. Candidate keys¶
Every table without a primary key (or with only a UNIQUE) stays a plain Table in the
declarative module:
Add a candidate key to CANDIDATE_KEYS["5.6"] for each hit: the columns that identify a row.
Generate again until grep finds nothing. The key columns become NOT NULL in the models.
5. Review names and relationships¶
Compare the new module with the previous version:
| Look for | Then |
|---|---|
A new table whose name clashes with a module name (metadata, Base, ...) |
TABLE_VARIABLE_NAMES |
New list attributes that make no sense, or new foreign keys to concept |
NO_REVERSE_RELATIONSHIPS |
Odd plural names (concept_relationship_metadatas) |
rename in generate.py, see OMOP policy |
NA or another placeholder in docstrings |
MISSING in enrich.py |
6. Generate everything and snapshot the new modules¶
uv run omop-codegen
for flavor in tables declarative dataclasses sqlmodels; do
uv run python tools/snapshot_models.py OMOP_5_6_$flavor -o tests/baseline/OMOP_5_6_$flavor.json
done
uv run python tools/baseline_diff.py --summary
The new modules match their fresh snapshots. If the release tag changed, the old versions
may differ from their baselines: add each upstream change to ALLOWED_DIFFERENCES with a
reason (Testing). Comment changes are always allowed, so
review them with git diff packages/dzdomop/src/omopmodel/. Upstream's own DDL diffs are hard
to read (statement order and case change between releases): the generated modules and the
baseline diff are easier.
7. Run the tests¶
The smoke tests pick up the new modules on their own. They insert a Person, CareSite,
Concept and Vocabulary with only the NOT NULL columns, from the test data in
tests/checks.py. If the new version adds NOT NULL columns to those tables, add
them there.
8. Docs and changelog¶
Find the places that name the versions or count them:
git grep -nE "5\.5|5_5|All three" -- ':!packages/dzdomop/src/omopmodel/OMOP_*' ':!tests/baseline' ':!uv.lock'
| File | Change |
|---|---|
README.md, packages/dzdomop/README.md |
version list, examples |
docs/index.md |
module table |
docs/models/03-pick-a-flavor.md |
version list in the intro, CDM_VERSION and CDM_RELEASE examples |
docs/models/faq.md |
the version table ("Which CDM version should I use?") and "All three are generated from ..." |
docs/generator/04-configuration.md |
defaults of OMOP_CDM_RELEASE_TAG and CDM_VERSIONS |
CHANGELOG.md |
the new modules, and every upstream change to the old versions |