Orville.PostgreSQL.Marshall.FieldDefinition

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

Documentation

data FieldDefinition nullability a

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

The name used in database queries to reference the field.

Since: 1.0.0.0

setFieldName :: FieldName -> FieldDefinition nullability a -> FieldDefinition nullability a

Sets the name used in database queries to reference the field.

Since: 1.0.0.0

fieldDescription :: FieldDefinition nullability a -> Maybe String

Returns the description that was passed to setFieldDescription, if any.

Since: 1.0.0.0

setFieldDescription :: String -> FieldDefinition nullability a -> FieldDefinition nullability a

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

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

Indicates whether a field is not nullable.

Since: 1.0.0.0

fieldDefaultValue :: FieldDefinition nullability a -> Maybe (DefaultValue a)

Returns the default value definition for the field, if any has been set.

Since: 1.0.0.0

fieldNullability :: FieldDefinition nullability a -> FieldNullability a

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

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

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 ConstraintDefinitions 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

Arguments

:: 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

Arguments

:: 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

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

Checks that the value in a field equals a particular value.

Since: 1.0.0.0

(.==) :: FieldDefinition nullability a -> a -> BooleanExpr infixl 9

Operator alias for fieldEquals.

Since: 1.0.0.0

fieldNotEquals :: FieldDefinition nullability a -> a -> BooleanExpr

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

Operator alias for fieldNotEquals.

Since: 1.0.0.0

fieldGreaterThan :: FieldDefinition nullability a -> a -> BooleanExpr

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

Operator alias for fieldGreaterThan.

Since: 1.0.0.0

fieldLessThan :: FieldDefinition nullability a -> a -> BooleanExpr

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

Operator alias for fieldLessThan.

Since: 1.0.0.0

fieldGreaterThanOrEqualTo :: FieldDefinition nullability a -> a -> BooleanExpr

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

Operator alias for fieldGreaterThanOrEqualTo.

Since: 1.0.0.0

fieldLessThanOrEqualTo :: FieldDefinition nullability a -> a -> BooleanExpr

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

Operator alias for fieldLessThanOrEqualTo.

Since: 1.0.0.0

fieldIsNull :: FieldDefinition Nullable a -> BooleanExpr

Checks that the value in a field is null.

Since: 1.0.0.0

fieldIsNotNull :: FieldDefinition Nullable a -> BooleanExpr

Checks that the value in a field is not null.

Since: 1.0.0.0

fieldLike :: FieldDefinition nullability a -> Text -> BooleanExpr

Checks that the value in a field matches a like pattern.

Since: 1.0.0.0

fieldLikeInsensitive :: FieldDefinition nullability a -> Text -> BooleanExpr

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

Checks that a field matches a list of values.

Since: 1.0.0.0

(.<-) :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr infixl 9

Operator alias for fieldIn.

Since: 1.0.0.0

fieldNotIn :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr

Checks that a field does not match a list of values.

Since: 1.0.0.0

(.</-) :: FieldDefinition nullability a -> NonEmpty a -> BooleanExpr infixl 9

Operator alias for fieldNotIn.

Since: 1.0.0.0

fieldTupleIn :: FieldDefinition nullabilityA a -> FieldDefinition nullabilityB b -> NonEmpty (a, b) -> BooleanExpr

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

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

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

Operator alias for setField.

Since: 1.0.0.0

orderByField :: FieldDefinition nullability value -> OrderByDirection -> OrderByExpr

data FieldNullability a

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

Constructors

NullableField (FieldDefinition Nullable a)

NotNullField (FieldDefinition NotNull a)

fieldValueToExpression :: FieldDefinition nullability a -> a -> ValueExpression

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

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

Marshalls a SqlValue from the database into the Haskell value that represents it. This may fail, in which case a Left is returned with an error message.

Since: 1.0.0.0

fieldColumnName :: FieldDefinition nullability a -> ColumnName

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

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

Constructs the equivalent FieldDefinition as a SQL expression, generally for use in DDL for creating columns in a table.

Since: 1.0.0.0

data FieldName

A simple type to represent the name of a field.

Since: 1.0.0.0

Instances

Show FieldName

Defined in Orville.PostgreSQL.Internal.FieldName

Methods

showsPrec :: Int -> FieldName -> ShowS

show :: FieldName -> String

showList :: [FieldName] -> ShowS

Eq FieldName

Defined in Orville.PostgreSQL.Internal.FieldName

Methods

(==) :: FieldName -> FieldName -> Bool

(/=) :: FieldName -> FieldName -> Bool

Ord FieldName

Defined in Orville.PostgreSQL.Internal.FieldName

Methods

compare :: FieldName -> FieldName -> Ordering

(<) :: FieldName -> FieldName -> Bool

(<=) :: FieldName -> FieldName -> Bool

(>) :: FieldName -> FieldName -> Bool

(>=) :: FieldName -> FieldName -> Bool

max :: FieldName -> FieldName -> FieldName

min :: FieldName -> FieldName -> FieldName

stringToFieldName :: String -> FieldName

Constructs a FieldName from a String.

Since: 1.0.0.0

fieldNameToString :: FieldName -> String

Converts a FieldName back to a String.

Since: 1.0.0.0

fieldNameToColumnName :: FieldName -> ColumnName

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

Converts a FieldName back to a ByteString.

Since: 1.0.0.0

byteStringToFieldName :: ByteString -> FieldName

Constructs a FieldName from a ByteString.

Since: 1.0.0.0

data NotNull

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

data Nullable

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

Applies a SqlType conversion to a FieldDefinition. You can use this function to create FieldDefinitions 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

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)

Makes a NotNull field Nullable by wrapping the Haskell type of the field in Maybe. The field will be marked as NULL in the database schema and the value Nothing will be used to represent NULL values when converting to and from SQL.

Since: 1.0.0.0

asymmetricNullableField :: FieldDefinition Nullable a -> FieldDefinition Nullable (Maybe a)

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

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

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

Adds a prefix, followed by an underscore, to a field's name.

Since: 1.0.0.0

integerField

Arguments

:: 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

serialField

Arguments

:: 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

smallIntegerField

Arguments

:: 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

bigIntegerField

Arguments

:: 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

bigSerialField

Arguments

:: 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

doubleField

Arguments

:: 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

booleanField

Arguments

:: 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

unboundedTextField

Arguments

:: 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

boundedTextField

Arguments

:: 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

fixedTextField

Arguments

:: 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

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

dateField

Arguments

:: 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

utcTimestampField

Arguments

:: 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

localTimestampField

Arguments

:: 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

uuidField

Arguments

:: 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

Builds a FieldDefinition that stores Haskell Text values as the PostgreSQL JSONB type.

Since: 1.0.0.0

fieldOfType

Arguments

:: SqlType a

SqlType that represents the PostgreSQL data type for the field.

-> 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 FieldDefinitions for your custom type.

Since: 1.0.0.0

whereColumnComparison :: (ValueExpression -> ValueExpression -> BooleanExpr) -> FieldDefinition nullability a -> a -> BooleanExpr

Constructs a field-based BooleanExpr using a function that builds a BooleanExpr.

Since: 1.0.0.0