|
1 | 1 | -- | |
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 | | --- = Type Categories |
11 | | --- |
12 | | --- The types are organized into the following categories: |
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' precision scale@ - Arbitrary and precise 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' limit@ - Variable-length with limit (@varchar@) |
29 | | --- * @'Char'@ - Single ASCII character (@char@) |
30 | | --- * @'Bpchar' length@ - 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' length@ - Fixed-length bit string (@bit@) |
69 | | --- * @'Varbit' limit@ - 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 (@int4range@, @int8range@, @numrange@, @tsrange@, @tstzrange@, @daterange@) |
87 | | --- * @'Multirange'@ - Generic multirange type (@int4multirange@, @int8multirange@, etc.) |
88 | | --- |
89 | | --- = Type Conversions |
90 | | --- |
91 | | --- These types do not necessarily have direct mappings to common Haskell types, |
92 | | --- but they provide explicit constructors and accessors for safe conversions. |
93 | | --- |
94 | | --- The library provides two types of constructors for each type: |
95 | | --- |
96 | | --- * __Normalizing constructors__ (prefix: @normalizeFrom*@) - Always succeed by clamping or canonicalizing input values to valid ranges |
97 | | --- * __Refining constructors__ (prefix: @refineFrom*@) - Return 'Maybe', failing if the input is out of range |
98 | | --- * __Accessor functions__ (prefix: @to*@) - Extract values from PostgreSQL types |
99 | | --- |
100 | | --- Each type also implements 'IsScalar' which provides binary and textual |
101 | | --- encoding/decoding according to PostgreSQL's wire protocol specification. |
102 | | --- |
103 | | --- = Usage Examples |
104 | | --- |
105 | | --- > import qualified Data.Text as Text |
106 | | --- > import qualified Data.Time as Time |
107 | | --- > import qualified PostgresqlTypes.Int4 as Int4 |
108 | | --- > import qualified PostgresqlTypes.Date as Date |
109 | | --- > import qualified PostgresqlTypes.Text as PgText |
110 | | --- > |
111 | | --- > -- Normalizing conversion: Int32 -> Int4 (always succeeds, clamping if needed) |
112 | | --- > pgInt :: Int4.Int4 |
113 | | --- > pgInt = Int4.normalizeFromInt32 42 |
114 | | --- > |
115 | | --- > -- Extract Int32 from Int4 |
116 | | --- > hsInt :: Int32 |
117 | | --- > hsInt = Int4.toInt32 pgInt |
118 | | --- > |
119 | | --- > -- Refining conversion: Text -> PostgreSQL Text. May fail if contains NUL-bytes. |
120 | | --- > pgTextMaybe :: Maybe PgText.Text |
121 | | --- > pgTextMaybe = PgText.refineFromText (Text.pack "Hello") |
122 | | --- > |
123 | | --- > -- Normalizing conversion which removes NUL-bytes from input |
124 | | --- > pgText :: PgText.Text |
125 | | --- > pgText = PgText.normalizeFromText (Text.pack "Hello") |
126 | | --- > |
127 | | --- > -- Normalizing conversion with clamping: Day -> Date (clamps to valid range) |
128 | | --- > pgDate :: Date.Date |
129 | | --- > pgDate = Date.normalizeFromDay (Time.fromGregorian 2024 1 15) |
130 | | --- > |
131 | | --- > -- Extract Day from Date |
132 | | --- > hsDay :: Time.Day |
133 | | --- > hsDay = Date.toDay pgDate |
134 | | --- |
135 | | --- For more information: |
136 | | --- |
137 | | --- * [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. |
138 | 3 | module PostgresqlTypes |
139 | | - ( Bit, |
140 | | - Bool, |
141 | | - Box, |
142 | | - Bpchar, |
143 | | - Bytea, |
144 | | - Char, |
145 | | - Cidr, |
146 | | - Circle, |
147 | | - Date, |
148 | | - Float4, |
149 | | - Float8, |
150 | | - Hstore, |
151 | | - Inet, |
| 4 | + ( -- * Numeric Types |
152 | 5 | Int2, |
153 | 6 | Int4, |
154 | 7 | Int8, |
155 | | - Interval, |
156 | | - Json, |
157 | | - Jsonb, |
158 | | - Line, |
159 | | - Lseg, |
160 | | - Macaddr, |
161 | | - Macaddr8, |
162 | | - Money, |
163 | | - Multirange, |
| 8 | + Float4, |
| 9 | + Float8, |
164 | 10 | Numeric, |
| 11 | + Money, |
165 | 12 | Oid, |
166 | | - Path, |
167 | | - Point, |
168 | | - Polygon, |
169 | | - Range, |
| 13 | + |
| 14 | + -- * Character Types |
170 | 15 | 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, |
171 | 28 | Time, |
172 | 29 | Timestamp, |
173 | 30 | Timestamptz, |
174 | 31 | Timetz, |
175 | | - 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, |
176 | 51 | Varbit, |
177 | | - 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, |
178 | 66 | ) |
179 | 67 | where |
180 | 68 |
|
|
0 commit comments