ADR 0002 — Convert only exact values, and keep a stand-in field for migration history#

Status: accepted

Decision#

Moving a column from django-partial-date rests on two rules.

A value converts only if it is exactly what django-partial-date writes. That is a timestamp at 00:00:00 on 1 January (year), 00:00:01 on the first of a month (month) or 00:00:02 on any date (day), in the years 0001 to 9999, read in the time zone of the database connection. An empty value stays empty. ConvertPartialDateField checks every value before it changes anything. Any other value stops the migration with RefusedValuesError, and the column and its rows stay as they were. The same holds on PostgreSQL and SQLite.

Existing migrations point at OldPartialDateField, never at PartialDateField. It is a field that describes the old column. It stays in the package for good, because a project’s migration history refers to it after the project has uninstalled django-partial-date.

Why#

What to do with a value that does not fit#

Goal G5 says a move loses no data. Three treatments of a value that does not fit were weighed.

Option

Result

Convert to what django-partial-date displays

Rejected. 1990-06-14 00:00:00 displays as 1990, because its precision setter never clears the month and the day. Converting destroys a day the column holds, and a developer may need it.

Skip the value and report it

Rejected. The column then cannot take the check ADR 0001 requires, and a report is easy to miss in a deployment.

Stop the migration

Chosen. Nothing is lost, and the developer is the only one who can say what the value meant.

What django-partial-date displays is not evidence of what was recorded, so a value it reads without complaint is still refused if it holds more than the ISO form can carry. A refused migration changes nothing, so applying it to a copy of the data is also how a project checks its data.

The time zone follows from the same rule. django-partial-date writes a naive timestamp, so the database reads it in the connection’s zone, and it reads it back the same way. A project whose settings changed after the rows were written has values that no longer fall on the three stored times. They are refused, instead of converted a day out.

What existing migrations point at#

Option

Result

Point them at PartialDateField

Rejected. The migrations would claim a text column while a deployed database holds a timestamp. On a database behind the latest migration, any pending change that makes SQLite rebuild the table creates the text column with its check, and copying the old values fails. A data migration reading the column fails too.

Keep a field describing the old column

Chosen. History stays true, so a new database and a deployed one take the same path and differ only in holding rows. Django’s own documentation recommends keeping a field class that historical migrations reference.

The stand-in reports CharField from get_internal_type(), which does not match its column, on purpose. Without that, a generated AlterField left in the migration casts the timestamps to varchar(10) on PostgreSQL, which truncates them silently, and the check accepts the result: 1990 becomes 1990-01-01. With it, PostgreSQL raises an error.

Revisit if#

  • A project has to move a table it cannot stop writing to. The check runs before the column changes, and a row written between the two is not checked.

  • django-partial-date is no longer in use anywhere. The stand-in stays for as long as any project’s migration history names it.