NAME

DBIO::SQLite - SQLite-specific schema management for DBIO

VERSION

version 0.900007

SYNOPSIS

Schema class

package MyApp::Schema;
use DBIO Schema => -sqlite;

The -sqlite shortcut pins +DBIO::SQLite::Storage as the storage type. It is equivalent to the explicit component form:

package MyApp::Schema;
use DBIO 'Schema';
__PACKAGE__->load_components('SQLite');

Result classes

package MyApp::Schema::Result::Artist;
use DBIO;

__PACKAGE__->table('artist');
__PACKAGE__->add_columns(
  id   => { data_type => 'integer', is_auto_increment => 1 },
  name => { data_type => 'varchar', size => 100 },
);
__PACKAGE__->set_primary_key('id');
__PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD', 'artist_id');

package MyApp::Schema::Result::CD;
use DBIO;

__PACKAGE__->table('cd');
__PACKAGE__->add_columns(
  id        => { data_type => 'integer', is_auto_increment => 1 },
  artist_id => { data_type => 'integer' },
  title     => { data_type => 'varchar', size => 200 },
);
__PACKAGE__->set_primary_key('id');
__PACKAGE__->belongs_to(artist => 'MyApp::Schema::Result::Artist', 'artist_id');

Connecting

my $schema = MyApp::Schema->connect('dbi:SQLite:db/app.db');
$schema->deploy;

my $artist = $schema->resultset('Artist')->create({ name => 'Sonic Youth' });
my @cds    = $artist->cds->all;

The classic use base form is still supported:

package MyApp::Schema;
use base 'DBIO::Schema';
__PACKAGE__->load_components('SQLite');

DESCRIPTION

DBIO::SQLite is the SQLite driver component for DBIO.

When this component is loaded into a schema class, connection() sets "storage_type" in DBIO::Schema to +DBIO::SQLite::Storage, which enables SQLite-specific storage behavior automatically.

METHODS

sqlite_extensions

Get or set the SQLite extensions this schema has.

__PACKAGE__->sqlite_extensions('fts5');
__PACKAGE__->sqlite_extensions('rtree', vec0 => { library => '/opt/sqlite/vec0.so' });
__PACKAGE__->sqlite_extensions(spellfix1 => { class => 'MyApp::DB::Extension::Spellfix' });

The declaration is the list (ADR 0066): an extension is not pulled in by loading a component, and a schema that does not declare fts5 has no FTS5 rules. A name may be followed by a hashref with the keys library and class:

library

The library $dbh->sqlite_load_extension loads into every new connection, a plain non-empty string. SQLite adds the platform's suffix when the file is not found as given. A library that cannot be loaded dies when the connection is set up, naming the extension and the library; a DBD::SQLite without load-extension support dies the same way. The entry point is the one SQLite derives from the file name.

class

The extension class (a DBIO::Extension) of an extension outside the family; it wins over the driver's table. Without it a name of the family (fts5, rtree) gets its class from the fixed table of DBIO::SQLite::Extension, any other name the plain class, which has no rules for the model.

Any other key, an empty hashref, a hashref without a name before it, a library that is not a plain non-empty string and a class that is not a class name croak. The list in list context is the names only, in the order they were declared; the options are "sqlite_extension_options". A new call replaces the list.

sqlite_extension_options

my $options = __PACKAGE__->sqlite_extension_options;   # { vec0 => { library => '/opt/sqlite/vec0.so' } }

The options "sqlite_extensions" declared, a hashref extension name to its options. Only the extensions that gave some are in it. A copy: changing it declares nothing.

connection

Overrides "connection" in DBIO::Schema to force +DBIO::SQLite::Storage as storage_type.

It also registers, with "register_storage_layer" in DBIO::Schema, the storage layer (ADR 0032) that the class of a declared extension names in its storage_layer, ahead of the composition core makes in this method. The classes of the list are loaded and checked for their interface version here, since the layer is chosen before the storage exists; the assertion of their driver waits for the first use of the connection. An extension chooses a layer, never the driver. No class of the family names one.

EXTENSIONS

A SQLite extension lives in the process and not in the file: nothing in the database records that a library was loaded, and every connection loads it again. The extensions a schema has are therefore a list it declares ("sqlite_extensions"), and the driver runs it (ADR 0066 of DBIO core):

__PACKAGE__->sqlite_extensions('fts5', 'rtree');
__PACKAGE__->sqlite_extensions(vec0 => { library => '/opt/sqlite/vec0.so' });

The deploy and the diff keep the shadow tables of FTS5 and R*Tree out of the model ("EXTENSIONS" in DBIO::SQLite::Deploy); a library is loaded into every new connection ("_activate_extensions" in DBIO::SQLite::Storage). A schema that declares no extension is not affected in any way. The classes behind the names are DBIO::SQLite::Extension.

MIGRATION NOTES

SQLite storage and SQLMaker classes were split out of the historical DBIx::Class monolithic distribution:

  • Old: DBIx::Class::Storage::DBI::SQLite

  • New: DBIO::SQLite::Storage

  • Old: DBIx::Class::SQLMaker::SQLite

  • New: DBIO::SQLite::SQLMaker

A schema declares the driver with this component or use DBIO 'Schema', -sqlite; core picks no storage class from the DSN (core ADR 0067).

TESTING

SQLite tests in this distribution use in-memory databases and do not require database credentials.

Offline SQLMaker tests can use DBIO::SQLite::Test or DBIO::Test with:

storage_type => 'DBIO::SQLite::Storage'

Shared tests can also exercise the replicated path with:

replicated   => 1,
storage_type => 'DBIO::SQLite::Storage'

AUTHOR

DBIO & DBIx::Class Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.

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