NAME

Duckie - A wrapper and native bindings for DuckDB

SYNOPSIS

use Duckie;
Duckie.new.query('select name from META6.json').rows[0]
# {name => Duckie}

my $db = Duckie.new;
say $db.query("select 1 as the_loneliest_number").column-data(0);
# [1]

with $db.query("select 1 as the_loneliest_number") -> $result {
  say $result.column-data('the_loneliest_number'); # [1]
} else {
  # Errors are soft failures
  say "Failed to run query: $_";
}

# DuckDB can query or import data from CSV or JSON files, HTTP URLs,
# PostgreSQL, MySQL, SQLite databases and more.
my @cols = $db.query('select * from data.csv').columns;
my @rows = $db.query('select * from data.json').rows;

$db.query: q[ attach 'postgres://secret:pw@localhost/dbname' as pg (type postgres)]
$res = $db.query: "select * from pg.my_table"

$db.query("install httpfs");
$db.query("load httpfs");
$res = $db.query: "select * from 'http://example.com/data.csv'";

# Joins between different types are also possible.
$res = $db.query: q:to/SQL/
select *
from pg.my_table one
inner join 'http://example.com/data.csv' csv_data on one.id = csv_data.id
inner join 'data.json' json_data on one.id = json_data.id
SQL

DESCRIPTION

This module provides Raku bindings for DuckDB. DuckDB is a "fast in-process analytical database". It provides an SQL interface for a variety of data sources. Result sets are column-oriented, with a rich set of types that are either inferred, preserved, or explicitly defined. Duckie also provides a row-oriented API.

This module provides two sets of classes.

Duckie::DuckDB::Native is a low-level interface that directly maps to the C API. Note that a number of the function calls there are either deprecated or scheduled for deprecation, so the implementation of the Raku interface favors the more recent mechanisms where possible.
Duckie provides a high level interface that handles things like memory management and native typecasting. While the Raku language supports native types, the results from Duckie do not currently expose them, preferring, for instance to return Integers instead of uint8s, int64s, etc, and using Rats for decimals, and Nums for floats. A future interface may expose native types.

METHODS

method new

method new(
  :$file = ':memory:'
) returns Duckie

Create a new Duckie object. The optional :file parameter specifies the path to a file to use as a database. If not specified, an in-memory database is used. The database is opened and connected to when the object is created.

method query

method query(
    Str $sql
) returns Duckie::Result

Run a query and return a result. If the query fails, a soft failure is thrown.

method DESTROY

method DESTROY() returns Mu

Close the database connection and free resources.

ENVIRONMENT

Set DUCKIE_DEBUG to a true value to enable logging to STDERR.

AUTHOR

Brian Duggan