NAME
DBIO::SQLite::Introspect::Tables - Introspect SQLite tables and views
VERSION
version 0.900007
DESCRIPTION
Fetches SQLite table and view metadata from sqlite_master. Skips internal sqlite_* objects and the shadow tables of virtual tables.
The shadow tables matter because sqlite_master gives them away as nothing special: an FTS5 table docs stores itself in docs_config, docs_content, docs_data, docs_docsize and docs_idx, all listed as type = 'table' with names no filter on sqlite_% catches. Carried into the model they become six user tables where there is one, and a diff that drops docs emits a DROP TABLE for each of them. Only the first one works: SQLite removes the shadow tables together with the virtual table, so the five that follow fail with no such table. DBIO::SQLite::Deploy's DDL loop is non-transactional, so the upgrade aborts midway, after the first DROP has already run.
So the shadow tables stay out of the model, and a cascade SQLite performs by itself is never emitted a second time as separate statements. The virtual table itself stays in the model -- it is a user object -- and keeps kind => 'table', which is what sqlite_master reports for it.
METHODS
fetch
my $tables = DBIO::SQLite::Introspect::Tables->fetch($dbh);
Returns a hashref keyed by table name. Each value is a hashref with keys: table_name, kind (table or view), sql (the original CREATE statement from sqlite_master), without_rowid, strict.
without_rowid and strict are 1 when the table's statement carries that option behind the closing parenthesis of its column list -- WITHOUT ROWID, STRICT, both in either order, in any letter case -- and 0 otherwise, for a view and a virtual table always. The words are read at that place only, so a column named strict or a string that holds WITHOUT ROWID sets neither.
sqlite_master stays the source of the names and of every field; PRAGMA table_list (libsqlite 3.37+) is used only as a classifier, to learn which of those names are shadow tables of the main schema.
sqlite_master without a schema prefix is main's alone, so a table living in a database brought in with ATTACH is invisible here. This refuses that case up front rather than describing a database it cannot see: a diff that took this partial model at face value would treat every attached table as missing and emit CREATE TABLE for it in main, shadowing the real, still-populated attached table with a fresh empty one -- silent data loss. See "_refuse_attached_databases".
On a libsqlite older than 3.37 there is no classifier, and this croaks -- but only if the database actually holds a virtual table. Without one there are no shadow tables, so nothing is at stake and the behaviour is exactly what it always was. With one, the shadow tables could only be guessed from their names, and a wrong guess is not a missing feature but the unexecutable DROP chain described above; refusing loudly is the lesser harm.
_refuse_attached_databases
Croaks if the handle carries any ATTACHed database, before a single row of sqlite_master is read.
fetch reads only main's sqlite_master, so tables in an attached database are simply not in the model it returns. Left to run, that partial model is worse than an error: the deploy diff reads the attached tables as missing and emits CREATE TABLE for them in main. The CREATE succeeds, an empty table in main now shadows the populated attached one, and an unqualified SELECT reads the empty copy while the data sits untouched in the attached database -- silent, error-free data loss.
PRAGMA database_list names every schema on the handle and is available in every libsqlite, so no version gate is needed. main and temp are the connection's own schemas, not attachments, and are allowed; anything else is an ATTACH, and the introspection refuses it, naming the attached databases. The model covers the schemas of the connection itself.
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.