Comment on how range retrieval works (#655)

lib/postgrex/builtins.ex

@@ -52,6 +52,11 @@ defmodule Postgrex.Range do
   @moduledoc """
   Struct for PostgreSQL `range`.
 
+  Note that PostgreSQL itself does not return ranges exactly as stored:
+  `SELECT '(1,5)'::int4range` returns `[2,5)`, which is equivalent in terms
+  of the values included in the range ([PostgreSQL docs](https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO)).
+  When selecting data, this struct simply reflects what PostgreSQL returns.
+
   ## Fields
 
     * `lower`

test/query_test.exs

@@ -300,6 +300,9 @@ defmodule QueryTest do
 
   @tag min_pg_version: "9.2"
   test "decode range", context do
+    # These do not appear to match what is selected, but that's because
+    # PostgreSQL itself returns range values this way.
+    # `SELECT '(1,5)'::int4range` returns `[2,5)`.
     assert [[%Postgrex.Range{lower: 2, upper: 5, lower_inclusive: true, upper_inclusive: false}]] =
              query("SELECT '(1,5)'::int4range", [])