NAME

Class::ReluctantORM::SQL - Represent SQL Statements

SYNOPSIS

  use Class::ReluctantORM::SQL::Aliases;

  # Insert
  my $insert = Class::ReluctantORM::SQL->new('insert');
  $insert->table(Table->new(table => 'table_name'));

  # TODO DOCS

  $sql->table(Table->new($tb_class);
  $sql->add_input($sql_column);
  $sql->add_output($sql_column);

DESCRIPTION

Represent SQL DML statements (INSERT, SELECT, UPDATE, and DELETE) in an abstract, driver-independent way. Class::ReluctantORM uses this suite of classes to construct each statement that it executes, then passes it to the Driver for rendering and execution. Results are then stored in the SQL object, and may be retrieved directly or inflated into Class::ReluctantORM objects.

Clauses, Relations, and Expressions

The SQL objects are loosely grouped into 4 categories:

Statement - Class::ReluctantORM::SQL

Represents a DML SQL statement, its parameters and bindings, and output columns and fetched values.

Provides a location for the clauses, whether as strings or as objects.

Clauses - Where, From, OrderBy, Limit

Represents major portions of the statement. These clauses are independent objects which are built separately, then attached to the SQL statment object.

Relations - Table, Join, SubQuery

Represents a table-like entity. Relations share a common superclass (Class::ReluctantORM::SQL::Relation), know about their columns, and are used in From clauses.

Expressions - Literal, FunctionCall, Column, Param

Represents an expression, which may be used in numerous locations.

Retrieving and Inflating Results

Some SQL statement objects can have OutputColumn objects associated with them (this includes all SELECT statments, and INSERT and UPDATE statements with RETURNING clauses). As results are retrieved, the values are stored in these OutputColumns.

If the statement is expected to only have one row of results, you can simply do this:

  $driver->run_sql($sql);
  foreach my $oc ($sql->output_columns) {
    # do something with $oc->output_value();
  }

If the statement is expected to return multiple rows, you should register a callback:

  my $handle_fetchrow = sub {
     my $sql = shift;
     foreach my $oc ($sql->output_columns) {
       # do something with $oc->output_value();
     }
  };
  $sql->add_fetchrow_listener($handle_fetchrow);
  $driver->run_sql($sql)

If you are seeking Class::ReluctantORM model objects (like Ships and Pirates), you need to use the inflation facility:

  if ($sql->is_inflatable()) {
     @ships = $sql->inflate();
  } else {
     # Too complex
  }

Parsing Support

Parsing support is provided by the Driver area. See Class::ReluctantORM::Driver.

Non-Parsed SQL Support

If you perform a query with 'parse_sql' false (or set that as a global default, see Class::ReluctantORM - Non-Parsed SQL Support), the SQL object still acts as the data object and provides execution and fetching services. Instead of populating the where attribute (which is expected to be a Where object), populate the raw_where attribute (which is expected to be a string, the SQL WHERE clause).

You may build your SQL object out of a mix of objects and raw SQL, though this is less likely to work.

Support is eventually planned for there to be a rw_from, raw_ordeR_by, raw_group_by, and raw_statement. For now, only raw_where is supported.