Add $dbh.execute, rework $sth.execute

[rbt]

dbh.execute, unlike dbh.do, returns a statement handle instead of a (sometimes incorrect) row count. This allows for a simple query with parameters to be executed without being prepared first.

I didn't want to change do(), and preferred a bit more naming consistency with sth.execute(). do is removed from documentation but not (yet) deprecated. Feedback is appreciated!

OLD: $dbh.do( 'CREATE TABLE tab (foo text, id int5)' );

my $sth = $dbh.prepare('SELECT foo FROM tab WHERE id = ?'); $sth.execute($id); for $sth.allrows(:array-of-hash) -> $row {}

NEW: $dbh.execute( 'CREATE TABLE tab (foo text, id int5)' );

for $dbh.execute('SELECT foo FROM tab WHERE id = ?', $id).allrows(:array-of-hash) -> $row {}

$dbh.do still exists but it is now undocumented to discourage use and should become deprecated in the near future. do() did not allow statements which has results which made it rather unhelpful. It's main purpose was to bypass prepare() for statements which broke under prepare() such as LOCK TABLE on MySQL.

$sth.execute previously returned a count of the effected rows. Now, for consistency with $dbh.execute, it returns a statement handle to allow chaining of rows, allrows, etc. directly onto the execute result. Fail/exceptions are far better for error handling than the return code was.

NOTE, MySQL for type conversion (such as the JSON example) still requires going through prepare.execute as the result set is handled differently.

Solves #185.

[rbt]

JJ suggested I bump the API, now set to 1.

Also took a look through the first 50 pages of results for Raku code with sth.execute and found an unmaintained package that looked at the return code BUT it's already been replaced by a different package which does it differently and won't be impacted.

[abraxxa]

The naming is fine for me.