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