There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

 / 
DBD-libsql-0.01
/ DBD::libsql

NAME

DBD::libsql - DBI driver for libsql databases

SYNOPSIS

use DBI;

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

# 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

  • HTTP-only communication with libsql servers

  • Full transaction support (BEGIN, COMMIT, ROLLBACK)

  • Prepared statements with parameter binding

  • Session management using baton tokens

  • Proper error handling with Hrana protocol responses

  • Support for all standard DBI methods

DSN FORMAT

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

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

Smart Defaults

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

  • Turso databases (.turso.io domains) - Uses HTTPS on port 443

  • Localhost - Uses HTTP on port 8080

  • Other hosts - Uses HTTPS on port 443

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?schema=http&port=3000
dbi:libsql:api.example.com?schema=https&port=8443

CONNECTION ATTRIBUTES

Standard DBI connection attributes are supported:

  • RaiseError - Enable/disable automatic error raising

  • AutoCommit - Enable/disable automatic transaction commit

  • PrintError - Enable/disable error printing

TURSO INTEGRATION

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

Authentication

For Turso databases, authentication can be provided via:

1. Environment Variables (recommended)
export TURSO_DATABASE_URL="libsql://my-db.aws-us-east-1.turso.io"
export TURSO_DATABASE_TOKEN="your_auth_token"

my $dbh = DBI->connect("dbi:libsql:my-db.aws-us-east-1.turso.io");
2. Connection Attributes
my $dbh = DBI->connect(
    "dbi:libsql:my-db.aws-us-east-1.turso.io",
    "", "",
    {
        turso_token => "your_auth_token",
        RaiseError => 1,
    }
);

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:

  • Hrana protocol communication

  • DBI connection management

  • SQL operations (CREATE, INSERT, SELECT, UPDATE, DELETE)

  • Parameter binding and prepared statements

  • Transaction support (BEGIN, COMMIT, ROLLBACK)

  • Data fetching (fetchrow_arrayref, fetchrow_hashref, fetchrow_array)

  • Error handling and graceful failures

  • Turso authentication and live database operations

LIMITATIONS

  • Only HTTP-based libsql servers are supported

  • Local file databases are not supported

  • In-memory databases are not supported

DEPENDENCIES

This module requires the following Perl modules:

  • DBI

  • LWP::UserAgent

  • HTTP::Request

  • JSON

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