graphql-w-persistent-0.7.0.0: GraphQL interface middleware for (SQL) databases.

LicenseIPS
Maintainerjasonsychau@live.ca
Stabilityprovisional
Safe HaskellSafe
LanguageHaskell2010

GraphQLdbi

Contents

Description

Here is a link to the official documents. You can learn and get a feel of how can you implement this package which is a GraphQL-to-SQL translator with Persistent package style return-value processing to make a GraphQL format return object string.

This module is made to enable interpreting your GraphQL queries. The expected query type is a single string to comprise all your GraphQL queries and fragments, and the expected variable type is a single string to your variable-to-value definitions.

When errors are encountered, this module is simply going to throw an uncaught Exception. The Exception name is some hint to where was the error encountered. More information is provided in the below function description.

Not all GraphQL features are currently supported. For a list to updates and current state, you should check the GitHub updates and example page.

Synopsis

Functions

Here is three methods to the package interpretation, validation, and formatting features.

processSchema Source #

Arguments

:: MonadIO m 
=> FilePath

This is the path to schema json file

-> m SchemaSpecs

The return value is a monad for your schema data.

This function is to parse your schema. The return values are passed to the other two functions to interpret your schema. You can declare and define your schema with tuples and lists without reading a json file as defined in below function, but you will not receive type and duplicate checking from this function.

Schema:

The schema json file is formated as one json object to describe the GraphQL objects and the object heirarchy. Only PrimitiveObjects are valid descendants to ParentalObjects. Only the shared object fields and shared scalar fields are parental object fields. If a parental object is a declared field from a primitive object, all descendants are supposed to be declared in database relationships. When declaring any primitive or parental object, the pseudonym is supposed to list all possible root object references. As a nested object, you should declare the names in the nested object field definitions in corresponding object definitions. Primitive objects are expected to not have all NULL unique id values, and they are otherwise removed from the result. Database relationships are defined as an ordered sequence from the identity table to the target association table. The order is identity table, identity table join field(s), target table, target table join field(s), then (multiple) triplets (of intermediate table, intermediate table to-join field, then intermediate table from-join field in order of nearness from identity table) if relevant. If multiple fields are defining the join, one declares every field with a space " " separation. For example, the declaration is [A,"a b", B, "c d"] if the join condition is A.a=B.c and A.b = B.d. You can add schema associations as declaring more object-fields in the primitive objects.

Scalar fields:

Scalar fields are declared with a type, and they are cast to corresponding JSON format when making the GraphQL result. Valid scalar field types are Text, ByteString, Int, Double, Rational, Bool, Day, TimeOfDay, or UTCTime.

Function exceptions:

Exceptions are returned when error is faced. This method returns errors of:

  • ImportSchemaException (if there is a problem with reading your schema)
  • ImportSchemaServerNameException (if there is a problem with reading your servername argument)
  • ImportSchemaPseudonymsException (if there is a problem with reading your pseudonyms list argument)
  • ImportSchemaScalarFieldsException (if there is a problem with reading your scalarfields list argument)
  • ImportSchemaObjectFieldsException (if there is a problem with reading your objectfields list argument)
  • ImportSchemaDatabaseTablesException (if there is a problem with reading your databasetables list argument)
  • ImportSchemaDatabaseRelationshipsException (if there is a problem with reading your databaserelationships list argument)
  • ImportSchemaDuplicateException (if two or more Server objects are sharing the same name)

Schema format example:

Here is an example schema to look at formatting:

   {
     ParentalObjects:[
       {
         ServerName:Taxonomy,
         Pseudonyms:[
           "taxonomy",
           Taxonomy
         ],
         ServerChildren:[
           Breed,
           Species,
           Family,
           Genus
         ]
       }
     ],
     PrimitiveObjects:[
       {
         ServerName: Person,
         Pseudonyms: [
           "person",
           Person
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           },
           {
             Name: "gender",
             Type: Int,
             Arguments: [
               {
                 Name: "as",
                 Options: [
                   {
                     Name: MALEFEMALE,
                     Type: Text,
                     Prefix: "CASE WHEN ",
                     Suffix: "==1 THEN MALE ELSE FEMALE END"
                   }
                 ]
               }
             ]
           }
         ],
         ObjectFields: [
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "taxonomy"   
             ],
             ServerName: Taxonomy
           }
         ],
         DatabaseTable: "person",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["person","id","pet","id","pet_ownership","owner_id","animal_id"],
           ["person","id","breed","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id"],
           ["person","id","species","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id","breed","id","species_id"],
           ["person","id","genus","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id"],
           ["person","id","family","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id","genus","id","family_id"]
         ]
       },
       {
         ServerName: Family,
         Pseudonyms: [
           Family,
           "family"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "family",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["family","id","person","id","genus","family_id","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["family","id","pet","id","genus","family_id","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id"],
           ["family","id","genus","family_id"],
           ["family","id","species","genus_id","genus","family_id","id"],
           ["family","id","breed","species_id","genus","family_id","id","species","genus_id","id"]
         ]
       },
       {
         ServerName: Genus,
         Pseudonyms: [
           Genus,
           "genus"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "genus",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["genus","id","person","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["genus","id","pet","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id"],
           ["genus","family_id","family","id"],
           ["genus","id","species","genus_id"],
           ["genus","id","breed","species_id","species","genus_id","id"]
         ]
       },
       {
         ServerName: Species,
         Pseudonyms: [
           Species,
           "species"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "species",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["species","id","person","id","breed","species_id","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["species","id","pet","id","breed","species_id","id","pet_type","breed_id","pet_id"],
           ["species","id","breed","species_id"],
           ["species","genus_id","genus","id"],
           ["species","id","family","genus_id","genus","species_id","id"]
         ]
       },
       {
         ServerName: Breed,
         Pseudonyms: [
           Breed,
           "breed"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "breed",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["breed","id","person","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["breed","id","pet","id","pet_type","breed_id","pet_id"],
           ["breed","species_id","species","id"],
           ["breed","species_id","genus","id","species","id","genus_id"],
           ["breed","species_id","family","id","species","id","genus_id","genus","id","family_id"]
         ]
       },
       {
         ServerName: Pet,
         Pseudonyms: [
           "pet",
           Pet
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           },
           {
             Name: "gender",
             Type: Int,
             Arguments: [
               {
                 Name: "as",
                 Options: [
                   {
                     Name: MALEFEMALE,
                     Type: Text,
                     Prefix: "CASE WHEN ",
                     Suffix: "==1 THEN MALE ELSE FEMALE END"
                   }
                 ]
               }
             ]
           }
         ],
         ObjectFields: [
           {
             Names: [
               "owner"
             ],
             ServerName: Person
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "taxonomy"
             ],
             ServerName: Taxonomy
           }
         ],
         DatabaseTable: "pet",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["pet","id","person","id","pet_ownership","animal_id","owner_id"],
           ["pet","id","breed","id","pet_type","pet_id","breed_id"],
           ["pet","id","species","id","pet_type","pet_id","breed_id","breed","id","species_id"],
           ["pet","id","genus","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id"],
           ["pet","id","family","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id","genus","id","family_id"]
         ]
       }
     ]
   }

Schema recommendation:

When you add every possible chain from every PrimitiveObject to every other PrimitiveObject, the schema coverage is extended.

Closing remark:

As the last remark, I'll turn attention to a quote from specifications.

"In contrast, GraphQL only returns the data that's explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking change. This has lead to a common practice of always avoiding breaking changes and serving a versionless API." - https://graphql.github.io/learn/best-practices/

With respect to that, you should elaborate on your schema representation. You should give all planned details, and you should make adjustments when you feel to evolve your server by making associations that are like simple arcs in a graph.

processQueryString Source #

Arguments

:: SchemaSpecs

This is the data about your schema

-> String

This is the GraphQL query

-> String

This is the variables string

-> (QueryData, [[String]])

The return value is a tuple with package objects and list with grouped sql query strings.

This function is to parse, validate, and interpret your query with variables. If you don't have variables, you may pass an empty string. The function is expecting your schema as SchemaSpec type from the above function. You can alternatively define you schema with lists and tuples.

You also can use the above function to print and paste your schema data into your script file.

Function return value:

The returned values are one tuple to contain information to pass into your database interface and to later reuse in below data processing function. The tuple is (PackagedObjects,SQLQueries). The second tuple member is a collection of queries. Examples are found in this repository page to pass queries (and data) to your database.

Function exceptions:

Exceptions are returned when error is faced. This method returns errors of:

  • SyntaxException (if there is a problem with the given GraphQL query syntax)
  • ParseFragmentException (if there is a problem with a Fragment syntax)
  • EmptyQueryException (if the query is left blank)
  • InvalidObjectException (if there is problem in nested object syntax, an object is not recognized, or server data is misinterpreted)
  • InvalidObjectSubFieldException (if a subfield is requested from nested object that is not having ownership of the subfield)
  • InvalidScalarException (if there is syntax error in listing scalar fields, or server data is misinterpreted)
  • NullArgumentException (if a transformation is set but no argument is given though we do not yet support transformations)
  • CreatingSqlQueryObjectFieldsException (if there are too many nested object subfields than nested objects to hold them or if there is a problem with the aligning of server object relationship argument - that's the fifth schema argument)
  • RelationshipConfigurationException (if the relationship schema fifth arugment is incorrect number of String values, if an unrecognized pairing is found, or if two table field cardinalities are not same)
  • FailedObjectEqualityException (if we could not match identical queries)
  • DuplicateRootObjectsException (if there is an overlapping query)
  • MissingVariableValueException (if we are missing variables in the variables-value string to the query)
  • InvalidVariableNameException (if we cannot find a variable in the query with given variables-value string)
  • MismatchedVariableTypeException (if query variable type is not matching object scalar type)
  • InvalidVariableTypeException (if variable type is invalid or missing)
  • ReadVariablesException (if the variables json string syntax is incorrect or was not correctly read)
  • VariablesSyntaxException (if the query variables declaration is invalid syntax)

processQueryData Source #

Arguments

:: SchemaSpecs

This is the schema data from the first method

-> QueryData

This is the package objects that is from processQueryString function.

-> [[[[Text]]]]

This is the database query results value in the same order and after casting to Text values.

-> String

The return value is a string type to describe the GraphQL-organized return values.

After casting all database results to Text (examples are given in this repository site), you may use this function to make GraphQL data.

The second argument is the package objects given from function processQueryString.

The return result is a string to resemble a GraphQL return value.

Formatting notes (IMPORTANT):

Nulls are expected as "Unexpected null". This is the Persistent default and important when processing ids to separate different results. One can translate nulls to "Unexpected null" when making Text types of query results. This is in the repository examples.

Function exceptions:

Exceptions are returned when error is faced. This method returns errors of:

  • InvalidObjectException (when server data is misinterpreted or an unrecognized server object is met)
  • InvalidScalarException (when server data is misinterpreted)
  • EOFDataProcessingException (when the given data is shorter than expected in reference to the given serve objects)
  • InvalidArgumentException (when there is an internal argument error - you should not observe this)
  • InvalidVariableTypeException (when an unrecognized base data type is met)
  • InvalidObjectScalarFieldException (when an unrecognized object-scalar pair is met)

Server exceptions

These are server exceptions to make error handling.

data QueryException Source #

Constructors

SyntaxException 
ParseFragmentException 
EmptyQueryException 
InvalidObjectException 
InvalidScalarException 
NullArgumentException 
CreatingSqlQueryObjectFieldsException 
CreatingSqlQueryObjectsException 
EOFDataProcessingException1 
EOFDataProcessingException2 
EOFDataProcessingException3 
EOFDataProcessingException4 
EOFDataProcessingException5 
EOFDataProcessingException6 
EOFDataProcessingException7 
EOFDataProcessingException8 
EOFDataProcessingException9 
RelationshipConfigurationException 
FailedObjectEqualityException 
DuplicateRootObjectsException 
ImportSchemaException 
ImportSchemaServerNameException 
ImportSchemaPseudonymsException 
ImportSchemaScalarFieldsException 
ImportSchemaObjectFieldsException 
ImportSchemaDatabaseTablesException 
ImportSchemaDatabaseRelationshipsException 
ImportSchemaChildrenException 
ImportSchemaDuplicateException 
MissingVariableValueException 
InvalidVariableNameException 
MismatchedVariableTypeException 
InvalidVariableTypeException 
ReadVariablesException 
VariablesSyntaxException 
InvalidArgumentException 
InvalidObjectSubfieldException 
Instances
Show QueryException Source # 
Instance details

Defined in Model.ServerExceptions

Methods

showsPrec :: Int -> QueryException -> ShowS #

show :: QueryException -> String #

showList :: [QueryException] -> ShowS #

Exception QueryException Source # 
Instance details

Defined in Model.ServerExceptions

Methods

toException :: QueryException -> SomeException #

fromException :: SomeException -> Maybe QueryException #

displayException :: QueryException -> String #