ipam/v1-to-v2-breaking-changes.md

v1 → v2 Breaking Changes

This document lists breaking changes when upgrading from IPAM v1.x to v2.0.

Upgrade steps: pull/deploy the v2 image or code, restart the application. Database migrations run automatically on startup via init_db(). No manual SQL is required for standard upgrades.

---

Removed features

Feature	v1	v2
Response caching / rate limiting	Flask-Limiter + in-app cache layer	Removed — direct DB queries
In-app update checker	/check_update + header toast	Removed — check releases yourself
Feature flags	Admin toggles for racks, tags, IP notes, bulk ops	Removed — features always available, gated by permissions only
Backup & restore	Admin UI + /backup/* routes	Removed — use your own DB backup strategy
Help page	/help	Removed
Interactive API docs	/api-docs web page	Removed — see API.md
Custom field “searchable” flag	UI checkbox + DB column	Removed — was never wired to search
Device types	Device type CRUD, device_type_id on devices, rack placement filters	Removed — devices are untyped; use tags or custom fields instead

Dependencies removed

• requests (update checker)
• Flask-Limiter and the custom cache module (already gone in v2 prep)

---

Removed routes

Method	v1 path	Notes
GET	/check_update	Update checker
GET/POST	/backup, /backup/create, /backup/download/<file>, /backup/restore, /backup/delete/<file>	Backup UI
GET	/help	Help page
GET	/api-docs	Swagger-style docs
GET/POST	/admin/feature_flags	Feature flag toggles
GET	/custom_fields/<entity_type>	Duplicate of API; use /api/v1/custom_fields/{entity_type}
GET	/api/device/<id>/ip_history	Moved — see below
GET	/api/ip/<ip>/history	Moved — see below
GET/POST/PUT/DELETE	/api/v1/device-types, /api/v2/device-types	Device types removed

---

API changes

v2 is API-only + Vue SPA

v2 removes all Jinja/HTML routes. The UI is a Vue 3 SPA served from static/dist/. All functionality goes through /api/v2/*.

v1	v2
/api/v1/*	/api/v2/* (v1 removed)
Session via HTML login forms	POST /api/v2/auth/login + session cookie
API key only on API routes	Same routes accept session cookie or API key
{ "devices": [...] } list responses	{ "items": [...] } for all list endpoints
{ "tags" }, { "users" }, { "roles" }, { "racks" }, { "logs" }, { "fields" } wrappers	{ "items" } (audit also includes total; devices-by-tag includes meta)

Version

GET /api/v2/info reports "api_version": "2.0".

IP history endpoints

v1 (removed)	v2 replacement	Auth
GET /api/device/<id>/ip_history	GET /api/v2/devices/<id>/ip-history	Session or API key
GET /api/ip/<ip>/history	GET /api/v2/ips/<ip>/history	Session or API key

Audit logging for API calls

v1 logged every API request (including GETs) to the audit log as api_usage.

v2 logs mutating requests only: POST, PUT, DELETE, PATCH. GET traffic is no longer audited. If you relied on GET audit entries for compliance, adjust your monitoring.

---

Database migrations (automatic)

On startup, v2 runs these migrations against existing databases:

1. Drop FeatureFlags table — feature flags removed
2. Drop CustomFieldDefinition.searchable column — if present
3. Remove orphaned permission view_help — help page removed
4. Drop Device.device_type_id column and DeviceType table — device types removed
5. Remove device-type permissions — view_device_types, add_device_type, etc.

No data loss for core IPAM entities (subnets, IPs, devices, racks, tags, users, audit log). Device type labels are not migrated; use tags or custom fields if you need classification.

---

Permissions & sessions

• view_help permission is removed from the database on upgrade.
• Device-type permissions (view_device_types, add_device_type, etc.) are removed on upgrade.
• Feature-flag toggles no longer hide UI; use roles and permissions instead.
• Permissions are cached in the session at login. If an admin changes a user's role, that user must log out and back in for permission changes to take effect.

---

Configuration

No new required environment variables. Removed features did not introduce new config keys.

Docker images no longer need a /backups volume mount for in-app backup (remove if you added it only for IPAM backup).

---

Codebase layout (operators / fork maintainers)

v1	v2
app.py + routes.py + cache.py + totp_utils.py	Single app.py + db.py
templates/, legacy static/js	Deleted — replaced by frontend/ → static/dist/
Server-rendered Tailwind	Vue 3 + Vite + Tailwind (auto light/dark, cyan accents)

---

Recommended pre-upgrade checklist

1. Back up your MariaDB/MySQL database using your normal tooling (mysqldump, volume snapshot, etc.).
2. Note any integrations using removed routes (update checker, backup API, legacy IP history paths).
3. Deploy v2 and restart the container/process once.
4. Verify login, home page, devices, and one API call with your API key.
5. Have affected users re-login if roles were changed recently.

---

Questions

For API reference after upgrade, see API.md.