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 AST will provide ways of expressing common functionality in
  52 a common language. The emitters (objects that follow the Visitor pattern) will
  53 be responsible for converting that common language into RDBMS-specific SQL.
  54
  55 =head1 COMPONENTS
  56
  57 There are two major components to SQL::Abstract v2.
  58
  59 =over 4
  60
  61 =item * AST
  62
  63 This is the Abstract Syntax Tree. It is a data structure that represents
  64 everything necessary to construct the SQL statement in whatever dialect the
  65 user requires.
  66
  67 =item * Visitor
  68
  69 This object conforms to the Visitor pattern and is used to generate the SQL
  70 represented by the AST. Each dialect will have a different Visitor object. In
  71 addition, there will be visitors for at least one of the ANSI specifications.
  72
  73 =back
  74
  75 =head1 AST STRUCTURE
  76
  77 The AST will be a HoHo..oH (hash of hash of ... of  hashes). The keys to the
  78 outermost hash will be the various clauses of a SQL statement, plus some
  79 metadata keys. All metadata keys will be identifiable as such by being prefixed
  80 with an underscore. All keys will be in lowercase.
  81
  82 =head2 Metadata keys
  83
  84 These are the additional metadata keys that the AST provides for.
  85
  86 =over 4
  87
  88 =item * _query
  89
  90 This denotes what kind of query this AST should be interpreted as.
  91
  92 =item * _version
  93
  94 This denotes the version of the AST.
  95
  96 =back
  97
  98 =head2 Structural units
  99
 100 Structural units in the AST are supported by loaded components. L<SQL::Abstract>
 101 provides for the following structural units by default:
 102
 103 =head3 Identifier
 104
 105 This is a (potentially) fully canonicalized identifier for a table or column. Is
 106 is of the structure C< [schema][sep][table][sep]column > or
 107 C< [schema][sep]table >.
 108
 109 In the case of a two-element identifier which could be C< table[sep]column > or
 110 C< schema[sep]table >, context will determine which it is. However, the AST
 111 doesn't care which it is, only that it properly parses.
 112
 113 =head3 Value
 114
 115 A Value is a Perl scalar. It may either be a:
 116
 117 =over 4
 118
 119 =item * String
 120
 121 A String is a quoted series of characters
 122
 123 =item * Number
 124
 125 A Number is an unquoted number in some numeric format
 126
 127 =item * NULL
 128
 129 NULL is SQL's NULL and corresponds to Perl's C<undef>.
 130
 131 =item * BindParameter
 132
 133 This corresponds to a value that will be passed in. This value is normally
 134 quoted in such a fashion so as to protect against SQL injection attacks. (q.v.
 135 L<DBI/quote()> for an example.)
 136
 137 =back
 138
 139 =head3
 140
 141 =head3 Function
 142
 143 A Function is anything of the form C< name( arglist ) > where C<name> is a
 144 string and C<arglist> is a comma-separated list of Expressions.
 145
 146 Yes, a Subquery is legal as an argument for many functions. Some example
 147 functions are:
 148
 149 =over 4
 150
 151 =item * C<< IN >>
 152
 153 =item * C<< MAX >>
 154
 155 =item * C<< MIN >>
 156
 157 =item * C<< SUM >>
 158
 159 =back
 160
 161 =head3 Subquery
 162
 163 A Subquery is another AST whose _query metadata parameter is set to "SELECT".
 164
 165 Most places that a Subquery can be used would require a single value to be
 166 returned (single column, single row), but that is not something that the AST can
 167 easily enforce. The single-column restriction can possibly be enforced, but the
 168 single-row restriction is much more difficult and, in most cases, probably
 169 impossible.
 170
 171 Subqueries, when expressed in SQL, must bounded by parentheses.
 172
 173 =head3 Unary Operator
 174
 175 A UnaryOperator takes a single argument on the RHS and is one of the following:
 176
 177 =over 4
 178
 179 =item * C<< NOT >>
 180
 181 =back
 182
 183 =head3 BinaryOperator
 184
 185 A BinaryOperator takes two arguments (one on the LHS and one on the RHS) and is
 186 one of the following:
 187
 188 =over 4
 189
 190 =item * C<< = >>
 191
 192 =item * C<< != >>
 193
 194 =item * C<< > >>
 195
 196 =item * C<< < >>
 197
 198 =item * C<< >= >>
 199
 200 =item * C<< <= >>
 201
 202 =item * C<< IS >>
 203
 204 =item * C<< IS NOT >>
 205
 206 =back
 207
 208 Note that an operator can comprise of what would be multiple tokens in a normal
 209 parsing effort.
 210
 211 =head3 Expression
 212
 213 An expression can be any one of the following:
 214
 215 =over 4
 216
 217 =item * Value
 218
 219 =item * Function
 220
 221 =item * Subquery
 222
 223 =item * UnaryOperator Expression
 224
 225 =item * Expression BinaryOperator Expression
 226
 227 =item * ( Expression )
 228
 229 =back
 230
 231 Parentheses indicate precedence and, in some situations, are necessary for
 232 certain operators.
 233
 234 =head2 SQL clauses
 235
 236 These are all the legal and acceptable clauses within the AST that would
 237 correpsond to clauses in a SQL statement. Not all clauses are legal within a
 238 given RDBMS engine's SQL dialect and some clauses may be required in one and
 239 optional in another. Detecting and enforcing those engine-specific restrictions
 240 is the responsibility of the Visitor object.
 241
 242 The clauses are defined with a yacc-like syntax. The various parts are:
 243
 244 =over 4
 245
 246 =item * :=
 247
 248 This means "defined" and is used to create a new term to be used below.
 249
 250 =item * []
 251
 252 This means optional and indicates that the items within it are optional.
 253
 254 =item * []*
 255
 256 This means optional and repeating as many times as desired.
 257
 258 =item * |
 259
 260 This means alternation. It is a binary operator and indicates that either the
 261 left or right hand sides may be used, but not both.
 262
 263 =item * C<< <> >>
 264
 265 This is a grouping construct. It means that all elements within this construct
 266 are treated together for the purposes of optional, repeating, alternation, etc.
 267
 268 =back
 269
 270 The expected clauses are (name and structure):
 271
 272 =head3 select
 273
 274 This corresponds to the SELECT clause of a SELECT statement.
 275
 276 A select clause is composed as follows:
 277
 278   SelectComponent := Expression [ [ AS ] String ]
 279
 280   SelectComponent
 281   [ , SelectComponent ]*
 282
 283 =head3 tables
 284
 285 This is a list of tables that this clause is affecting. It corresponds to the
 286 FROM clause in a SELECT statement and the INSERT INTO/UPDATE/DELETE clauses in
 287 those respective statements. Depending on the _query metadata entry, the
 288 appropriate clause name will be used.
 289
 290 The tables clause has several RDBMS-specific variations. The AST will support
 291 all of them and it is up to the Visitor object constructing the actual SQL to
 292 validate and/or use what is provided as appropriate.
 293
 294 A table clause is composed as follows:
 295
 296   TableIdentifier := Identifier [ [ AS ] String ]
 297   JoinType := < LEFT|RIGHT [ OUTER ] > | INNER | CROSS
 298
 299   TableIdentifier
 300   [
 301       < , TableIdentifier >
 302     | <
 303         [ JoinType ] JOIN TableIdentifier
 304         [
 305             < USING ( Identifier [ , Identifier ] ) >
 306           | < ON [ ( ] Expression [ , Expression ] [ ) ] >
 307         ]
 308       >
 309   ]*
 310
 311 Additionally, where aliases are provided for in the TableIdentifier, those
 312 aliases must be used as the tablename in subsequent Identifiers that identify a
 313 column of that table.
 314
 315 =head3 where
 316
 317 This corresponds to the WHERE clause in a SELECT, UPDATE, or DELETE statement.
 318
 319 A where clause is composed as follows:
 320
 321   WhereOperator := AND | OR
 322   WhereExpression := Expression | Expression WhereOperator Expression
 323
 324   WhereExpression
 325
 326 =head3 set
 327
 328 This corresponds to the SET clause in an INSERT or UPDATE statement.
 329
 330 A set clause is composed as follows:
 331
 332   SetComponent := Identifier = Expression
 333
 334   SetComponent [ , SetComponent ]*
 335
 336 =head3 columns
 337
 338 This corresponds to the optional list of columns in an INSERT statement.
 339
 340 A columns clause is composed as follows:
 341
 342   ( Identifier [ , Identifier ]* )
 343
 344 =head3 values
 345
 346 This corresponds to the VALUES clause in an INSERT statement.
 347
 348 A values clause is composed as follows:
 349
 350   ( Expression [ , Expression ]* )
 351
 352 If there is a columns clause, the number of entries in the values clause must be
 353 equal to the number of entries in the columns clause.
 354
 355 =head3 orderby
 356
 357 This corresponds to the ORDER BY clause in a SELECT statement.
 358
 359 An orderby clause is composed as follows:
 360
 361   OrderByComponent := XXX-TODO-XXX
 362   OrderByDirection := ASC | DESC
 363
 364   OrderByComponent [ OrderByDirection ]
 365   [ , OrderByComponent [ OrderByDirection ] ]*
 366
 367 =head3 groupby
 368
 369 This corresponds to the GROUP BY clause in a SELECT statement.
 370
 371 An groupby clause is composed as follows:
 372
 373   GroupByComponent := XXX-TODO-XXX
 374
 375   GroupByComponent [ , GroupByComponent ]*
 376
 377 =head3 rows
 378
 379 This corresponds to the clause that is used in some RDBMS engines to limit the
 380 number of rows returned by a query. In MySQL, this would be the LIMIT clause.
 381
 382 A rows clause is composed as follows:
 383
 384   Number [, Number ]
 385
 386 =head3 for
 387
 388 This corresponds to the clause that is used in some RDBMS engines to indicate
 389 what locks are to be taken by this SELECT statement.
 390
 391 A for clause is composed as follows:
 392
 393   UPDATE | DELETE
 394
 395 =head3 connectby
 396
 397 This corresponds to the clause that is used in some RDBMS engines to provide for
 398 an adjacency-list query.
 399
 400 A connectby clause is composed as follows:
 401
 402   Identifier, WhereExpression
 403
 404 =head1 AUTHORS
 405
 406 robkinyon: Rob Kinyon C<< <rkinyon@cpan.org> >>
 407
 408 =head1 LICENSE
 409
 410 You may distribute this code under the same terms as Perl itself.
 411
 412 =cut