id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
35731	Extend documentation about db_default and DatabaseDefault	Kyle Bebak	YashRaj1506	"I would be helpful if the existing docs at `ref/models/fields.txt`, when describing `db_default`, would mention `DatabaseDefault`.
Also, the docs `topics/db/models.txt` describe most of the `Field` options but `db_default` is missing, so ideally we would add a section for it with examples, including some that would show how and when `DatabaseDefault` is returned/used.

==== Original report ====

For example, if client code creates a model `Foo` with `val = IntegerField(db_default=10)`, does `foo = Foo()`, and accesses `foo.val`, they get an instance of `django.db.models.expressions.DatabaseDefault`.

This `DatabaseDefault` seems to be used for bookkeeping until the model instance is written to the DB, after which `foo.val` is an `int`. IMO this is not a good design, because it's a case of an implementation detail (setting a value for the field once it's saved to the DB) changing the model's public interface (IMO a model instance's field values are part of its public interface).

If instead we do `val = IntegerField()`, and `foo = Foo()`, and access `foo.val`, we get `None`, s.t. the type of `foo.val` is `int | None`. Using `db_default` means that the type of `foo.val` is now `int | DatabaseDefault`. `DatabaseDefault` is a bookkeeping type that client code usually shouldn't interact with. If users aren't aware of `db_default`'s implementation, they might still write code like this, which would be broken: `if foo.val is not None: print(foo.val + 10)`.

Because `DatabaseDefault` is for bookkeeping, it seems like there's no reason the model instance couldn't store its `DatabaseDefault` instances on a ""private"" field which wouldn't affect the model's public interface. This would be a lot cleaner IMO. Most users shouldn't know about `DatabaseDefault`, which unsurprisingly isn't mentioned here, https://docs.djangoproject.com/en/5.1/ref/models/fields/#db-default, or anywhere else in the docs AFAICT."	Cleanup/optimization	closed	Database layer (models, ORM)	dev	Normal	fixed		Kyle Bebak Simon Charette Lily Foote	Ready for checkin	1	0	0	0	0	0