Copyright | Flipstone Technology Partners 2023 |
---|---|
License | MIT |
Stability | Stable |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
This module provides functions for working with Orville FieldDefinition
values. FieldDefinition
is use to determine the column name and data type
that a Haskell field is mapped to via a
SqlMarshaller
. It is also used for constructing
boolean conditions for matching rows in queries.
Since: 1.0.0.0
Synopsis
- data FieldDefinition nullability a
- fieldName :: FieldDefinition nullability a -> FieldName
- setFieldName :: FieldName -> FieldDefinition nullability a -> FieldDefinition nullability a
- fieldDescription :: FieldDefinition nullability a -> Maybe String
- setFieldDescription :: String -> FieldDefinition nullability a -> FieldDefinition nullability a
- fieldType :: FieldDefinition nullability a -> SqlType a
- fieldIsNotNullable :: FieldDefinition nullability a -> Bool
- fieldDefaultValue :: FieldDefinition nullability a -> Maybe (DefaultValue a)
- fieldNullability :: FieldDefinition nullability a -> FieldNullability a
- fieldTableConstraints :: FieldDefinition nullability a -> TableConstraints
- addFieldTableConstraints :: [FieldName -> ConstraintDefinition] -> FieldDefinition nullability a -> FieldDefinition nullability a
- addForeignKeyConstraint :: TableIdentifier -> FieldName -> FieldDefinition nullability a -> FieldDefinition nullability a
- addForeignKeyConstraintWithOptions :: TableIdentifier -> FieldName -> ForeignKeyOptions -> FieldDefinition nullability a -> FieldDefinition nullability a
- addUniqueConstraint :: FieldDefinition nullability a -> FieldDefinition nullability a
- fieldEquals :: FieldDefinition nullability a -> a -> BooleanExpr
- (.==) :: FieldDefinition nullability a -> a -> BooleanExpr
- fieldNotEquals :: FieldDefinition nullability a -> a -> BooleanExpr
- (./=) :: FieldDefinition nullability a -> a -> BooleanExpr
- fieldGreaterThan :: FieldDefinition nullability a -> a -> BooleanExpr
- (.>) :: FieldDefinition nullability a -> a -> BooleanExpr
- fieldLessThan :: FieldDefinition nullability a -> a -> BooleanExpr
- (.<) :: FieldDefinition nullability a -> a -> BooleanExpr
- fieldGreaterThanOrEqualTo :: FieldDefinition nullability a -> a -> BooleanExpr
- (.>=) :: FieldDefinition nullability a -> a -> BooleanExpr
- fieldLessThanOrEqualTo :: FieldDefinition nullability a -> a -> BooleanExpr
- (.<=) :: FieldDefinition nullability a -> a -> BooleanExpr
- fieldIsNull :: FieldDefinition Nullable a -> BooleanExpr
- fieldIsNotNull :: FieldDefinition Nullable a -> BooleanExpr
- fieldLike :: FieldDefinition nullability a -> Text -> BooleanExpr
- fieldLikeInsensitive :: FieldDefinition nullability a -> Text -> BooleanExpr
- fieldIn :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr
- (.<-) :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr
- fieldNotIn :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr
- (.</-) :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr
- fieldTupleIn :: FieldDefinition nullabilityA a -> FieldDefinition nullabilityB b -> NonEmpty (a, b) -> BooleanExpr
- fieldTupleNotIn :: FieldDefinition nullabilityA a -> FieldDefinition nullabilityB b -> NonEmpty (a, b) -> BooleanExpr
- setField :: FieldDefinition nullability a -> a -> SetClause
- (.:=) :: FieldDefinition nullability a -> a -> SetClause
- orderByField :: FieldDefinition nullability value -> OrderByDirection -> OrderByExpr
- data FieldNullability a
- fieldValueToExpression :: FieldDefinition nullability a -> a -> ValueExpression
- fieldValueToSqlValue :: FieldDefinition nullability a -> a -> SqlValue
- fieldValueFromSqlValue :: FieldDefinition nullability a -> SqlValue -> Either String a
- fieldColumnName :: FieldDefinition nullability a -> ColumnName
- fieldColumnReference :: FieldDefinition nullability a -> ValueExpression
- fieldColumnDefinition :: FieldDefinition nullability a -> ColumnDefinition
- data FieldName
- stringToFieldName :: String -> FieldName
- fieldNameToString :: FieldName -> String
- fieldNameToColumnName :: FieldName -> ColumnName
- fieldNameToByteString :: FieldName -> ByteString
- byteStringToFieldName :: ByteString -> FieldName
- data NotNull
- data Nullable
- convertField :: (SqlType a -> SqlType b) -> FieldDefinition nullability a -> FieldDefinition nullability b
- coerceField :: (Coercible a b, Coercible b a) => FieldDefinition nullability a -> FieldDefinition nullability b
- nullableField :: FieldDefinition NotNull a -> FieldDefinition Nullable (Maybe a)
- asymmetricNullableField :: FieldDefinition Nullable a -> FieldDefinition Nullable (Maybe a)
- setDefaultValue :: DefaultValue a -> FieldDefinition nullability a -> FieldDefinition nullability a
- removeDefaultValue :: FieldDefinition nullability a -> FieldDefinition nullability a
- prefixField :: String -> FieldDefinition nullability a -> FieldDefinition nullability a
- integerField :: String -> FieldDefinition NotNull Int32
- serialField :: String -> FieldDefinition NotNull Int32
- smallIntegerField :: String -> FieldDefinition NotNull Int16
- bigIntegerField :: String -> FieldDefinition NotNull Int64
- bigSerialField :: String -> FieldDefinition NotNull Int64
- doubleField :: String -> FieldDefinition NotNull Double
- booleanField :: String -> FieldDefinition NotNull Bool
- unboundedTextField :: String -> FieldDefinition NotNull Text
- boundedTextField :: String -> Int32 -> FieldDefinition NotNull Text
- fixedTextField :: String -> Int32 -> FieldDefinition NotNull Text
- textSearchVectorField :: String -> FieldDefinition NotNull Text
- dateField :: String -> FieldDefinition NotNull Day
- utcTimestampField :: String -> FieldDefinition NotNull UTCTime
- localTimestampField :: String -> FieldDefinition NotNull LocalTime
- uuidField :: String -> FieldDefinition NotNull UUID
- jsonbField :: String -> FieldDefinition NotNull Text
- fieldOfType :: SqlType a -> String -> FieldDefinition NotNull a
- whereColumnComparison :: (ValueExpression -> ValueExpression -> BooleanExpr) -> FieldDefinition nullability a -> a -> BooleanExpr
Documentation
data FieldDefinition nullability a Source #
FieldDefinition
determines the SQL construction of a column in the
database, comprising the name, SQL type and whether the field is nullable.
A FieldDefinition
is matched to a particular Haskell type, which it knows
how to marshall to and from the database representation of SQL type for
the field.
Since: 1.0.0.0
fieldName :: FieldDefinition nullability a -> FieldName Source #
The name used in database queries to reference the field.
Since: 1.0.0.0
setFieldName :: FieldName -> FieldDefinition nullability a -> FieldDefinition nullability a Source #
Sets the name used in database queries to reference the field.
Since: 1.0.0.0
fieldDescription :: FieldDefinition nullability a -> Maybe String Source #
Returns the description that was passed to setFieldDescription
, if any.
Since: 1.0.0.0
setFieldDescription :: String -> FieldDefinition nullability a -> FieldDefinition nullability a Source #
Sets the description for the field. This description is not currently used
anywhere by Orville itself, but users can retrieve the description via
fieldDescription
for their own purposes (e.g. generating documentation).
Since: 1.0.0.0
fieldType :: FieldDefinition nullability a -> SqlType a Source #
The SqlType
for the FieldDefinition
determines the PostgreSQL
data type used to define the field as well as how to marshall Haskell values
to and from the database.
Since: 1.0.0.0
fieldIsNotNullable :: FieldDefinition nullability a -> Bool Source #
Indicates whether a field is not nullable.
Since: 1.0.0.0
fieldDefaultValue :: FieldDefinition nullability a -> Maybe (DefaultValue a) Source #
Returns the default value definition for the field, if any has been set.
Since: 1.0.0.0
fieldNullability :: FieldDefinition nullability a -> FieldNullability a Source #
Resolves the nullability
of a field to a concrete type, which is returned
via the FieldNullability
type. You can pattern match on this type to then
extract the either Nullable
or NotNull
field for cases where you may
require different logic based on the nullability of a field.
Since: 1.0.0.0
fieldTableConstraints :: FieldDefinition nullability a -> TableConstraints Source #
A list of table constraints that will be included on any table that uses this field definition.
Since: 1.0.0.0
addFieldTableConstraints :: [FieldName -> ConstraintDefinition] -> FieldDefinition nullability a -> FieldDefinition nullability a Source #
Adds the given table constraints to the field definition. These constraints
will then be included on any table where the field is used. The constraints
are passed a function that will take the name of the field definition and
construct the constraints. This allows the
ConstraintDefinition
s to use the correct name of the
field in the case where setFieldName
is used after constraints are added.
Note: If multiple constraints are added with the same
ConstraintMigrationKey
, only the last one that is added
will be part of the TableDefinition
. Any previously
added constraint with the same key is replaced by the new one.
Since: 1.0.0.0
addForeignKeyConstraint Source #
:: TableIdentifier | Identifier of the table referenced by the foreign key. |
-> FieldName | The field name that this field definition references in the foreign table. |
-> FieldDefinition nullability a | |
-> FieldDefinition nullability a |
Adds a FOREIGN KEY
constraint to the FieldDefinition
(using
addFieldTableConstraints
). This constraint will be included on any table
that uses the field definition.
Since: 1.0.0.0
addForeignKeyConstraintWithOptions Source #
:: TableIdentifier | Identifier of the table referenced by the foreign key. |
-> FieldName | The field name that this field definition references in the foreign table. |
-> ForeignKeyOptions | |
-> FieldDefinition nullability a | |
-> FieldDefinition nullability a |
Adds a FOREIGN KEY
constraint to the FieldDefinition
. This constraint
will be included on any table that uses the field definition.
Since: 1.0.0.0
addUniqueConstraint :: FieldDefinition nullability a -> FieldDefinition nullability a Source #
Adds a UNIQUE
constraint to the FieldDefinition
. This constraint
will be included on any table that uses the field definition.
Since: 1.0.0.0
fieldEquals :: FieldDefinition nullability a -> a -> BooleanExpr Source #
Checks that the value in a field equals a particular value.
Since: 1.0.0.0
(.==) :: FieldDefinition nullability a -> a -> BooleanExpr infixl 9 Source #
Operator alias for fieldEquals
.
Since: 1.0.0.0
fieldNotEquals :: FieldDefinition nullability a -> a -> BooleanExpr Source #
Checks that the value in a field does not equal a particular value.
Since: 1.0.0.0
(./=) :: FieldDefinition nullability a -> a -> BooleanExpr infixl 9 Source #
Operator alias for fieldNotEquals
.
Since: 1.0.0.0
fieldGreaterThan :: FieldDefinition nullability a -> a -> BooleanExpr Source #
Checks that the value in a field is greater than a particular value.
Since: 1.0.0.0
(.>) :: FieldDefinition nullability a -> a -> BooleanExpr infixl 9 Source #
Operator alias for fieldGreaterThan
.
Since: 1.0.0.0
fieldLessThan :: FieldDefinition nullability a -> a -> BooleanExpr Source #
Checks that the value in a field is less than a particular value.
Since: 1.0.0.0
(.<) :: FieldDefinition nullability a -> a -> BooleanExpr infixl 9 Source #
Operator alias for fieldLessThan
.
Since: 1.0.0.0
fieldGreaterThanOrEqualTo :: FieldDefinition nullability a -> a -> BooleanExpr Source #
Checks that the value in a field is greater than or equal to a particular value.
Since: 1.0.0.0
(.>=) :: FieldDefinition nullability a -> a -> BooleanExpr infixl 9 Source #
Operator alias for fieldGreaterThanOrEqualTo
.
Since: 1.0.0.0
fieldLessThanOrEqualTo :: FieldDefinition nullability a -> a -> BooleanExpr Source #
Checks that the value in a field is less than or equal to a particular value.
Since: 1.0.0.0
(.<=) :: FieldDefinition nullability a -> a -> BooleanExpr infixl 9 Source #
Operator alias for fieldLessThanOrEqualTo
.
Since: 1.0.0.0
fieldIsNull :: FieldDefinition Nullable a -> BooleanExpr Source #
Checks that the value in a field is null.
Since: 1.0.0.0
fieldIsNotNull :: FieldDefinition Nullable a -> BooleanExpr Source #
Checks that the value in a field is not null.
Since: 1.0.0.0
fieldLike :: FieldDefinition nullability a -> Text -> BooleanExpr Source #
Checks that the value in a field matches a like pattern.
Since: 1.0.0.0
fieldLikeInsensitive :: FieldDefinition nullability a -> Text -> BooleanExpr Source #
Checks that the value in a field matches a like pattern case insensitively.
Since: 1.0.0.0
fieldIn :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr Source #
Checks that a field matches a list of values.
Since: 1.0.0.0
(.<-) :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr infixl 9 Source #
Operator alias for fieldIn
.
Since: 1.0.0.0
fieldNotIn :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr Source #
Checks that a field does not match a list of values.
Since: 1.0.0.0
(.</-) :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr infixl 9 Source #
Operator alias for fieldNotIn
.
Since: 1.0.0.0
fieldTupleIn :: FieldDefinition nullabilityA a -> FieldDefinition nullabilityB b -> NonEmpty (a, b) -> BooleanExpr Source #
Checks that a tuple of two fields is in the list of specified tuples.
Since: 1.0.0.0
fieldTupleNotIn :: FieldDefinition nullabilityA a -> FieldDefinition nullabilityB b -> NonEmpty (a, b) -> BooleanExpr Source #
Checks that a tuple of two fields is not in the list of specified tuples.
Since: 1.0.0.0
setField :: FieldDefinition nullability a -> a -> SetClause Source #
Constructs a SetClause
that will set the column named in the
field definition to the given value. The value is converted to a SQL
value using fieldValueToSqlValue
.
Since: 1.0.0.0
(.:=) :: FieldDefinition nullability a -> a -> SetClause Source #
Operator alias for setField
.
Since: 1.0.0.0
orderByField :: FieldDefinition nullability value -> OrderByDirection -> OrderByExpr Source #
data FieldNullability a Source #
A FieldNullability
is returned by the fieldNullability
function, which
can be used when a function works on both Nullable
and NotNull
functions
but needs to deal with each type of field separately. It adds wrapper
constructors around the FieldDefinition
that you can pattern match on to
then work with a concrete Nullable
or NotNull
field.
Since: 1.0.0.0
fieldValueToExpression :: FieldDefinition nullability a -> a -> ValueExpression Source #
Marshalls a Haskell value to be stored in the field to its SqlValue
representation and packages the result as a ValueExpression
so that
it can be easily used with other Expr
functions.
Since: 1.0.0.0
fieldValueToSqlValue :: FieldDefinition nullability a -> a -> SqlValue Source #
Marshalls a Haskell value to be stored in the field to its SqlValue
representation.
Since: 1.0.0.0
fieldValueFromSqlValue :: FieldDefinition nullability a -> SqlValue -> Either String a Source #
fieldColumnName :: FieldDefinition nullability a -> ColumnName Source #
Constructs the ColumnName
for a field for use in SQL expressions
from the Orville.PostgreSQL.Expr module.
Since: 1.0.0.0
fieldColumnReference :: FieldDefinition nullability a -> ValueExpression Source #
Constructs the ValueExpression
for a field for use in SQL expressions
from the Orville.PostgreSQL.Expr module.
Since: 1.0.0.0
fieldColumnDefinition :: FieldDefinition nullability a -> ColumnDefinition Source #
Constructs the equivalent FieldDefinition
as a SQL expression,
generally for use in DDL for creating columns in a table.
Since: 1.0.0.0
A simple type to represent the name of a field.
Since: 1.0.0.0
stringToFieldName :: String -> FieldName Source #
fieldNameToString :: FieldName -> String Source #
fieldNameToColumnName :: FieldName -> ColumnName Source #
Convert a field name to a ColumnName
for usage in SQL expressions.
The field name will be properly quoted and escaped.
Since: 1.0.0.0
fieldNameToByteString :: FieldName -> ByteString Source #
Converts a FieldName
back to a ByteString
.
Since: 1.0.0.0
byteStringToFieldName :: ByteString -> FieldName Source #
Constructs a FieldName
from a ByteString
.
Since: 1.0.0.0
NotNull
is a valueless type used to track that a FieldDefinition
represents a field that is marked not-null in the database schema. See the
FieldNullability
type for the value-level representation of field nullability.
Since: 1.0.0.0
Nullable
is a valueless type used to track that a FieldDefinition
represents a field that is marked nullable in the database schema. See the
FieldNullability
type for the value-level representation of field nullability.
Since: 1.0.0.0
convertField :: (SqlType a -> SqlType b) -> FieldDefinition nullability a -> FieldDefinition nullability b Source #
Applies a SqlType
conversion to a FieldDefinition
. You can
use this function to create FieldDefinition
s based on the primitive ones
provided, but with more specific Haskell types.
See convertSqlType
and tryConvertSqlType
for functions
to create the conversion needed as the first argument to convertField
.
Since: 1.0.0.0
coerceField :: (Coercible a b, Coercible b a) => FieldDefinition nullability a -> FieldDefinition nullability b Source #
A specialization of convertField
that can be used with types that implement
Coercible
. This is particularly useful for newtype wrappers around
primitive types.
Since: 1.0.0.0
nullableField :: FieldDefinition NotNull a -> FieldDefinition Nullable (Maybe a) Source #
asymmetricNullableField :: FieldDefinition Nullable a -> FieldDefinition Nullable (Maybe a) Source #
Adds a Maybe
wrapper to a field that is already nullable. (If your field is
NotNull
, you wanted nullableField
instead of this function). Note that
fields created using this function have asymmetric encoding and decoding of
NULL
values. Because the provided field is Nullable
, NULL
values decoded
from the database already have a representation in the a
type, so NULL
will be decoded as 'Just of type a for NULL'. This means if you
insert a Nothing
value using the field, it will be read back as Just
value. This is useful for building high level combinators that might need to
make fields Nullable
but need the value to be decoded in its underlying
type when reading back (e.g. maybeMapper
from
Orville.PostgreSQL.Marshall.SqlMarshaller).
Since: 1.0.0.0
setDefaultValue :: DefaultValue a -> FieldDefinition nullability a -> FieldDefinition nullability a Source #
Sets a default value for the field. The default value will be added as part of the column definition in the database. Because the default value is ultimately provided by the database, this can be used to add a not-null column safely to an existing table as long as a reasonable default value is available to use.
Since: 1.0.0.0
removeDefaultValue :: FieldDefinition nullability a -> FieldDefinition nullability a Source #
Removes any default value that may have been set on a field via
setDefaultValue
.
Since: 1.0.0.0
prefixField :: String -> FieldDefinition nullability a -> FieldDefinition nullability a Source #
Adds a prefix, followed by an underscore, to a field's name.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Int32 |
Builds a FieldDefinition
that stores Haskell Int32
values as the
PostgreSQL INT type.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Int32 |
Builds a FieldDefinition
that stores an Int32
value as the SERIAL
type. This can be used to create auto-incrementing columns.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Int16 |
Builds a FieldDefinition
that stores Haskell Int16
values as the
PostgreSQL SMALLINT type.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Int64 |
Builds a FieldDefinition
that stores Haskell Int64
values as the
PostgreSQL BIGINT type.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Int64 |
Builds a FieldDefinition
that stores an Int64
value as the BIGSERIAL
type. This can be used to create auto-incrementing columns.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Double |
Builds a FieldDefinition
that stores a Double
value as the "DOUBLE
PRECISION" type. Note: PostgreSQL's "DOUBLE PRECISION" type only allows for
up to 15 digits of precision, so some rounding may occur when values are
stored in the database.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Bool |
Builds a FieldDefinition
that stores Haskell Bool
values as the
PostgreSQL BOOLEAN type.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Text |
Builds a FieldDefinition
that stores Haskell Text
values as the
PostgreSQL TEXT type. Note that this PostgreSQL has no particular
limit on the length of text stored.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> Int32 | Maximum length of text in the field. |
-> FieldDefinition NotNull Text |
Builds a FieldDefinition
that stores Haskell Text
values as the
PostgreSQL VARCHAR type. Attempting to store a value beyond the length
specified will cause an error.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> Int32 | Maximum length of text in the field. |
-> FieldDefinition NotNull Text |
Builds a FieldDefinition
that stores Haskell Text
values as the
PostgreSQL CHAR type. Attempting to store a value beyond the length
specified will cause an error. Storing a value that is not the full
length of the field will result in padding by the database.
Since: 1.0.0.0
textSearchVectorField :: String -> FieldDefinition NotNull Text Source #
Builds a FieldDefinition
that stores PostgreSQL text search vector values.
The values are represented as Haskell Text
values, but are interpreted as
text search vector values by PostgreSQL when passed to it.
See https://www.postgresql.org/docs/current/datatype-textsearch.html for
information about how PostgreSQL creates tsvector
values from strings.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull Day |
Builds a FieldDefinition
that stores Haskell Day
values as the
PostgreSQL DATE type.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull UTCTime |
Builds a FieldDefinition
that stores Haskell UTCTime
values as the
PostgreSQL "TIMESTAMP with time zone" type.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull LocalTime |
Builds a FieldDefinition
that stores Haskell UTCTime
values as the
PostgreSQL "TIMESTAMP without time zone" type.
Since: 1.0.0.0
:: String | Name of the field in the database. |
-> FieldDefinition NotNull UUID |
Builds a FieldDefinition
that stores Haskell UUID
values as the
PostgreSQL UUID type.
Since: 1.0.0.0
jsonbField :: String -> FieldDefinition NotNull Text Source #
Builds a FieldDefinition
that stores Haskell Text
values as the
PostgreSQL JSONB type.
Since: 1.0.0.0
:: SqlType a |
|
-> String | Name of the field in the database. |
-> FieldDefinition NotNull a |
Builds a FieldDefinition
that will use the given SqlType
to
determine the database representation of the field. If you have created a
custom SqlType
, you can use this function to construct a helper
like the other functions in this module for creating FieldDefinition
s for
your custom type.
Since: 1.0.0.0
whereColumnComparison :: (ValueExpression -> ValueExpression -> BooleanExpr) -> FieldDefinition nullability a -> a -> BooleanExpr Source #
Constructs a field-based BooleanExpr
using a function that
builds a BooleanExpr
.
Since: 1.0.0.0