NAME

SQL::Easy - extremely easy access to sql data

VERSION

version 2.0.0

SYNOPSIS

Let image we have db 'blog' with one table:

    CREATE TABLE `posts` (
      `ID` int(10) unsigned NOT NULL AUTO_INCREMENT,
      `dt` datetime NOT NULL,
      `title` VARCHAR(255) NOT NULL,
      PRIMARY KEY (`ID`)
    ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;

    insert INTO `posts` (`dt`, `title`) values
      ('1', '2010-07-14 18:30:31', 'Hello, World!'),
      ('2', '2010-08-02 17:13:35', 'use perl or die')
    ;

Then we we can do some things with SQL::Easy

    use SQL::Easy;

    my $se = SQL::Easy->new(
        database => 'blog',
        user     => 'user',
        password => 'secret',
        host     => '127.0.0.1',           # default '127.0.0.1'
        port     => 3306,                  # default 3306
        connection_check_threshold => 30,  # default 30
    );

    # get scalar
    my $posts_count = $se->get_one('select count(id) from posts');

    # get list
    my ($dt, $title) = $se->get_row(
        'select dt, title from posts where id = ?',
        1,
    );

    # get arrayref
    my $posts = $se->get_data(
        'select dt_post, title from posts order by id',
    );
    # We will get
    #    [
    #        {
    #            'dt_post' => '2010-07-14 18:30:31',
    #            'title' => 'Hello, World!'
    #        },
    #        {
    #            'dt_post' => '2010-08-02 17:13:35',
    #            'title' => 'use perl or die'
    #        }
    #    ];

    my $post_id = $se->insert(
        'insert into images ( dt_post, title ) values ( now(), ? )',
        'My new idea',
    );
    # $post_id is the id of the new row in table

    # Sometimes you don't need the any return value (when you delete or update
    # rows), you only need to execute some sql. You can do it by
    $se->execute(
        'update posts set title = ? where id = ?',
        'JAPH',
        2,
    );

If it passed more than 'connection_check_threshold' seconds between requests the module will check that db connection is alive and reconnect if it went away.

DESCRIPTION

On cpan there are a lot of ORMs. The problem is that sometimes ORM are too complex. You don't need ORM in a simple script with couple requests. ORM is sometimes difficult to use, you need to learn its syntax. From the other hand you already knows SQL language.

SQL::Easy give you easy access to data stored in databases using well known SQL language.

SQL::Easy version numbers uses Semantic Versioning standart. Please visit http://semver.org/ to find out all about this great thing.

METHODS

new

Get: 1) $class 2) $params - hashref with constraction information

Return: 1) object

    my $se = SQL::Easy->new(
        database => 'blog',
        user     => 'user',
        password => 'secret',
        host     => '127.0.0.1',           # default '127.0.0.1'
        port     => 3306,                  # default 3306
        connection_check_threshold => 30,  # default 30
    );

Or, if you already have dbh:

    my $se2 = SQL::Easy->new(
        dbh => $dbh,
    );

For example, if you are woring with Dancer::Plugin::Database you can use this command to create SQL::Easy object:

    my $se3 = SQL::Easy->new(
        dbh => database(),
    );

This is one special parameter `cb_before_execute`. It should recieve callback. This callback is run just before the sql is executed. The callback recieves hash with keys 'sql' and 'bind_variables' that contains the values. The return value of this callback is returned.

    my $se4 = SQL::Easy->new(
        ...
        cb_before_execute => sub {
            my (%params) = @_;

            my $sql = delete $params{sql};
            my $bind_variables = delete $params{bind_variables};

            print $sql . "\n";
            print join("\n", @{$bind_variables}) . "\n";

            return '';
        }
    );

get_dbh

Get: 1) $self

Return: 1) $ with dbi handler

get_one

Get: 1) $self 2) $sql 3) @bind_variables

Return: 1) $ with the first value of request result

get_row

Get: 1) $self 2) $sql 3) @bind_variables

Return: 1) @ with first row in result table

get_col

Get: 1) $self 2) $sql 3) @bind_variables

Return: 1) @ with first column in result table

get_data

Get: 1) $self 2) $sql 3) @bind_variables

Return: 1) $ with array of hashes with the result of the query

Sample usage:

    my $a = $se->get_data('select * from t1');

    print scalar @{$a};         # quantity of returned rows
    print $a->[0]{filename};    # element 'filename' in the first row

    for(my $i = 0; $i <= $#{$a}; $i++) {
        print $a->[$i]{filename}, "\n";
    }

get_tsv_data

Get: 1) $self 2) $sql 3) @bind_variables

Return: 1) $ with tab separated db data

Sample usage:

    print $se->get_tsv_data(
        'select dt_post, title from posts order by id limit 2',
    );

It will output the text below (with the tabs as separators).

    dt_post title
    2010-07-14 18:30:31     Hello, World!
    2010-08-02 17:13:35     use perl or die

insert

Get: 1) $self 2) $sql 3) @bind_variables

Return: 1) $ with id of inserted record

Sub executes sql with bind variables and returns id of inseted record

execute

Get: 1) $self 2) $sql 3) @bind_variables

Return: -

Sub just executes sql that it recieves and returns nothing interesting

CONTRIBUTORS

  • Igor Sverdlov

SOURCE CODE

The source code for this module is hosted on GitHub https://github.com/bessarabov/SQL-Easy

BUGS

Please report any bugs or feature requests in GitHub Issues https://github.com/bessarabov/SQL-Easy

AUTHOR

Ivan Bessarabov <ivan@bessarabov.ru>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Ivan Bessarabov.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.