`inet` docs suggestion and possible bug report

From: Nathan Long <hello(at)nathanmlong(dot)com>
To: pgsql-docs(at)lists(dot)postgresql(dot)org
Subject: `inet` docs suggestion and possible bug report
Date: 2025-04-28 15:07:21
Message-ID: CAOyE-6bxoq4N4ZaPJSoyKvTF6EWB0-57sJfMap4EXzM=47K_jQ@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

On https://www.postgresql.org/docs/current/datatype-net-types.html the
opening paragraph says:

> PostgreSQL offers data types to store IPv4, IPv6, and MAC addresses, as
shown in Table 8.21
<https://www.postgresql.org/docs/current/datatype-net-types.html#DATATYPE-NET-TYPES-TABLE>.
It is better to use these types instead of plain text types to store
network addresses, because these types offer input error checking and
specialized operators and functions (see Section 9.12
<https://www.postgresql.org/docs/current/functions-net.html>).

At least in the case of `inet`, another reason is for accurate comparison.
IPv4 and IPv6 both have shorthand textual representations; eg `127.1` =
`127.1.0.0`. Text storage would consider these unequal.

I propose modifying the leading paragraph to say:

> PostgreSQL offers data types to store IPv4, IPv6, and MAC addresses, as
shown in Table 8.21
<https://www.postgresql.org/docs/current/datatype-net-types.html#DATATYPE-NET-TYPES-TABLE>.
It is better to use these types instead of plain text types to store
network addresses, because these types offer input error checking,
**accurate comparison,** and specialized operators and functions (see
Section 9.12 <https://www.postgresql.org/docs/current/functions-net.html>).

and appending a sentence to `8.9.1 inet` as follows:

> Because it stores an address in its canonical format, inet provides
reliable comparison between addresses. Both IPv4 and IPv6 have shorthand
formats which would compare as unequal if stored as plain text; for
example, `SELECT '127.1' = '127.1.0.0';` returns false, but `SELECT
'::ffff:127.0.0.1'::inet = '::ffff:127.1'::inet;` returns true.

A possible bug report: As of I expected `SELECT '127.1'::inet =
'127.0.0.1'::inet;` to return true, but as of 16.6 the cast on the
shorthand format fails, even though it handles the IPV6-mapped equivalent.

-- Nathan

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Tom Lane 2025-04-28 20:28:57 Re: `inet` docs suggestion and possible bug report
Previous Message PG Doc comments form 2025-04-25 07:21:22 Data visibility for returning statement