lib/SQL/Abstract/Manual/Specification.pod

   1 =head1 NAME
   2
   3 SQL::Abstract::Manual::Specification
   4
   5 =head1 SYNOPSIS
   6
   7 This discusses the specification for the AST provided by L<SQL::Abstract>. It is
   8 meant to describe how the AST is structured, various components provided by
   9 L<SQL::Abstract> for use with this AST, how to manipulate the AST, and various
  10 uses for the AST once it is generated.
  11
  12 =head1 MOTIVATIONS
  13
  14 L<SQL::Abstract> has been in use for many years. Originally created to handle
  15 the where-clause formation found in L<DBIx::Abstract>, it was generalized to
  16 manage the creation of any SQL statement through the use of Perl structures.
  17 Through the beating it received as the SQL generation syntax for L<DBIx::Class>,
  18 various deficiencies were found and a generalized SQL AST was designed. This
  19 document describes that AST.
  20
  21 =head1 GOALS
  22
  23 The goals for this AST are as follows:
  24
  25 =head2 SQL-specific semantics
  26
  27 Instead of attempting to be an AST to handle any form of query, this will
  28 instead be specialized to manage SQL queries (and queries that map to SQL
  29 queries). This means that there will be support for SQL-specific features, such
  30 as placeholders.
  31
  32 =head2 Perl-specific semantics
  33
  34 This AST is meant to be used from within Perl5 only. So, it will take advantage
  35 of as many Perl-specific features that make sense to use. No attempt whatosever
  36 will be made to make this AST work within any other language, including Perl6.
  37
  38 =head2 Whole-lifecycle management
  39
  40 Whether a query is built out of whole cloth in one shot or cobbled together from
  41 several snippets over the lifetime of a process, this AST will support any way
  42 to construct the query. Queries can also be built from other queries, so an
  43 UPDATE statement could be used as the basis for a SELECT statement, DELETE
  44 statement, or even a DDL statement of some kind.
  45
  46 =head2 Dialect-agnostic usage
  47
  48 Even though SQL itself has several ANSI specifications (SQL-92 and SQL-99 among
  49 them), this only serves as a basis for what a given RDBMS will expect. However,
  50 every engine has its own specific extensions and specific ways of handling
  51 common features. The API to the AST will provide ways of expressing common
  52 functionality in a common language.  The emitters (objects that follow the
  53 Visitor pattern) will be responsible for converting that common language into
  54 RDBMS-specific SQL.
  55
  56 =head1 AST STRUCTURE
  57
  58 The AST will be a HoA (hash of arrays). The keys to the hash will be the various
  59 clauses of a SQL statement, plus some metadata keys. All metadata keys will be
  60 identifiable as such by being prefixed with an underscore. All keys will be in
  61 lowercase.
  62
  63 =head2 Metadata keys
  64
  65 These are the additional metadata keys that the AST provides for.
  66
  67 =over 4
  68
  69 =item * _query
  70
  71 This denotes what kind of query this AST should be interpreted as.
  72
  73 =item *
  74
  75 =back
  76
  77 =head2 Structural units
  78
  79 Structural units in the AST are supported by loaded components. L<SQL::Abstract>
  80 provides for the following structural units by default:
  81
  82 =head3 Identifier
  83
  84 This is a (potentially) fully canonicalized identifier for a table or column. Is
  85 is of the structure C< [schema][sep][table][sep]column > or
  86 C< [schema][sep]table >.
  87
  88 In the case of a two-element identifier which could be C< table[sep]column > or
  89 C< schema[sep]table >, context will determine which it is. However, the AST
  90 doesn't care which it is, only that it properly parses.
  91
  92 =head3 Value
  93
  94 A Value is a Perl scalar. It may either be a:
  95
  96 =over 4
  97
  98 =item * String
  99
 100 A String is a quoted series of characters
 101
 102 =item * Number
 103
 104 A Number is an unquoted number in some numeric format
 105
 106 =item * NULL
 107
 108 NULL corresponds to Perl's C<undef>
 109
 110 =item * BindParameter
 111
 112 This corresponds to a value that will be passed in. This value is normally
 113 quoted in such a fashion so as to protect against SQL injection attacks. (q.v.
 114 L<DBI/quote()> for an example.)
 115
 116 =back
 117
 118 =head3
 119
 120 =head3 Function
 121
 122 A Function is anything of the form C< name( arglist ) > where C<name> is a
 123 string and C<arglist> is a comma-separated list of Expressions.
 124
 125 Yes, a Subquery is legal as an argument for many functions. Some example
 126 functions are:
 127
 128 =over 4
 129
 130 =item * C<< IN >>
 131
 132 =item * C<< MAX >>
 133
 134 =item * C<< MIN >>
 135
 136 =item * C<< SUM >>
 137
 138 =back
 139
 140 =head3 Subquery
 141
 142 A Subquery is another AST whose _query metadata parameter is set to "SELECT".
 143
 144 Most places that a Subquery can be used would require a single value to be
 145 returned (single column, single row), but that is not something that the AST can
 146 easily enforce. The single-column restriction can possibly be enforced, but the
 147 single-row restriction is much more difficult and, in most cases, probably
 148 impossible.
 149
 150 Subqueries, when expressed in SQL, must bounded by parentheses.
 151
 152 =head3 Unary Operator
 153
 154 A UnaryOperator takes a single argument on the RHS and is one of the following:
 155
 156 =over 4
 157
 158 =item * C<< NOT >>
 159
 160 =back
 161
 162 =head3 BinaryOperator
 163
 164 A BinaryOperator takes two arguments (one on the LHS and one on the RHS) and is
 165 one of the following:
 166
 167 =over 4
 168
 169 =item * C<< = >>
 170
 171 =item * C<< != >>
 172
 173 =item * C<< > >>
 174
 175 =item * C<< < >>
 176
 177 =item * C<< >= >>
 178
 179 =item * C<< <= >>
 180
 181 =item * C<< IS >>
 182
 183 =item * C<< IS NOT >>
 184
 185 =back
 186
 187 Note that an operator can comprise of what would be multiple tokens in a normal
 188 parsing effort.
 189
 190 =head3 Expression
 191
 192 An expression can be any one of the following:
 193
 194 =over 4
 195
 196 =item * Value
 197
 198 =item * Function
 199
 200 =item * Subquery
 201
 202 =item * UnaryOperator Expression
 203
 204 =item * Expression BinaryOperator Expression
 205
 206 =item * ( Expression )
 207
 208 =back
 209
 210 Parentheses indicate precedence and, in some situations, are necessary for
 211 certain operators.
 212
 213 =head2 SQL clauses
 214
 215 These are all the legal and acceptable clauses within the AST that would
 216 correpsond to clauses in a SQL statement. Not all clauses are legal within a
 217 given RDBMS engine's SQL dialect and some clauses may be required in one and
 218 optional in another. Detecting and enforcing those engine-specific restrictions
 219 is the responsibility of the Visitor object.
 220
 221 The clauses are defined with a yacc-like syntax. The various parts are:
 222
 223 =over 4
 224
 225 =item * :=
 226
 227 This means "defined" and is used to create a new term to be used below.
 228
 229 =item * []
 230
 231 This means optional and indicates that the items within it are optional.
 232
 233 =item * []*
 234
 235 This means optional and repeating as many times as desired.
 236
 237 =item * |
 238
 239 This means alternation. It is a binary operator and indicates that either the
 240 left or right hand sides may be used, but not both.
 241
 242 =item * C<< <> >>
 243
 244 This is a grouping construct. It means that all elements within this construct
 245 are treated together for the purposes of optional, repeating, alternation, etc.
 246
 247 =back
 248
 249 The expected clauses are (name and structure):
 250
 251 =head3 select
 252
 253 This corresponds to the SELECT clause of a SELECT statement.
 254
 255 A select clause is composed as follows:
 256
 257   SelectComponent := Expression [ [ AS ] String ]
 258
 259   SelectComponent
 260   [ , SelectComponent ]*
 261
 262 =head3 tables
 263
 264 This is a list of tables that this clause is affecting. It corresponds to the
 265 FROM clause in a SELECT statement and the INSERT INTO/UPDATE/DELETE clauses in
 266 those respective statements. Depending on the _query metadata entry, the
 267 appropriate clause name will be used.
 268
 269 The tables clause has several RDBMS-specific variations. The AST will support
 270 all of them and it is up to the Visitor object constructing the actual SQL to
 271 validate and/or use what is provided as appropriate.
 272
 273 A table clause is composed as follows:
 274
 275   TableIdentifier := Identifier [ [ AS ] String ]
 276   JoinType := < LEFT|RIGHT [ OUTER ] > | INNER | CROSS
 277
 278   TableIdentifier
 279   [
 280       < , TableIdentifier >
 281     | <
 282         [ JoinType ] JOIN TableIdentifier
 283         [
 284             < USING ( Identifier [ , Identifier ] ) >
 285           | < ON [ ( ] Expression [ , Expression ] [ ) ] >
 286         ]
 287       >
 288   ]*
 289
 290 Additionally, where aliases are provided for in the TableIdentifier, those
 291 aliases must be used as the tablename in subsequent Identifiers that identify a
 292 column of that table.
 293
 294 =head3 where
 295
 296 This corresponds to the WHERE clause in a SELECT, UPDATE, or DELETE statement.
 297
 298 A where clause is composed as follows:
 299
 300   WhereOperator := AND | OR
 301   WhereExpression := Expression | Expression WhereOperator Expression
 302
 303   WhereExpression
 304
 305 =head3 set
 306
 307 This corresponds to the SET clause in an INSERT or UPDATE statement.
 308
 309 A set clause is composed as follows:
 310
 311   SetComponent := Identifier = Expression
 312
 313   SetComponent [ , SetComponent ]*
 314
 315 =head3 columns
 316
 317 This corresponds to the optional list of columns in an INSERT statement.
 318
 319 A columns clause is composed as follows:
 320
 321   ( Identifier [ , Identifier ]* )
 322
 323 =head3 values
 324
 325 This corresponds to the VALUES clause in an INSERT statement.
 326
 327 A values clause is composed as follows:
 328
 329   ( Expression [ , Expression ]* )
 330
 331 If there is a columns clause, the number of entries in the values clause must be
 332 equal to the number of entries in the columns clause.
 333
 334 =head3 orderby
 335
 336 This corresponds to the ORDER BY clause in a SELECT statement.
 337
 338 An orderby clause is composed as follows:
 339
 340   OrderByComponent := XXX-TODO-XXX
 341   OrderByDirection := ASC | DESC
 342
 343   OrderByComponent [ OrderByDirection ]
 344   [ , OrderByComponent [ OrderByDirection ] ]*
 345
 346 =head3 groupby
 347
 348 This corresponds to the GROUP BY clause in a SELECT statement.
 349
 350 An groupby clause is composed as follows:
 351
 352   GroupByComponent := XXX-TODO-XXX
 353
 354   GroupByComponent [ , GroupByComponent ]*
 355
 356 =head3 rows
 357
 358 This corresponds to the clause that is used in some RDBMS engines to limit the
 359 number of rows returned by a query. In MySQL, this would be the LIMIT clause.
 360
 361 A rows clause is composed as follows:
 362
 363   Number [, Number ]
 364
 365 =head3 for
 366
 367 This corresponds to the clause that is used in some RDBMS engines to indicate
 368 what locks are to be taken by this SELECT statement.
 369
 370 A for clause is composed as follows:
 371
 372   UPDATE | DELETE
 373
 374 =head3 connectby
 375
 376 This corresponds to the clause that is used in some RDBMS engines to provide for
 377 an adjacency-list query.
 378
 379 A connectby clause is composed as follows:
 380
 381   Identifier, WhereExpression
 382
 383 =head1 AUTHORS
 384
 385 robkinyon: Rob Kinyon C<< <rkinyon@cpan.org> >>
 386
 387 =head1 LICENSE
 388
 389 You may distribute this code under the same terms as Perl itself.
 390
 391 =cut