Skip to content

refactor(db): rename permission_history to site_activity_consent (BDMS-1381) - #1037

Open
ksmuczynski wants to merge 4 commits into
stagingfrom
refactor/rename-permission-history-BDMS-1381
Open

ksmuczynski wants to merge 4 commits into
stagingfrom
refactor/rename-permission-history-BDMS-1381

Conversation

@ksmuczynski

@ksmuczynski ksmuczynski commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The database now stores owner consent in site_activity_consent, with columns activity and allowed. The only table whose name still says "permission" is permission_grant, which records what staff may do. The well API, the OGC layers and OcotilloUI see no change.

Why

This PR addresses the following problem / context:

  • Once permission_grant merged, two tables used "permission" for two different things. ADR5 uses "permission" only for what staff are allowed to do, and "consent" for what a landowner allows at their site.

How

Implementation summary - the following was changed / added / removed:

  • Renamed the table, its columns and its constraints in the hand-written Alembic migration 652b0abb3241.
  • Renamed the permission_type lexicon category to site_activity and reworded its three term definitions, with data migrations for existing databases.
  • Recorded the new name in ADR5 and updated the docs.

Notes

Any special considerations, workarounds, or follow-up work to note?

  • Data migrations. After each deploy, run 20261102_0001_rename_permission_type_lexicon_category and 20261102_0002_reword_site_activity_term_definitions through the Data Migrations workflow. Until then the lexicon endpoints show the old category name and definitions. The API doesn't depend on either. .
  • Unchanged. The well response still sends permissions, permission_type and permission_allowed, and tests/test_site_activity_consent_schema.py fails if either alias is lost. Renaming those fields is a separate, staged change.

Refs BDMS-1381

ADR5 uses "permission" for what staff are allowed to do, which is what
permission_grant records. permission_history records whether a landowner
lets the Bureau measure water levels, sample water chemistry, or install
a datalogger at their site. That is consent, so the table becomes
site_activity_consent, its columns become activity and allowed, and the
model becomes SiteActivityConsent.

The lexicon category for those activities changes from permission_type
to site_activity. activity_type was the obvious name, but
permission_grant already uses it as the category for data_type.

The migration is hand-written. Alembic autogenerate would drop the old
table and create a new one, deleting every consent on record (about
7,000 on staging). The migration reads constraint names from the catalog
because PostgreSQL 18 names NOT NULL constraints and 17 does not. A
guard stops the upgrade if anything on the table still has "permission"
in its name.

The view ogc_internal_water_well_field_operations needs no changes.
PostgreSQL tracks tables by OID and columns by position, so the view
follows the rename.

The well API still sends permissions, permission_type and
permission_allowed through serialization aliases, so OcotilloUI does not
change. Renaming those fields needs a staged release and is a separate
decision.

The SiteActivity enum is built from core/lexicon.json, so the API does
not depend on the data migration that renames the category row in
existing databases. That migration overwrites the category description
even if someone edited it, because the old text describes the old
concept.

Refs BDMS-1381
ADR5 proposed field_access_consent as the table and model name, but I
chose site_activity_consent. "Field" already means a column in ADR5.
"Access" is too narrow for installing a datalogger and collides with the
lexicon's Access Status. ADR5 now uses the new name throughout, and a
dated amendment under Status explains the change.

The latest copy of the field operations view's SQL, in migration
a3b4c5d6e7f8, still uses the old table and column names. The layer doc
now warns that the next migration to rebuild the view must switch to
the new names.

Refs BDMS-1381
I edited the ERD by hand instead of regenerating it. On the current
staging branch, scripts/generate_erd.py fails on an Identity column in
an NMA legacy model before it reaches the renamed table. The committed
ERD is also missing several newer tables, so a full regeneration would
bury this change among unrelated ones.

Refs BDMS-1381
The three site_activity definitions began with "Permissions for ...".
These activities are what an owner consents to, and "permission" now
means what staff may do. One also had its words out of order:
"Permissions for water taking chemistry samples".

init_lexicon never updates an existing term's definition, so a data
migration rewrites the rows in existing databases. It only changes a
definition that still matches the old seed text, so anything edited
through /lexicon stays as it is. Data migration 20260901_0001 follows
the same rule for category descriptions.

Refs BDMS-1381
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Coverage

✅ 81.45% total — gate is 75%.

Coverage for the Python files changed in this PR
Name Stmts Miss Cover Missing
api/well_inventory.py 0 0 100%
core/enums.py 62 0 100%
data_migrations/migrations/20261102_0001_rename_permission_type_lexicon_category.py 49 49 0% 38-126
data_migrations/migrations/20261102_0002_reword_site_activity_term_definitions.py 13 13 0% 35-73
db/__init__.py 60 1 98% 85
db/api_key.py 19 1 95% 107
db/contact.py 70 0 100%
db/site_activity_consent.py 24 1 96% 79
db/thing.py 191 5 97% 504, 536, 557, 585-591
schemas/site_activity_consent.py 8 0 100%
schemas/thing.py 228 9 96% 287, 298, 323-326, 369, 374-376, 381
services/sample_helper.py 31 0 100%
services/scoped_transfer.py 823 464 44% 199, 207, 214, 221-223, 251-254, 288-293, 344-368, 373-386, 411-458, 463-465, 468-483, 486-539, 544-547, 550-608, 611-613, 618-633, 636-678, 681-683, 690-717, 720-724, 760-761, 802-803, 809-832, 837-1003, 1009-1012, 1031, 1055-1056, 1063-1065, 1069, 1078, 1146-1152, 1160-1168, 1178-1182, 1196-1201, 1209-1214, 1222-1228, 1236-1273, 1283, 1310, 1324, 1344, 1348, 1360-1369, 1377-1425, 1449-1456, 1460-1466, 1476-1549, 1559-1586, 1858-1881, 1889-1895, 1917-1924, 1941, 1969-1991
services/util.py 128 43 66% 47-56, 80, 84, 122, 125, 148-149, 187-188, 199-217, 223-238, 271, 290-296
services/well_inventory_csv.py 306 20 93% 93, 155-158, 261-264, 266-268, 309-311, 345-347, 546, 581, 819-826
TOTAL 2012 606 70%

@ksmuczynski ksmuczynski changed the title refactor/rename-permission-history-BDMS-1381 refactor(db): rename permission_history to site_activity_consent BDMS-1381 Nov 5, 2026
@ksmuczynski ksmuczynski changed the title refactor(db): rename permission_history to site_activity_consent BDMS-1381 refactor(db): rename permission_history to site_activity_consent (BDMS-1381) Nov 5, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant