/ 
DBD-libsql-0.06
/ README.md

Actions Status

NAME

DBD::libsql - DBI driver for libsql databases

SYNOPSIS

use DBI;

# Connect to a local libsql server
my $dbh = DBI->connect('dbi:libsql:localhost', '', '', {
    RaiseError => 1,
    AutoCommit => 1,
});

# Connect to Turso with authentication token (recommended approach)
my $dbh = DBI->connect(
    'dbi:libsql:my-db.aws-us-east-1.turso.io',
    '',                    # username (unused)
    'your_turso_token',    # password field used for auth token
    {
        RaiseError => 1,
        AutoCommit => 1,
    }
);

# Alternative: Turso connection with connection attribute
my $dbh = DBI->connect('dbi:libsql:my-db.aws-us-east-1.turso.io', '', '', {
    RaiseError => 1,
    AutoCommit => 1,
    libsql_auth_token => 'your_turso_token',
});

# Create a table
$dbh->do("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");

# Insert data
$dbh->do("INSERT INTO users (name) VALUES (?)", undef, 'Alice');

# Query data
my $sth = $dbh->prepare("SELECT * FROM users WHERE name = ?");
$sth->execute('Alice');
while (my $row = $sth->fetchrow_hashref) {
    print "ID: $row->{id}, Name: $row->{name}\n";
}

$dbh->disconnect;

DESCRIPTION

DBD::libsql is a DBI driver that provides access to libsql databases via HTTP. libsql is a fork of SQLite that supports server-side deployment and remote access.

This driver communicates with libsql servers using the Hrana protocol over HTTP, providing full SQL functionality including transactions, prepared statements, and parameter binding.

FEATURES

DSN FORMAT

The Data Source Name (DSN) format for DBD::libsql uses smart defaults for easy configuration:

dbi:libsql:hostname
dbi:libsql:hostname?scheme=https&port=8443

Smart Defaults

The driver automatically detects the appropriate protocol and port based on the hostname:

Examples

# Turso Database (auto-detected: HTTPS, port 443)
dbi:libsql:hono-prisma-ytnobody.aws-ap-northeast-1.turso.io

# Local development server (auto-detected: HTTP, port 8080) 
dbi:libsql:localhost

# Custom configuration
dbi:libsql:localhost?scheme=http&port=3000
dbi:libsql:api.example.com?scheme=https&port=8443

CONNECTION ATTRIBUTES

Standard DBI connection attributes are supported:

TURSO INTEGRATION

DBD::libsql provides seamless integration with Turso, the managed libsql service.

Authentication

For Turso databases, authentication tokens can be provided via multiple methods (in priority order):

Getting Turso Credentials

1. Install the Turso CLI: https://docs.turso.tech/reference/turso-cli 2. Create a database: turso db create my-database 3. Get the URL: turso db show --url my-database 4. Create a token: turso db tokens create my-database

DEVELOPMENT AND TESTING

Running Tests

Basic tests (no external dependencies):

prove -lv t/

Extended tests (requires turso CLI):

# Install turso CLI first
curl -sSfL https://get.tur.so/install.sh | bash

# Start local turso dev server
turso dev --port 8080 &

# Run integration tests
prove -lv xt/01_integration.t xt/02_smoke.t

Live Turso tests (optional):

export TURSO_DATABASE_URL="libsql://your-db.region.turso.io"
export TURSO_DATABASE_TOKEN="your_token"
prove -lv xt/03_turso_live.t

Test Coverage

The test suite covers:

METHODS

This driver implements the standard DBI interface. All standard DBI methods are supported:

Database Handle Methods

Statement Handle Methods

TRANSACTION SUPPORT

DBD::libsql fully supports transactions through the Hrana protocol:

AutoCommit Mode

By default, AutoCommit is enabled (1), meaning each SQL statement is automatically committed.

# AutoCommit enabled - each statement auto-commits
$dbh->do("INSERT INTO users (name) VALUES ('Alice')");

Manual Transaction Control

Disable AutoCommit to use manual transaction control:

$dbh->{AutoCommit} = 0;  # Start transaction mode
$dbh->do("INSERT INTO users (name) VALUES ('Alice')");
$dbh->do("INSERT INTO users (name) VALUES ('Bob')");
$dbh->commit();  # Commit both inserts

Or use the convenience methods:

$dbh->begin_work();
$dbh->do("INSERT INTO users (name) VALUES ('Alice')");
$dbh->do("INSERT INTO users (name) VALUES ('Bob')");

if ($error) {
    $dbh->rollback();
} else {
    $dbh->commit();
}

ERROR HANDLING

DBD::libsql provides comprehensive error handling:

RaiseError Attribute

Enable automatic error raising (recommended):

my $dbh = DBI->connect($dsn, '', '', {
    RaiseError => 1,
    AutoCommit => 1,
});

Manual Error Checking

my $dbh = DBI->connect($dsn, '', '', { RaiseError => 0 });

my $sth = $dbh->prepare("SELECT * FROM users");
unless ($sth) {
    die "Prepare failed: " . $dbh->errstr;
}

unless ($sth->execute()) {
    die "Execute failed: " . $sth->errstr;
}

Common Error Conditions

PERFORMANCE CONSIDERATIONS

Connection Reuse

Reuse database connections when possible:

# Good: Single connection for multiple operations
my $dbh = DBI->connect($dsn, '', $token);
for my $item (@items) {
    $dbh->do("INSERT INTO table VALUES (?)", undef, $item);
}
$dbh->disconnect();

Prepared Statements

Use prepared statements for repeated queries:

# Good: Prepare once, execute many times
my $sth = $dbh->prepare("INSERT INTO users (name) VALUES (?)");
for my $name (@names) {
    $sth->execute($name);
}
$sth->finish();

Batch Operations

Group operations in transactions for better performance:

$dbh->begin_work();
my $sth = $dbh->prepare("INSERT INTO users (name) VALUES (?)");
for my $name (@names) {
    $sth->execute($name);
}
$sth->finish();
$dbh->commit();

LIMITATIONS

EXAMPLES

Basic Usage

use DBI;

# Connect to local libsql server
my $dbh = DBI->connect('dbi:libsql:localhost', '', '', {
    RaiseError => 1,
    AutoCommit => 1,
});

# Create a table
$dbh->do(q{
    CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE,
        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
    )
});

# Insert data
$dbh->do("INSERT INTO users (name, email) VALUES (?, ?)", 
         undef, 'Alice Johnson', 'alice@example.com');

# Query data
my $sth = $dbh->prepare("SELECT * FROM users WHERE name LIKE ?");
$sth->execute('Alice%');

while (my $row = $sth->fetchrow_hashref) {
    printf "User: %s <%s> (ID: %d)\n", 
           $row->{name}, $row->{email}, $row->{id};
}

$sth->finish();
$dbh->disconnect();

Turso Cloud Database

use DBI;

# Connect to Turso with authentication
my $dbh = DBI->connect(
    'dbi:libsql:my-app.aws-us-east-1.turso.io',
    '',                    # username unused
    $auth_token,           # password field for token
    {
        RaiseError => 1,
        AutoCommit => 1,
    }
);

# Use the database normally
my $sth = $dbh->prepare("SELECT COUNT(*) FROM sqlite_master WHERE type='table'");
$sth->execute();
my ($table_count) = $sth->fetchrow_array();
print "Database has $table_count tables\n";

$dbh->disconnect();

Transaction Example

use DBI;

my $dbh = DBI->connect($dsn, '', $token, { RaiseError => 1 });

eval {
    $dbh->begin_work();
    
    # Insert user
    $dbh->do("INSERT INTO users (name, email) VALUES (?, ?)",
             undef, 'Bob Smith', 'bob@example.com');
    my $user_id = $dbh->last_insert_id('', '', 'users', 'id');
    
    # Insert user profile
    $dbh->do("INSERT INTO profiles (user_id, bio) VALUES (?, ?)",
             undef, $user_id, 'Software developer');
    
    $dbh->commit();
    print "User and profile created successfully\n";
};

if ($@) {
    warn "Transaction failed: $@";
    $dbh->rollback();
}

$dbh->disconnect();

Prepared Statement Example

use DBI;

my $dbh = DBI->connect($dsn, '', $token, { RaiseError => 1 });

# Prepare statement once
my $sth = $dbh->prepare(q{
    INSERT INTO log_entries (level, message, timestamp) 
    VALUES (?, ?, CURRENT_TIMESTAMP)
});

# Execute multiple times with different data
my @log_data = (
    ['INFO', 'Application started'],
    ['DEBUG', 'Database connection established'],
    ['WARN', 'Configuration file not found'],
    ['ERROR', 'Failed to process request'],
);

for my $entry (@log_data) {
    $sth->execute(@$entry);
}

$sth->finish();
print "Inserted " . scalar(@log_data) . " log entries\n";

$dbh->disconnect();

COMPATIBILITY

libsql Server Versions

This driver is compatible with:

Perl Versions

Requires Perl 5.18 or later.

DBI Compliance

Implements DBI specification 1.631+ with the following notes:

DEPENDENCIES

This module requires the following Perl modules:

AUTHOR

ytnobody ytnobody@gmail.com

LICENSE

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

SEE ALSO

libsql and Turso Documentation

Development Tools

Alternative Solutions