<markdown>
===================
SQL Basics in Solar
===================

The [[Package::Solar_Sql | ]] package contains classes for connecting to and
querying SQL databases. It uses PDO-based adapter classes so that you can
interact with MySQL, PostgreSQL, and SQLite.  (Support for Microsoft SQL and
Oracle is forthcoming.)

All [[Class::Solar_Sql_Adapter | ]] functions are supported on all databases,
so you never need to know the specifics of a particular database backend. If
your Solar_Sql calls work on one database, they should work on all databases
(with some exceptions for how you write your queries; more on that in the
"Portability" section below).

To get started, configure and instantiate a Solar_Sql object using the
available [[Solar_Sql_Adapter::$_config]] keys.

{{code: php
    // load the Solar environment
    require 'Solar.php';
    Solar::start('/path/to/config/Solar.config.php');

    // configure
    $config = array(
        'adapter' => 'Solar_Sql_Adapter_Mysql',
        'host'    => '127.0.0.1',
        'user'    => 'username',
        'pass'    => 'password',
        'name'    => 'database_name',
    );

    // instantiate
    $sql = Solar::factory('Solar_Sql', $config);
}}

If set up your config file like this ...

{{code: php
    $config = array();

    $config['Solar_Sql'] = array(
        'adapter' => 'Solar_Sql_Adapter_Mysql',
        'host'    => '127.0.0.1',
        'user'    => 'username',
        'pass'    => 'password',
        'name'    => 'database_name',
    );
    
    return $config;
}}

... then Solar_Sql will use those as the default configuration keys.

Once you have a Solar_Sql_Adapter object, you can start issuing queries
directly and getting PDOStatement objects in return:

{{code: php
    $sql = Solar::factory('Solar_Sql');
    $pdoStatement = $sql->query('SELECT * FROM table_name');
}}


-------------------
Methods At-A-Glance
-------------------

To quote values so they can be used safely in SQL commands, use ...

* [[Solar_Sql_Adapter::quote()]]

* [[Solar_Sql_Adapter::quoteInto()]]

* [[Solar_Sql_Adapter::quoteMulti()]]


For direct-execution of commands, use...

* [[Solar_Sql_Adapter::query()]]


To fetch results, use ...

* [[Solar_Sql_Adapter::fetchAll()]]

* [[Solar_Sql_Adapter::fetchAssoc()]]

* [[Solar_Sql_Adapter::fetchCol()]]

* [[Solar_Sql_Adapter::fetchOne()]]

* [[Solar_Sql_Adapter::fetchPairs()]]

* [[Solar_Sql_Adapter::fetchPdo()]]

* [[Solar_Sql_Adapter::fetchSql()]]

* [[Solar_Sql_Adapter::fetchValue()]]


To conveniently manipulate data in individual tables, use...

* [[Solar_Sql_Adapter::insert()]]

* [[Solar_Sql_Adapter::update()]]

* [[Solar_Sql_Adapter::delete()]]


For auto-increment values and database-portable sequences, use...

* [[Solar_Sql_Adapter::lastInsertId()]]

* [[Solar_Sql_Adapter::createSequence()]]

* [[Solar_Sql_Adapter::dropSequence()]]

* [[Solar_Sql_Adapter::nextSequence()]]


For database-portable transactions, use...

* [[Solar_Sql_Adapter::begin()]]

* [[Solar_Sql_Adapter::commit()]]

* [[Solar_Sql_Adapter::rollback()]]


For database-portable table/column/index modification, use...

* [[Solar_Sql_Adapter::createTable()]]

* [[Solar_Sql_Adapter::dropTable()]]

* [[Solar_Sql_Adapter::addColumn()]]

* [[Solar_Sql_Adapter::dropColumn()]]

* [[Solar_Sql_Adapter::createIndex()]]

* [[Solar_Sql_Adapter::dropIndex()]]
</markdown>