PostgresqlSyntax.Parsing

Our parsing strategy is to port the original Postgres parser as closely as possible.

We're using the gram.y Postgres source file, which is the closest thing we have to a Postgres syntax spec. Here's a link to it: https:/github.compostgrespostgresblobmastersrcbackendparser/gram.y.

Here's the essence of how the original parser is implemented, citing from [PostgreSQL Wiki](https:/wiki.postgresql.orgwiki/Developer_FAQ):

scan.l defines the lexer, i.e. the algorithm that splits a string (containing an SQL statement) into a stream of tokens. A token is usually a single word (i.e., doesn't contain spaces but is delimited by spaces), but can also be a whole single or double-quoted string for example. The lexer is basically defined in terms of regular expressions which describe the different token types.

gram.y defines the grammar (the syntactical structure) of SQL statements, using the tokens generated by the lexer as basic building blocks. The grammar is defined in BNF notation. BNF resembles regular expressions but works on the level of tokens, not characters. Also, patterns (called rules or productions in BNF) are named, and may be recursive, i.e. use themselves as sub-patterns.

Documentation

>>> testParser parser = either putStr print . run parser

type Parser = HeadedParsec Void Text

Executors

run :: Parser a -> Text -> Either String a

Helpers

commaSeparator :: Parser ()

dotSeparator :: Parser ()

inBrackets :: Parser a -> Parser a

inBracketsCont :: Parser a -> Parser (Parser a)

inParens :: Parser a -> Parser a

inParensCont :: Parser a -> Parser (Parser a)

inParensWithLabel :: (label -> content -> result) -> Parser label -> Parser content -> Parser result

inParensWithClause :: Parser clause -> Parser content -> Parser content

trueIfPresent :: Parser a -> Parser Bool

quotedString :: Char -> Parser Text

>>> testParser (quotedString '\'') "'abc''d'"
"abc'd"

atEnd :: Parser a -> Parser a

PreparableStmt

preparableStmt :: Parser PreparableStmt

Insert

insertStmt :: HeadedParsec Void Text InsertStmt

insertTarget :: HeadedParsec Void Text InsertTarget

insertRest :: HeadedParsec Void Text InsertRest

overrideKind :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s OverrideKind

insertColumnList :: Parser InsertColumnList

insertColumnItem :: HeadedParsec Void Text InsertColumnItem

onConflict :: HeadedParsec Void Text OnConflict

confExpr :: HeadedParsec Void Text ConfExpr

onConflictDo :: HeadedParsec Void Text OnConflictDo

returningClause :: HeadedParsec Void Text ReturningClause

Update

updateStmt :: HeadedParsec Void Text UpdateStmt

setClauseList :: HeadedParsec Void Text (NonEmpty SetClause)

setClause :: HeadedParsec Void Text SetClause

setTarget :: HeadedParsec Void Text SetTarget

setTargetList :: Parser SetTargetList

Delete

deleteStmt :: HeadedParsec Void Text DeleteStmt

usingClause :: HeadedParsec Void Text UsingClause

Select

selectStmt :: HeadedParsec Void Text SelectStmt

>>> test = testParser selectStmt

>>> test "select id from as"
...
  |
1 | select id from as
  |                  ^
Reserved keyword "as" used as an identifier. If that's what you intend, you have to wrap it in double quotes.

selectWithParens :: HeadedParsec Void Text SelectWithParens

selectNoParens :: HeadedParsec Void Text SelectNoParens

sharedSelectNoParens :: Maybe WithClause -> HeadedParsec Void Text SelectNoParens

simpleSelectNoParens :: HeadedParsec Void Text SelectNoParens

The one that doesn't start with "WITH".

withSelectNoParens :: HeadedParsec Void Text SelectNoParens

selectClause :: HeadedParsec Void Text SelectClause

baseSimpleSelect :: HeadedParsec Void Text SimpleSelect

extensionSimpleSelect :: Either SimpleSelect SelectWithParens -> HeadedParsec Void Text SimpleSelect

allOrDistinct :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Bool

selectBinOp :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s SelectBinOp

valuesClause :: HeadedParsec Void Text ValuesClause

withClause :: HeadedParsec Void Text WithClause

commonTableExpr :: HeadedParsec Void Text CommonTableExpr

materialized :: (Ord e, Stream s, FoldCase (Tokens s), Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Bool

targeting :: HeadedParsec Void Text Targeting

targetList :: HeadedParsec Void Text (NonEmpty TargetEl)

targetEl :: HeadedParsec Void Text TargetEl

>>> testParser targetEl "a.b as c"
AliasedExprTargetEl (CExprAExpr (ColumnrefCExpr (Columnref (UnquotedIdent "a") (Just (AttrNameIndirectionEl (UnquotedIdent "b") :| []))))) (UnquotedIdent "c")

onExpressionsClause :: HeadedParsec Void Text ExprList

Into clause details

optTempTableName :: HeadedParsec Void Text IntoClause

Group by details

groupByItem :: HeadedParsec Void Text GroupByItem

Window clause details

windowDefinition :: HeadedParsec Void Text WindowDefinition

windowSpecification :: HeadedParsec Void Text WindowSpecification

partitionByClause :: HeadedParsec Void Text PartitionClause

frameClause :: HeadedParsec Void Text FrameClause

frameClauseMode :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s FrameClauseMode

frameExtent :: HeadedParsec Void Text FrameExtent

frameBound :: HeadedParsec Void Text FrameBound

windowExclusionClause :: (Ord e, Stream s, FoldCase (Tokens s), Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s WindowExclusionClause

Table refs

fromList :: HeadedParsec Void Text FromClause

fromClause :: HeadedParsec Void Text FromClause

tableRef :: HeadedParsec Void Text TableRef

>>> testParser tableRef "a left join b on (a.i = b.i)"
JoinTableRef (MethJoinedTable (QualJoinMeth...

nonTrailingTableRef :: HeadedParsec Void Text TableRef

trailingTableRef :: TableRef -> HeadedParsec Void Text TableRef

relationExpr :: HeadedParsec Void Text RelationExpr

relationExprOptAlias :: [Text] -> HeadedParsec Void Text RelationExprOptAlias

tablesampleClause :: HeadedParsec Void Text TablesampleClause

repeatableClause :: HeadedParsec Void Text RepeatableClause

funcTable :: HeadedParsec Void Text FuncTable

rowsfromItem :: HeadedParsec Void Text RowsfromItem

rowsfromList :: HeadedParsec Void Text (NonEmpty RowsfromItem)

colDefList :: HeadedParsec Void Text ColDefList

optOrdinality :: (Ord e, Stream s, Token s ~# Char, Tokens s ~# Text) => HeadedParsec e s Text

tableFuncElementList :: HeadedParsec Void Text ColDefList

tableFuncElement :: HeadedParsec Void Text TableFuncElement

collateClause :: HeadedParsec Void Text AnyName

funcAliasClause :: HeadedParsec Void Text FuncAliasClause

joinedTable :: Parser JoinedTable

inParensJoinedTable :: HeadedParsec Void Text JoinedTable

trailingJoinedTable :: TableRef -> HeadedParsec Void Text JoinedTable

joinType :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s JoinType

joinQual :: HeadedParsec Void Text JoinQual

aliasClause :: HeadedParsec Void Text AliasClause

Where

whereClause :: HeadedParsec Void Text WhereClause

whereOrCurrentClause :: HeadedParsec Void Text WhereOrCurrentClause

Sorting

sortClause :: HeadedParsec Void Text SortClause

sortBy :: HeadedParsec Void Text SortBy

Expressions

exprList :: HeadedParsec Void Text ExprList

exprListInParens :: HeadedParsec Void Text TypeModifiers

aExpr :: Parser AExpr

Notice that the tree constructed by this parser does not reflect the precedence order of Postgres. For the purposes of this library it simply doesn't matter, so we're not bothering with that.

Composite on the right: >>> testParser aExpr "a = b :: int4" SymbolicBinOpAExpr (CExprAExpr (ColumnrefCExpr (Columnref (UnquotedIdent "a") Nothing))) (MathSymbolicExprBinOp EqualsMathOp) (TypecastAExpr (CExprAExpr (ColumnrefCExpr (Columnref (UnquotedIdent "b") Nothing))) (Typename False (GenericTypeSimpleTypename (GenericType (UnquotedIdent "int4") Nothing Nothing)) False Nothing))

Composite on the left: >>> testParser aExpr "a = b :: int4 and c" SymbolicBinOpAExpr (CExprAExpr (ColumnrefCExpr (Columnref (UnquotedIdent "a") Nothing))) (MathSymbolicExprBinOp EqualsMathOp) (AndAExpr (TypecastAExpr (CExprAExpr (ColumnrefCExpr (Columnref (UnquotedIdent "b") Nothing))) (Typename False (GenericTypeSimpleTypename (GenericType (UnquotedIdent "int4") Nothing Nothing)) False Nothing)) (CExprAExpr (ColumnrefCExpr (Columnref (UnquotedIdent "c") Nothing))))

filteredAExpr :: [Text] -> HeadedParsec Void Text AExpr

customizedAExpr :: HeadedParsec Void Text CExpr -> Parser AExpr

bExpr :: HeadedParsec Void Text BExpr

customizedBExpr :: HeadedParsec Void Text CExpr -> HeadedParsec Void Text BExpr

cExpr :: HeadedParsec Void Text CExpr

customizedCExpr :: HeadedParsec Void Text Columnref -> HeadedParsec Void Text CExpr

subqueryOp :: HeadedParsec Void Text SubqueryOp

subType :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s SubType

inExpr :: HeadedParsec Void Text InExpr

symbolicBinOpExpr :: t1 -> HeadedParsec Void Text t2 -> (t1 -> SymbolicExprBinOp -> t2 -> b) -> HeadedParsec Void Text b

typecastExpr :: a -> (a -> Typename -> a) -> HeadedParsec Void Text a

plusedExpr :: (Stream strm, Ord err, Token strm ~# Char) => HeadedParsec err strm b -> HeadedParsec err strm b

minusedExpr :: (Stream strm, Ord err, Token strm ~# Char) => HeadedParsec err strm b -> HeadedParsec err strm b

qualOpExpr :: HeadedParsec Void Text a -> (QualOp -> a -> b) -> HeadedParsec Void Text b

row :: HeadedParsec Void Text Row

explicitRow :: HeadedParsec Void Text ExplicitRow

implicitRow :: HeadedParsec Void Text ImplicitRow

arrayExprCont :: HeadedParsec Void Text (HeadedParsec Void Text ArrayExpr)

caseExpr :: HeadedParsec Void Text CaseExpr

whenClause :: HeadedParsec Void Text WhenClause

elseClause :: HeadedParsec Void Text CaseDefault

funcExpr :: HeadedParsec Void Text FuncExpr

funcExprWindowless :: HeadedParsec Void Text FuncExprWindowless

withinGroupClause :: HeadedParsec Void Text WithinGroupClause

filterClause :: HeadedParsec Void Text FilterClause

overClause :: HeadedParsec Void Text OverClause

funcExprCommonSubexpr :: HeadedParsec Void Text FuncExprCommonSubexpr

extractList :: HeadedParsec Void Text ExtractList

extractArg :: HeadedParsec Void Text ExtractArg

overlayList :: HeadedParsec Void Text OverlayList

overlayPlacing :: HeadedParsec Void Text AExpr

positionList :: HeadedParsec Void Text PositionList

substrList :: HeadedParsec Void Text SubstrList

substrListFromFor :: HeadedParsec Void Text SubstrListFromFor

substrFrom :: HeadedParsec Void Text AExpr

substrFor :: HeadedParsec Void Text SubstrFor

trimModifier :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s TrimModifier

trimList :: HeadedParsec Void Text TrimList

funcApplication :: HeadedParsec Void Text FuncApplication

funcApplicationParams :: HeadedParsec Void Text FuncApplicationParams

normalFuncApplicationParams :: HeadedParsec Void Text FuncApplicationParams

singleVariadicFuncApplicationParams :: HeadedParsec Void Text FuncApplicationParams

listVariadicFuncApplicationParams :: HeadedParsec Void Text FuncApplicationParams

starFuncApplicationParams :: (Stream strm, Ord err, Token strm ~# Char) => HeadedParsec err strm FuncApplicationParams

funcArgExpr :: HeadedParsec Void Text FuncArgExpr

Ops

symbolicExprBinOp :: HeadedParsec Void Text SymbolicExprBinOp

lexicalExprBinOp :: (Ord e, Stream s, FoldCase (Tokens s), Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Text

qualOp :: HeadedParsec Void Text QualOp

qualAllOp :: HeadedParsec Void Text QualAllOp

op :: (Ord err, Stream strm, Token strm ~# Char, Tokens strm ~# Text) => HeadedParsec err strm Text

anyOperator :: HeadedParsec Void Text AnyOperator

allOp :: (Ord err, Stream strm, FoldCase (Tokens strm), IsString (Tokens strm), Token strm ~# Char, Tokens strm ~# Text) => HeadedParsec err strm AllOp

mathOp :: (Stream strm, FoldCase (Tokens strm), IsString (Tokens strm), Ord err, Token strm ~# Char) => HeadedParsec err strm MathOp

Constants

aexprConst :: HeadedParsec Void Text AexprConst

>>> testParser aexprConst "32948023849023"
IAexprConst 32948023849023

>>> testParser aexprConst "'abc''de'"
SAexprConst "abc'de"

>>> testParser aexprConst "23.43234"
FAexprConst 23.43234

>>> testParser aexprConst "32423423.324324872"
FAexprConst 3.2423423324324872e7

>>> testParser aexprConst "NULL"
NullAexprConst

iconstOrFconst :: (Stream strm, RealFloat b, Integral a, Ord err, Token strm ~# Char) => HeadedParsec err strm (Either a b)

iconst :: (Stream strm, Integral decimal, Ord err, Token strm ~# Char) => HeadedParsec err strm decimal

fconst :: (Stream strm, RealFloat float, Ord err, Token strm ~# Char) => HeadedParsec err strm float

sconst :: Parser Text

constTypename :: HeadedParsec Void Text ConstTypename

numeric :: HeadedParsec Void Text Numeric

bit :: HeadedParsec Void Text Bit

constBit :: HeadedParsec Void Text ConstBit

constCharacter :: HeadedParsec Void Text ConstCharacter

character :: (Ord e, Stream s, FoldCase (Tokens s), Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Character

constDatetime :: HeadedParsec Void Text ConstDatetime

timezone :: (Ord e, Stream s, FoldCase (Tokens s), Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Bool

interval :: HeadedParsec Void Text Interval

intervalSecond :: Integral a => HeadedParsec Void Text (Maybe a)

Clauses

selectLimit :: HeadedParsec Void Text SelectLimit

limitClause :: HeadedParsec Void Text LimitClause

offsetClause :: HeadedParsec Void Text OffsetClause

offsetClauseParams :: HeadedParsec Void Text OffsetClause

selectLimitValue :: HeadedParsec Void Text SelectLimitValue

rowOrRows :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Bool

firstOrNext :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Bool

selectFetchFirstValue :: HeadedParsec Void Text SelectFetchFirstValue

plusOrMinus :: (Stream strm, Ord err, Token strm ~# Char) => HeadedParsec err strm Bool

For Locking

forLockingClause :: HeadedParsec Void Text ForLockingClause

forLockingItem :: HeadedParsec Void Text ForLockingItem

forLockingStrength :: (Ord e, Stream s, FoldCase (Tokens s), Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s ForLockingStrength

nowaitOrSkip :: (Ord e, Stream s, FoldCase (Tokens s), Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Bool

References & Names

quotedName :: HeadedParsec Void Text Ident

ident :: HeadedParsec Void Text Ident

colId :: HeadedParsec Void Text Ident

filteredColId :: Foldable t => t Text -> HeadedParsec Void Text Ident

colLabel :: HeadedParsec Void Text Ident

qualifiedName :: HeadedParsec Void Text QualifiedName

>>> testParser qualifiedName "a.b"
IndirectedQualifiedName (UnquotedIdent "a") (AttrNameIndirectionEl (UnquotedIdent "b") :| [])

>>> testParser qualifiedName "a.-"
...
expecting '*', column label, or white space

columnref :: HeadedParsec Void Text Columnref

filteredColumnref :: [Text] -> HeadedParsec Void Text Columnref

customizedColumnref :: HeadedParsec Void Text Ident -> HeadedParsec Void Text Columnref

anyName :: HeadedParsec Void Text AnyName

filteredAnyName :: Foldable t => t Text -> HeadedParsec Void Text AnyName

customizedAnyName :: HeadedParsec Void Text ColId -> HeadedParsec Void Text AnyName

name :: HeadedParsec Void Text Ident

nameList :: HeadedParsec Void Text (NonEmpty Ident)

cursorName :: HeadedParsec Void Text Ident

funcName :: Parser FuncName

typeFunctionName :: HeadedParsec Void Text Ident

indirection :: HeadedParsec Void Text Indirection

indirectionEl :: HeadedParsec Void Text IndirectionEl

attrName :: HeadedParsec Void Text Ident

keywordNameFromSet :: (Ord err, Stream strm, Tokens strm ~# Text, Token strm ~# Char) => HashSet Text -> HeadedParsec err strm Ident

keywordNameByPredicate :: (Ord err, Stream strm, Tokens strm ~# Text, Token strm ~# Char) => (Text -> Bool) -> HeadedParsec err strm Ident

anyKeyword :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s Text

keyword :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => Text -> HeadedParsec e s Text

Expected keyword

keyphrase :: (FoldCase (Tokens s), Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => Text -> HeadedParsec e s Text

Consume a keyphrase, ignoring case and types of spaces between words.

Typename

typeList :: Parser TypeList

typename :: HeadedParsec Void Text Typename

arrayBounds :: Integral a => HeadedParsec Void Text (NonEmpty (Maybe a))

simpleTypename :: HeadedParsec Void Text SimpleTypename

genericType :: HeadedParsec Void Text GenericType

attrs :: HeadedParsec Void Text (NonEmpty Ident)

typeModifiers :: HeadedParsec Void Text TypeModifiers

Indexes

indexParams :: HeadedParsec Void Text (NonEmpty IndexElem)

indexElem :: HeadedParsec Void Text IndexElem

indexElemDef :: HeadedParsec Void Text IndexElemDef

collate :: HeadedParsec Void Text AnyName

class_ :: HeadedParsec Void Text AnyName

ascDesc :: (Ord e, Stream s, Tokens s ~# Text, Token s ~# Char) => HeadedParsec e s AscDesc

nullsOrder :: (Ord e, Stream s, Token s ~# Char, Tokens s ~# Text) => HeadedParsec e s NullsOrder