\n"
36 |
--------------------------------------------------------------------------------
/GrammarToAsciidoc.lhs:
--------------------------------------------------------------------------------
1 |
2 | This file converts the text grammar files into asciidoc
3 |
4 | creates asciidoc headings from the text headings (==, ===)
5 | changes 'Function' and 'Format' into local headings (.Function)
6 | adds anchors to the start of each grammar def
7 | adds anchor links in the grammar def bodies
8 | adds blocks around the grammar defs
9 |
10 | TODO:
11 |
12 | add backreferences from grammer def names to usage sites (in
13 | side bar?)
14 |
15 | get links working e.g. from psm to foundation doc
16 |
17 | > import Data.Char
18 | > --import System.Environment
19 | > --import Data.List
20 | > import Text.Regex
21 |
22 | > --import Debug.Trace
23 |
24 | > main :: IO ()
25 | > main = do
26 | > str <- getContents
27 | > let ls = lines str
28 | > ls' = addBlocks False ls
29 | > putStrLn ":toc: right\n\n= Document\n"
30 | > putStrLn $ unlines ls'
31 |
32 |
33 | start a pre block:
34 | add the anchor and start the block
35 |
36 | > addBlocks :: Bool -> [String] -> [String]
37 | > addBlocks False (x@('<':t):xs) = --trace (show ("g",x)) $
38 | > let t' = hyphenize $ takeWhile (/='>') t
39 | > in ("[[" ++ t' ++ "]]")
40 | > :"[subs=\"specialcharacters,macros\"]"
41 | > :"----":x:addBlocks True xs
42 | > where
43 | > hyphenize = map $ \c -> case c of
44 | > ' ' -> '-'
45 | > _ -> c
46 |
47 | inside a pre block, check if this is the end of the block
48 |
49 | special case for the keywords which have empty lines inside the
50 | grammar defs
51 |
52 | > addBlocks True (x:y:xs) | trim x == ""
53 | > && startsWithPipe (trim y)
54 | > = x:addBlocks True (y:xs)
55 | > where
56 | > startsWithPipe ('|':_) = True
57 | > startsWithPipe _ = False
58 |
59 | regular end of grammar def - an empty line
60 |
61 | > addBlocks True (x:xs) | trim x == "" = "----":x:addBlocks False xs
62 |
63 |
64 | inside a pre block, change a grammar reference into an anchorlink
65 | line with grammar defs, add links
66 |
67 | (<([^>]*)>) -> <
68 |
69 | example:
70 |
71 | ->
72 | < >>
73 |
74 | > {-addBlocks True (x@(' ':_):xs)
75 | > | trace (show (grammarLine x, x)) False = undefined
76 | > where
77 | > grammarLine y = case dropWhile isSpace y of
78 | > '<':_ -> True
79 | > _ -> False-}
80 |
81 | > addBlocks True (x@(' ':_):xs) =
82 | > fixLinks (
83 | > subRegex (mkRegex "(<([^>]*)>)") x "<<\\2, \\1 >>")
84 | > : addBlocks True xs
85 | > where
86 | > {-grammarLine y = case dropWhile isSpace y of
87 | > '<':_ -> True
88 | > _ -> False-}
89 | > fixLinks ('<':'<':ts) = '<':'<': hyph ts
90 | > fixLinks (t:ts) = t : fixLinks ts
91 | > fixLinks [] = []
92 | > hyph (',':ts) = ',':fixLinks ts
93 | > hyph (' ':ts) = '-' : hyph ts
94 | > hyph (t:ts) = t : hyph ts
95 | > hyph [] = []
96 |
97 |
98 | > addBlocks True (x:xs) = x:addBlocks True xs
99 |
100 | add a newline after function,format headers so they render nicely
101 |
102 | > addBlocks False (x:xs) | trim x `elem` headers =
103 | > ('.':x):"":addBlocks False xs
104 | > where headers = ["Function","Format"]
105 |
106 | section titles
107 |
108 | > addBlocks False (x@(c1:_):xs) | isDigit c1 =
109 | > (case dropWhile isDigit x of
110 | > '.':_ -> "=== " ++ x
111 | > _ -> "== " ++ x)
112 | > : addBlocks False xs
113 |
114 |
115 | any other line: todo, check for anchor links
116 |
117 | > addBlocks False (x:xs) = x:addBlocks False xs
118 |
119 | finished the document
120 |
121 | > addBlocks True [] = ["----"]
122 | > addBlocks False [] = []
123 |
124 |
125 |
126 | > trim :: String -> String
127 | > trim = f . f
128 | > where f = reverse . dropWhile isSpace
129 |
--------------------------------------------------------------------------------
/README:
--------------------------------------------------------------------------------
1 | This project contains grammars for the ANSI SQL Standards (taken from
2 | the drafts).
3 |
4 | See the HTML rendered grammars here:
5 |
6 | http://jakewheat.github.io/sql-overview/
7 |
8 | TODO
9 | Cover most of the SQL Standard:
10 |
11 | explain what the concepts are. Document the names for these in the SQL
12 | standard, and what names products use.
13 |
14 | Focus mostly on grammar, but also on semantics. Explain and give
15 | examples of sql source, and cover the availability of these in sql
16 | products, mentioning the compatibility with the standard and other
17 | products, and the jargon used for each product.
18 |
19 | The reader should go away with:
20 |
21 | * an understanding of what is in the standard and what the names of
22 | things really mean
23 |
24 | * an understanding of which bits of the standard are widely supported,
25 | which bits are widely supported but with varying syntax or
26 | behaviour, and which bits exist only in the minds of the sql
27 | standards people and don't relate to reality
28 |
29 | * an understanding of why features exist and what purpose they are for
30 |
31 | * an understanding of which features are supported in a range of
32 | common products
33 |
34 | * a good and in depth appreciation for sql's strengths and weaknesses
35 |
36 | Provisional product list ideas: db2, oracle, sql server, sap dbmss,
37 | postgresql, mysql.
38 |
39 | TODO: cross referenced grammar
40 |
41 | What kinds of features are in the standards:
42 |
43 | 1 syntax which everyone supports
44 | 2 syntax which many dbmss support
45 | 3 features which many dbmss support with different syntax
46 | 4 features which many dbmss support, possibly with different syntax,
47 | with not very similar semantics
48 | 5 features which no or very few dbmss support
49 |
50 | -------
51 |
52 | TOC ideas:
53 | databases, tables, queries, updates
54 |
55 | scalar types
56 | type constructors: row, array, multiset
57 | scalar expressions
58 | dml
59 | queries
60 |
61 | queries
62 | select list
63 | table ref, joins
64 | aggregates, group by, grouping sets
65 | window functions
66 | where, having
67 | limit, offset
68 | order by
69 | set operations
70 | cte
71 | array unnest and variations?
72 | subqueries, csq, lateral
73 |
74 | updates
75 | delete
76 | truncate
77 | insert
78 | merge
79 | update
80 | cursors
81 | temporary tables ??
82 | ddl, schemas
83 | tables, columns
84 | defaults, identity, sequences
85 | constraints, unique/pk, not null, referential, check
86 | alter table
87 | table periods, system versioning
88 | other schema objects
89 |
90 | locators??
91 | transaction management
92 | session management
93 | catalog
94 | access control
95 |
96 | clients, servers, sessions, connections
97 | databases, 'catalog clusters', and schemas
98 |
99 | control statements
100 | connection management
101 | diagnostics
102 |
103 | dynamic sql
104 | embedded sql
105 | direct invocation
106 |
107 | procedural sql
108 | external data
109 | extensibility
110 |
111 | call level interface
112 | persistent stored modules
113 | management of external data
114 | object language bindings (java?)
115 | information and definition schema
116 | java
117 | xml
118 |
119 |
120 | --------------------------
121 |
122 | postgres manual says that there are 179 mandatory features for 2011
123 | core conformance, postgres does 160, and no database product does all
124 | of these
125 |
126 |
--------------------------------------------------------------------------------
/Setup.hs:
--------------------------------------------------------------------------------
1 | import Distribution.Simple
2 | main = defaultMain
3 |
--------------------------------------------------------------------------------
/fix_lines.pl:
--------------------------------------------------------------------------------
1 | #read stdin as a single string and not a line at a time
2 | my $whole_file; { local $/; $whole_file = };
3 |
4 | # line wrapped in the middle of reference
5 | # This:
6 | # some text really references
8 | # Turns into:
9 | # some text really references
10 | #
11 | # first capture group gets an unclosed < that looks like a reference
12 | # then uncaptured whitespace around a newline
13 | # second capture group gets the rest of the reference and its closing >
14 | # the replacement has a space in the middle to replace the whitespace that was a newline
15 | $whole_file =~ s/(<[a-z][a-zA-Z: ]*)\s*\n\s*([a-zA-Z: ]+[a-z]>)/$1 $2/g;
16 |
17 | # remove linebreaks in paragraph text that put a reference at the beginning of a line
18 | # the only allowed references at the beginning of the line are actual definitions with ::= on the same line
19 | $whole_file =~ s/(\w)\s*\n(<[a-z][a-zA-Z: ]+[a-z]>(?!.*::=))/$1 $2/g;
20 |
21 | # print the processed file back out for further processing
22 | print $whole_file;
23 |
--------------------------------------------------------------------------------
/index.asciidoc:
--------------------------------------------------------------------------------
1 |
2 | :toc: right
3 | :toclevels: 8
4 |
5 | = SQL overview
6 |
7 | == Overview
8 |
9 | WIP
10 |
11 | This is a project to review SQL: run through the standard and explain
12 | what each feature is, explain the jargon terms, explain why the
13 | feature exists, and explain the relationship with real sql products -
14 | standard feature, possibly with different syntax/ different semantics/
15 | different names/jargon; or one of those SQL Standard things which
16 | bears no relationship to reality.
17 |
18 | Maybe provide a little history and context also, with a little bit of
19 | relational theory.
20 |
21 | Glossary for SQL
22 |
23 | == SQL recommended reading
24 |
25 | SQL: The Complete Reference, 3rd Edition, James R. Groff, Paul
26 | N. Weinberg, Andrew J. Oppel
27 |
28 | This is a comprehensive book which covers up to the SQL:1999 standard.
29 | +
30 | +
31 | +
32 | SQL in a Nutshell, Kevin Kline, Brand Hunt, Daniel Kline
33 |
34 | This is another good book which covers some of the SQL:2003 and
35 | SQL:2008 standards. This means it covers a few newer things like
36 | window functions which 'SQL: The Complete Reference' doesn't. It also
37 | compares some main SQL product dialects.
38 | +
39 | +
40 | +
41 | SQL A Comparative Survey, Hugh Darwen +
42 | http://bookboon.com/en/sql-a-comparative-survey-ebook
43 |
44 | This is a book about SQL from a relational theory perspective.
45 | +
46 | +
47 | +
48 | SQL and Relational Theory, 2nd Edition, Chris Date
49 |
50 | This also covers SQL from a partly theoretical perspective.
51 | +
52 | +
53 | +
54 | A Guide to the SQL Standard, C. J. Date, Hugh Darwen
55 |
56 | This is a fantastic book for covering all the little details of the
57 | SQL standard in depth. It only covers up to SQL:92.
58 | +
59 | +
60 | +
61 | There are several other good books by Chris Date, some with Hugh
62 | Darwen and others, for instance 'Introduction to Database Systems',
63 | 'Temporal Data & the Relational Model, Databases', 'Types and the
64 | Relational Model'. Only the first one (Introduction to
65 | Database Systems) really relates to SQL.
66 | +
67 | +
68 | +
69 | Database Systems: The Complete Book, Hector Garcia-Molina, Jeff Ullman, and Jennifer Widom.
70 |
71 | This book is very comprehensive and has some interesting sections.
72 | +
73 | +
74 | +
75 | Some of the SQL draft standards are available to download for free
76 | (follow the links on the wikipedia page for SQL or try google). They
77 | are a little tricky to read and understand. You can find some stuff at
78 | these links. There is also the grammars from the draft standards
79 | below on this page.
80 |
81 | http://savage.net.au/SQL/index.html
82 |
83 | http://www.wiscorp.com/SQLStandards.html
84 | +
85 | +
86 | +
87 | //TODO: add stuff about transactions, cbo, newsql?
88 |
89 | == SQL products' manuals
90 |
91 | IBM DB2 10.5 SQL Reference Volume 1
92 |
93 | http://public.dhe.ibm.com/ps/products/db2/info/vr105/pdf/en_US/DB2SQLRefVol1-db2s1e1050.pdf
94 | +
95 | +
96 | +
97 | Oracle SQL Reference 12c release 1
98 |
99 | http://docs.oracle.com/cd/E16655_01/server.121/e17209.pdf
100 | +
101 | +
102 | +
103 | Teradata:
104 |
105 | TODO
106 | +
107 | +
108 | +
109 | Microsoft SQL Server 2012 TSQL reference online. I didn't find a PDF
110 | for this.
111 |
112 | http://technet.microsoft.com/en-us/library/bb510741.aspx
113 | +
114 | +
115 | +
116 | PostgreSQL 9.4 manual:
117 |
118 | http://www.postgresql.org/docs/9.4/interactive/index.html
119 |
120 | No PDF for the Postgres manual either, but the web pages are very
121 | readable.
122 | +
123 | +
124 | +
125 | TODO: MySQL, Redshift, Netezza, Vertica, Vectorwise,
126 | Infobright, MemSQL, FoundationDB, Dataphor, EnterpriseDB, Pivotal,
127 | Informix, Ingres, MariaDB, SQLite, Firebird, MonetDB, Nonstop SQL?,
128 | some small subset of the SAP SQL DBMSs (maxdb, anywhere, hana?).
129 |
130 | == SQL Grammars
131 |
132 | link:sql-92-grammar.html[]
133 |
134 | link:sql-1999-grammar.html[]
135 |
136 | link:sql-2003-foundation-grammar.html[]
137 |
138 | link:sql-2008-foundation-grammar.html[]
139 |
140 | link:sql-2011-foundation-grammar.html[]
141 |
142 | link:sql-2011-psm-grammar.html[]
143 |
--------------------------------------------------------------------------------
/make_website.sh:
--------------------------------------------------------------------------------
1 | #! /usr/bin/env bash
2 |
3 | # instructions: have a recent version of cabal-install and ghc in your path
4 | # and perl, asciidoctor
5 | # run this file and it will generate the html to the build dir
6 | # tested with cabal-install 3.0.0.0 and ghc 8.10.1
7 | # should work with earlier versions of both (and later)
8 | # last ran with asciidoctor 1.5.8
9 |
10 | set -e
11 |
12 | mkdir -p build
13 |
14 | asciidoctor index.asciidoc -o -| cabal run -v0 AddLinks > build/index.html
15 |
16 | for i in sql-92-grammar sql-1999-grammar sql-2003-foundation-grammar sql-2008-foundation-grammar sql-2011-foundation-grammar sql-2011-psm-grammar sql-2016-foundation-grammar; do
17 | echo $i
18 | perl fix_lines.pl < $i.txt | cabal run -v0 GrammarToAsciidoc | asciidoctor - | cabal run -v0 AddLinks > build/$i.html
19 | done
20 |
21 |
--------------------------------------------------------------------------------
/sql-2011-psm-grammar.txt:
--------------------------------------------------------------------------------
1 |
2 | 5 Lexical elements
3 |
4 | This Clause modifies Clause 5, "Lexical elements", in ISO/IEC 9075-2.
5 |
6 |
7 |
8 | 5.1 and
9 |
10 | Function
11 | Specify lexical units (tokens and separators) that participate in SQL language.
12 |
13 |
14 | Format
15 | ::=
16 | !! All alternatives from ISO/IEC 9075-2
17 |
18 | | CONDITION_IDENTIFIER
19 |
20 | | EXIT
21 |
22 | | STACKED
23 |
24 | | UNDO
25 |
26 | ::=
27 | !! All alternatives from ISO/IEC 9075-2
28 |
29 | | DO
30 |
31 | | ELSEIF
32 |
33 | | HANDLER
34 |
35 | | IF | ITERATE
36 |
37 | | LEAVE | LOOP
38 |
39 | | REPEAT | RESIGNAL
40 |
41 | | SIGNAL
42 |
43 | | UNTIL
44 |
45 | | WHILE
46 |
47 | 5.2 Names and identifiers
48 |
49 | Function
50 | Specify names.
51 |
52 |
53 | Format
54 | ::=
55 |
56 |
57 | ::=
58 |
59 |
60 | ::=
61 |
62 |
63 | 6 Scalar expressions
64 |
65 | 6.1 and
66 |
67 | Function
68 | Specify one or more values, host parameters, SQL parameters, dynamic parameters, host variables, or SQL
69 | variables.
70 |
71 |
72 | Format
73 | ::=
74 | !! All alternatives from ISO/IEC 9075-2
75 | |
76 |
77 | ::=
78 | !! All alternatives from ISO/IEC 9075-2
79 | |
80 |
81 | ::=
82 | !! All alternatives from ISO/IEC 9075-2
83 | |
84 |
85 | ::=
86 | !! All alternatives from ISO/IEC 9075-2
87 | |
88 |
89 | ::=
90 | !! All alternatives from ISO/IEC 9075-2
91 | |
92 |
93 | 6.4
94 |
95 | Function
96 | Reference an SQL variable.
97 |
98 |
99 | Format
100 | ::=
101 |
102 |
103 | 8 Persistent Stored Modules (SQL/PSM)
104 |
105 | 8.2
106 |
107 | Function
108 | Specify an SQLSTATE value.
109 |
110 |
111 | Format
112 | ::=
113 | SQLSTATE [ VALUE ]
114 |
115 | 9 Schema definition and manipulation
116 |
117 | 9.1
118 |
119 | Function
120 | Define a schema.
121 |
122 |
123 | Format
124 | ::=
125 | !! All alternatives from ISO/IEC 9075-2
126 | |
127 |
128 | 9.19
129 |
130 | Function
131 | Defined triggered SQL-statements.
132 |
133 |
134 | Format
135 | ::=
136 |
137 | NOTE 12 - The preceding production defining completely supersedes the definition in [ISO9075-2].
138 |
139 | 9.21
140 |
141 | Function
142 | Define an SQL-server module.
143 |
144 |
145 | Format
146 | ::=
147 | CREATE MODULE
148 | [ ]
149 | [ ]
150 | [ ]
151 | [ ... ]
152 | ...
153 | END MODULE
154 |
155 | ::=
156 | NAMES ARE
157 |
158 | ::=
159 | SCHEMA
160 |
161 | ::=
162 |
163 |
164 | ::=
165 |
166 |
167 | ::=
168 |
169 |
170 | 9.22
171 |
172 | Function
173 | Destroy an SQL-server module.
174 |
175 |
176 | Format
177 | ::=
178 | DROP MODULE
179 |
180 | 9.24
181 |
182 | Function
183 | Define an SQL-invoked routine.
184 |
185 |
186 | Format
187 | ::=
188 | !! All alternatives from ISO/IEC 9075-2
189 | |
190 |
191 | ::=
192 |
193 | |
194 |
195 | ::=
196 | [ DECLARE ]
197 |
198 | ::=
199 | [ DECLARE ]
200 |
201 | 10 Access control
202 |
203 | 10.2
204 |
205 | This Subclause modifies Subclause 12.3, "", in ISO/IEC 9075-2.
206 |
207 |
208 | Function
209 | Specify privileges.
210 |
211 |
212 | Format
213 |