Skip to content

Commit 214bbb4

Browse files
nikita-volkovnikita-volkov
committed
Update the docs
1 parent ce89459 commit 214bbb4

File tree

2 files changed

+57
-178
lines changed

2 files changed

+57
-178
lines changed

‎postgresql-types.cabal‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,15 @@ category: PostgreSQL, Codecs
55
synopsis: Precise PostgreSQL types representation and driver-agnostic codecs
66
description:
77
Haskell representation of PostgreSQL data types with mappings to and from both
8-
binary and textual formats of the PostgreSQL wire protocol.
8+
binary and textual formats of the PostgreSQL wire protocol. The types are implemented in their canonical forms that directly correspond to their PostgreSQL counterparts. The philosophy is that nuance matters. So all special values are represented without data loss or compromise.
99

10-
This library is about precision. It aims to reproduce the PostgreSQL type system as closely as possible.
10+
The types presented by this package do not necessarily have direct mappings to the common Haskell types. Canonicalizing conversions and smart constructors are provided to address that.
1111

12-
Types are represented with hidden constructors, ensuring only valid PostgreSQL
13-
values can be constructed. Conversions use explicit normalizing and refining constructors for
14-
safe, well-defined transformations. Exhaustively tested against PostgreSQL 9-18
15-
with property-based testing covering the complete range of valid PostgreSQL values.
12+
E.g., any @text@ value from PostgreSQL makes valid 'Data.Text.Text' values in Haskell, but not every Haskell 'Data.Text.Text` value makes valid PostgreSQL @text@, because PostgreSQL does not allow NUL-bytes in text fields, but Haskell's 'Data.Text.Text' does. In case of dates the supported date ranges may differ between PostgreSQL and Haskell's \"time\" library. Therefore, conversions between these types and common Haskell types may be partial and may fail if the data cannot be represented in the target type.
1613

17-
The library can be used as the basis for various PostgreSQL libraries.
14+
All of the types supply 'Test.QuickCheck.Arbitrary' instances that cover the full range of valid PostgreSQL values. Every type is property-tested to validate round-trip conversions between binary and textual formats against PostgreSQL of version 9 to 18.
1815

19-
Ecosystem integration adapters are available for:
16+
The library can be used as the basis for various PostgreSQL libraries. Ecosystem integration adapters are available for:
2017

2118
* hasql: <https://hackage-content.haskell.org/package/hasql-postgresql-types>
2219

‎src/library/PostgresqlTypes.hs‎

Lines changed: 52 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -1,186 +1,68 @@
11
-- |
2-
-- Haskell representations of PostgreSQL data structures in their canonical forms that directly correspond to their PostgreSQL definitions. No data loss, no compromise!
3-
--
4-
-- The philosophy behind this package is that nuance matters. PostgreSQL has a rich type system with many types that have subtle differences in their behavior and representation. This package aims to provide Haskell types that accurately reflect these PostgreSQL types, preserving their semantics and constraints.
5-
--
6-
-- These types do not necessarily have direct mappings to the common Haskell types. Canonicalizing conversions and smart constructors are provided to address that.
7-
--
8-
-- E.g., any @text@ value from PostgreSQL makes valid 'Data.Text.Text' values in Haskell, but not every Haskell 'Data.Text.Text` value makes valid PostgreSQL @text@, because PostgreSQL does not allow NUL-bytes in text fields, but Haskell's 'Data.Text.Text' does. In case of dates the supported date ranges may differ between PostgreSQL and Haskell's \"time\" library. Therefore, conversions between these types and common Haskell types may be partial and may fail if the data cannot be represented in the target type.
9-
--
10-
-- = Supported Types
11-
--
12-
-- This package provides support for nearly all PostgreSQL data types, organized by category:
13-
--
14-
-- == Numeric Types
15-
--
16-
-- * @'Int2'@ - 2-byte signed integer (@int2@ \/ @smallint@)
17-
-- * @'Int4'@ - 4-byte signed integer (@int4@ \/ @integer@)
18-
-- * @'Int8'@ - 8-byte signed integer (@int8@ \/ @bigint@)
19-
-- * @'Float4'@ - Single-precision floating point (@float4@ \/ @real@)
20-
-- * @'Float8'@ - Double-precision floating point (@float8@ \/ @double precision@)
21-
-- * @'Numeric'@ - Arbitrary precision numeric (@numeric@ \/ @decimal@)
22-
-- * @'Money'@ - Currency amount (@money@)
23-
-- * @'Oid'@ - Object identifier (@oid@)
24-
--
25-
-- == Character Types
26-
--
27-
-- * @'Text'@ - Variable-length character string (@text@)
28-
-- * @'Varchar'@ - Variable-length with limit (@varchar@)
29-
-- * @'Char'@ - Single ASCII character (@char@)
30-
-- * @'Bpchar'@ - Fixed-length character string (@char(n)@, @character(n)@, or @bpchar(n)@)
31-
--
32-
-- == Boolean Type
33-
--
34-
-- * @'Bool'@ - Boolean (@bool@)
35-
--
36-
-- == Binary Data
37-
--
38-
-- * @'Bytea'@ - Binary data (@bytea@)
39-
--
40-
-- == Date\/Time Types
41-
--
42-
-- * @'Date'@ - Calendar date (@date@)
43-
-- * @'Time'@ - Time of day without time zone (@time@)
44-
-- * @'Timestamp'@ - Date and time without time zone (@timestamp@)
45-
-- * @'Timestamptz'@ - Date and time with time zone (@timestamptz@)
46-
-- * @'Timetz'@ - Time of day with time zone (@timetz@)
47-
-- * @'Interval'@ - Time interval (@interval@)
48-
--
49-
-- == Network Address Types
50-
--
51-
-- * @'Inet'@ - IPv4 or IPv6 host address (@inet@)
52-
-- * @'Cidr'@ - IPv4 or IPv6 network address (@cidr@)
53-
-- * @'Macaddr'@ - MAC address (@macaddr@)
54-
-- * @'Macaddr8'@ - MAC address (EUI-64 format) (@macaddr8@)
55-
--
56-
-- == Geometric Types
57-
--
58-
-- * @'Point'@ - Point on a plane (@point@)
59-
-- * @'Line'@ - Infinite line (@line@)
60-
-- * @'Lseg'@ - Line segment (@lseg@)
61-
-- * @'Box'@ - Rectangular box (@box@)
62-
-- * @'Path'@ - Geometric path (@path@)
63-
-- * @'Polygon'@ - Closed geometric path (@polygon@)
64-
-- * @'Circle'@ - Circle (@circle@)
65-
--
66-
-- == Bit String Types
67-
--
68-
-- * @'Bit'@ - Fixed-length bit string (@bit@)
69-
-- * @'Varbit'@ - Variable-length bit string (@varbit@)
70-
--
71-
-- == UUID Type
72-
--
73-
-- * @'Uuid'@ - Universally unique identifier (@uuid@)
74-
--
75-
-- == JSON Types
76-
--
77-
-- * @'Json'@ - JSON data (@json@)
78-
-- * @'Jsonb'@ - Binary JSON data (@jsonb@)
79-
--
80-
-- == Key-Value Types
81-
--
82-
-- * @'Hstore'@ - Key-value store (@hstore@)
83-
--
84-
-- == Range Types
85-
--
86-
-- * @'Range'@ - Generic range type supporting int4range, int8range, numrange, tsrange, tstzrange, daterange
87-
-- * @'Multirange'@ - Generic multirange type supporting int4multirange, int8multirange, etc.
88-
--
89-
-- == Array Types
90-
--
91-
-- Array types are available for all of the above types.
92-
--
93-
-- = Function Naming Conventions
94-
--
95-
-- These types do not necessarily have direct mappings to common Haskell types,
96-
-- but they provide explicit constructors and accessors for safe conversions.
97-
--
98-
-- The library provides three types of functions for working with PostgreSQL types:
99-
--
100-
-- * __Normalizing constructors__ (prefix: @normalizeFrom*@) - Always succeed by clamping or canonicalizing input values to valid ranges. Use these when you want to ensure a value is valid by transforming invalid inputs into valid ones (e.g., removing NUL bytes from text, clamping dates to PostgreSQL's supported range).
101-
--
102-
-- * __Refining constructors__ (prefix: @refineFrom*@) - Return 'Maybe', failing if the input is out of range or invalid. Use these when you want to validate that input data is already within valid PostgreSQL constraints.
103-
--
104-
-- * __Accessor functions__ (prefix: @to*@) - Extract values from PostgreSQL types to common Haskell types. These conversions are always safe and total.
105-
--
106-
-- Each type module also implements 'IsScalar' which provides binary and textual
107-
-- encoding/decoding according to PostgreSQL's wire protocol specification.
108-
--
109-
-- = Usage Examples
110-
--
111-
-- > import qualified Data.Text as Text
112-
-- > import qualified Data.Time as Time
113-
-- > import qualified PostgresqlTypes.Int4 as Int4
114-
-- > import qualified PostgresqlTypes.Date as Date
115-
-- > import qualified PostgresqlTypes.Text as PgText
116-
-- >
117-
-- > -- Normalizing conversion: Int32 -> Int4 (always succeeds, clamping if needed)
118-
-- > pgInt :: Int4.Int4
119-
-- > pgInt = Int4.normalizeFromInt32 42
120-
-- >
121-
-- > -- Extract Int32 from Int4
122-
-- > hsInt :: Int32
123-
-- > hsInt = Int4.toInt32 pgInt
124-
-- >
125-
-- > -- Refining conversion: Text -> PostgreSQL Text. May fail if contains NUL-bytes.
126-
-- > pgTextMaybe :: Maybe PgText.Text
127-
-- > pgTextMaybe = PgText.refineFromText (Text.pack "Hello")
128-
-- >
129-
-- > -- Normalizing conversion which removes NUL-bytes from input
130-
-- > pgText :: PgText.Text
131-
-- > pgText = PgText.normalizeFromText (Text.pack "Hello")
132-
-- >
133-
-- > -- Normalizing conversion with clamping: Day -> Date (clamps to valid range)
134-
-- > pgDate :: Date.Date
135-
-- > pgDate = Date.normalizeFromDay (Time.fromGregorian 2024 1 15)
136-
-- >
137-
-- > -- Extract Day from Date
138-
-- > hsDay :: Time.Day
139-
-- > hsDay = Date.toDay pgDate
140-
--
141-
-- For more information:
142-
--
143-
-- * [PostgreSQL type documentation](https://www.postgresql.org/docs/current/datatype.html)
2+
-- This module re-exports all PostgreSQL types defined in this package. No constructors. No functions.
1443
module PostgresqlTypes
145-
( Bit,
146-
Bool,
147-
Box,
148-
Bpchar,
149-
Bytea,
150-
Char,
151-
Cidr,
152-
Circle,
153-
Date,
154-
Float4,
155-
Float8,
156-
Hstore,
157-
Inet,
4+
( -- * Numeric Types
1585
Int2,
1596
Int4,
1607
Int8,
161-
Interval,
162-
Json,
163-
Jsonb,
164-
Line,
165-
Lseg,
166-
Macaddr,
167-
Macaddr8,
168-
Money,
169-
Multirange,
8+
Float4,
9+
Float8,
17010
Numeric,
11+
Money,
17112
Oid,
172-
Path,
173-
Point,
174-
Polygon,
175-
Range,
13+
14+
-- * Character Types
17615
Text,
16+
Varchar,
17+
Char,
18+
Bpchar,
19+
20+
-- * Boolean Type
21+
Bool,
22+
23+
-- * Binary Data
24+
Bytea,
25+
26+
-- * Date\/Time Types
27+
Date,
17728
Time,
17829
Timestamp,
17930
Timestamptz,
18031
Timetz,
181-
Uuid,
32+
Interval,
33+
34+
-- * Network Address Types
35+
Inet,
36+
Cidr,
37+
Macaddr,
38+
Macaddr8,
39+
40+
-- * Geometric Types
41+
Point,
42+
Line,
43+
Lseg,
44+
Box,
45+
Path,
46+
Polygon,
47+
Circle,
48+
49+
-- * Bit String Types
50+
Bit,
18251
Varbit,
183-
Varchar,
52+
53+
-- * UUID Type
54+
Uuid,
55+
56+
-- * JSON Types
57+
Json,
58+
Jsonb,
59+
60+
-- * Key-Value Types
61+
Hstore,
62+
63+
-- * Range Types
64+
Range,
65+
Multirange,
18466
)
18567
where
18668

0 commit comments

Comments
 (0)