DBSchema::DBD(3pm)

💖 DBIx::DBSchema::DBD — the Driver Writer's Guide (aka the base class, aka where the magic starts) 💖

okay bestie, pull up a chair, because this is User Contributed Perl Documentation's finest, and it's literally the driver writer's guide and the base class for DBIx::DBSchema::DBD. it's giving "read this before you write a driver" energy, and honestly? iconic. 🎀

---

✨ SYNOPSIS ✨

so basically, if you ever need the docs again, you just go:

perldoc DBIx::DBSchema::DBD

and if you're out here building your very own driver, the vibe is:

package DBIx::DBSchema::DBD::FooBase
use DBIx::DBSchema::DBD;
@ISA = qw(DBIx::DBSchema::DBD);

like, you inherit from it, you become it, main character energy fr fr. 🦋

---

🌸 DESCRIPTION 🌸

okay so here's the tea, and it's important tea:

your driver should be named DBIx::DBSchema::DBD::DatabaseName, where DatabaseName is literally the same as the DBD:: driver for this database. no notes, that's just the rule. 💅

and drivers should implement the following class methods, bestie. this is the whole to-do list. do not skip any. the way that each one matters… 🔥

• columns CLASS DBI_DBH TABLE — you hand it an active DBI database handle, and it gives you back a listref of listrefs (peep perllol if that's new to you). each inner listref has six elements, in this exact order: column name, column type, nullability, column length, column default, and then a field reserved for driver-specific use. six. count them. 🫶
• column CLASS DBI_DBH TABLE COLUMN — same as columns above, except it returns the listref for a single column. and guess what, you can just inherit from DBIx::DBSchema::DBD to get this function for free. slay, free stuff. 💖
• primary_key CLASS DBI_DBH TABLE — give it an active DBI database handle and it returns the primary key for the specified table. simple as that. 👑
• unique CLASS DBI_DBH TABLE — ⚠️ deprecated method, bestie — for new drivers you want the indices method instead. but okay, the lore: given an active DBI database handle, it returns a hashref of unique indices. the keys of the hashref are index names, and the values are arrayrefs which point a list of column names for each. see "HASHES OF LISTS" in perldsc and DBIx::DBSchema::Index. 💀
• index CLASS DBI_DBH TABLE — also ⚠️ deprecated, same deal, indices is the new one for new drivers. given an active DBI database handle, it returns a hashref of (non-unique) indices. keys are index names, values are arrayrefs pointing to a list of column names for each. see "HASHES OF LISTS" in perldsc and DBIx::DBSchema::Index. 😭
• indices CLASS DBI_DBH TABLE — ✨ the new hotness. given an active DBI database handle, returns a hashref of all indices, both unique and non-unique. the keys of the hashref are index names, and the values are again hashrefs, with these keys:
  • name — index name (yes it's redundant, we know, it's just there)
  • using — optional index method
  • unique — boolean indicating whether or not this is a unique index
  • columns — list reference of column names (or expressions)

(see FS::DBIx::DBSchema::Index)

new drivers, you are advised to implement this method. existing drivers, you are advised to (eventually) provide this method instead of index and unique. no pressure but like… some pressure. 🌈

and for backwards-compatibility with current drivers, the base DBIx::DBSchema::DBD class provides an indices method which uses the old index and unique methods to provide this data. so it's got you, bestie. 🫶

• default_db_catalog — returns the default database catalog for the DBI table_info command. inheriting from DBIx::DBSchema::DBD will provide the default empty string. easy win. ⭐
• default_db_schema — returns the default database schema for the DBI table_info command. inheriting from DBIx::DBSchema::DBD will provide the default empty string. same energy, still a win. ⭐
• constraints CLASS DBI_DBH TABLE — given an active DBI database handle, returns the constraints (currently, foreign keys) for the specified table, as a list of hash references. 📋

each hash reference has the following keys:

• constraint — contraint name (spelled exactly like that in the source, keeping it)
• columns — list refrence of column names (also kept as-is, we don't fix typos around here, we preserve them)
• table — foreign taable name (yep, also exactly as written)
• references — list reference of column names in foreign table
• match — (no description given)
• on_delete — (no description given)
• on_update — (no description given)

• column_callback DBH TABLE_NAME COLUMN_OBJ — optional callback for driver-specific overrides to SQL column definitions. 🎀

should return a hash reference, empty for no action, or with one or more of the following keys defined:

• effective_type — optional type override used during column creation.
• explicit_null — set true to have the column definition declare NULL columns explicitly
• effective_default — optional default override used during column creation.
• effective_local — optional local override used during column creation.

• add_column_callback DBH TABLE_NAME COLUMN_OBJ — optional callback for additional SQL statments to be called when adding columns to an existing table. 🧚

should return a hash reference, empty for no action, or with one or more of the following keys defined:

• effective_type — optional type override used during column creation.
• effective_null — optional nullability override used during column creation.
• sql_after — array reference of SQL statements to be executed after the column is added.

• alter_column_callback DBH TABLE_NAME OLD_COLUMN_OBJ NEW_COLUMN_OBJ — optional callback for overriding the SQL statments to be called when altering columns to an existing table. 🔥

should return a hash reference, empty for no action, or with one or more of the following keys defined:

• sql_alter — alter SQL statement(s) for changing everything about a column. specifying this overrides processing of individual changes (type, nullability, default, etc.). like, it takes over the whole thing, so heads up.
• sql_alter_type — alter SQL statement(s) for changing type and length (there is no default).
• sql_alter_null — alter SQL statement(s) for changing nullability to be used instead of the default.

• column_value_needs_quoting COLUMN_OBJ — optional callback for determining if a column's default value require quoting. returns true if it does, false otherwise. short king of a method. 💅

---

🦋 TYPE MAPPING 🦋

okay so this part is actually so clever. you can define a %typemap array for your driver to map "standard" data types to database-specific types. 🌸

for example, the MySQL TIMESTAMP field has non-standard auto-updating semantics; the MySQL DATETIME type is what other databases and the ODBC standard call TIMESTAMP, so one of the entries in the MySQL %typemap is:

'TIMESTAMP' => 'DATETIME',

another example is the Pg %typemap which maps the standard types BLOB and LONG VARBINARY to the Pg-specific BYTEA:

'BLOB' => 'BYTEA',
'LONG VARBINARY' => 'BYTEA',

make sure you use all uppercase-keys. 🔠 like, literally, uppercase keys only, that's the vibe check.

---

👑 AUTHOR 👑

Ivan Kohler <ivan-dbix-dbschema@420.am>

---

💜 COPYRIGHT 💜

Copyright (c) 2000-2005 Ivan Kohler Copyright (c) 2007-2017 Freeside Internet Services, Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

💀 BUGS 💀

(no bugs listed — honestly a flex)

---

🌈 SEE ALSO 🌈

• DBIx::DBSchema
• DBIx::DBSchema::DBD::mysql
• DBIx::DBSchema::DBD::Pg
• DBIx::DBSchema::Index
• DBI
• DBI::DBD
• perllol
• "HASHES OF LISTS" in perldsc

---

okay and that's the whole page, bestie, you ate it. this was documented by the perl gang, v5.36.0, dated 2022-09-10, and the manual page itself is DBSchema::DBD(3pm). xoxo, go write that driver. 🫶✨🎀