Skip to content

docs: calendar factory rows in What runs where — PostgreSQL's first date, the extremes with the conversions off, Quarter's error text #450

Closed

Description

@CaffeinatedCoder

Found by a review of #191 (main PR #447 @ 879c82a, release/10.x PR #449 @ 684216b), checked on PostgreSQL 16.15 and 18.1. Docs only: the translation itself agrees with memory everywhere it was swept.

Problem

Three sentences about the calendar factories are imprecise.

  1. PostgreSQL's first date. docs/efcore.md#what-runs-where (the LocalDateRange/YearMonthRange row), the EF Core README, the four calendar entries in test/oracles/translation-support.json and NodaCalendarFactoryClientSideTests' summary say "the years before 4713 BC have no PostgreSQL date". PostgreSQL's first date is 4714-11-24 BC:

    select '4714-11-24 BC'::date;   -- 4714-11-24 BC
    select '4714-11-23 BC'::date;   -- ERROR: date out of range
    

    The wording also leads with -infinity, which suggests the cell would be fine with Npgsql.DisableDateTimeInfinityConversions set. It isn't: the month and the year that hold PostgreSQL's first day can't be built either.

    select date_trunc('month', '4714-11-24 BC'::date::timestamp);   -- ERROR: timestamp out of range
    select date_trunc('year',  '4714-12-31 BC'::date::timestamp);   -- ERROR: timestamp out of range
    

    The decision to keep the NodaTime forms in memory stands. Only its stated reason is off.

  2. The extremes. docs/efcore.md says "The first and last periods end at -infinity and infinity, as Npgsql writes DateOnly.MinValue and MaxValue". That holds only with Npgsql's infinity conversions on. With them off they are the days themselves, as the translator and CalendarFactoryExtremesTests already know. Also, the first period starts at -infinity; it doesn't end there.

  3. The error text. "PostgreSQL raises an error that names the argument". Quarter(y, 5) and Quarter(y, 0) raise make_date's own error, which names the month the quarter became:

    select make_date(9999, 5*3-2, 1);   -- ERROR: date field value out of range: 9999-13-01
    select make_date(2026, 0*3-2, 1);   -- ERROR: date field value out of range: 2026--2-01
    

Change

  • (1) Say "dates before 4714-11-24 BC, so the month and the year that hold PostgreSQL's first day have no start", and that this holds with the infinity conversions on or off. The same in all five places.
  • (2) "The first period starts at -infinity and the last ends at infinity, as Npgsql writes DateOnly.MinValue and MaxValue (the days themselves with Npgsql.DisableDateTimeInfinityConversions)." Then update E76's quote.
  • (3) Say the error names the argument or, for a quarter, the month it stands for. Or guard the quarter like the year, so its message names the quarter.

Test

Docs only. OracleCatalogueTests holds E76's quote to the reworded sentence.

Activity

  1. added this to the 10.3.0 milestone on Oct 25, 2026
  2. added
    documentationImprovements or additions to documentation
    area/rangesRange unions, variants and the shape engines
    package/efcoreAffects CodoMetis.ValueRanges.EFCore.PostgreSQL
    package/efcore-nodatimeAffects CodoMetis.ValueRanges.EFCore.PostgreSQL.NodaTime
    on Oct 25, 2026
  3. CaffeinatedCoder commented on Oct 25, 2026

    @CaffeinatedCoder
    OwnerAuthor

    Fixed in #455 (main) and #458 (release/10.x). Re-measured on PostgreSQL 16.15. One addition to the issue's point 3: make_date's error shows the date for a month and for the year 0 as well as for a quarter (make_date(0, 6, 1) → 0-06-01). Only the year and week guards name the argument, and the doc now says exactly that. Close by hand once both merge.

  4. added a commit that references this issue on Oct 25, 2026
  5. CaffeinatedCoder commented on Oct 25, 2026

    @CaffeinatedCoder
    OwnerAuthor

    Merged on both lines; #458 was the release/10.x PR. Closed by hand, since Closes acts only on main.

  6. added a commit that references this issue on Oct 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/rangesRange unions, variants and the shape enginesdocumentationImprovements or additions to documentationpackage/efcoreAffects CodoMetis.ValueRanges.EFCore.PostgreSQLpackage/efcore-nodatimeAffects CodoMetis.ValueRanges.EFCore.PostgreSQL.NodaTime

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions