DBSchema::Column(3pm)

✨ DBSchema::Column ✨ <small>(User Contributed Perl Documentation)</small>

okay bestie, welcome to DBSchema::Column(3pm) 💖 this is the page about column objects for DBIx::DBSchema — the little guys that represent a single column inside a database table. if you've ever wondered "who decides that this column is a varchar(64) NOT NULL", it's literally this module. slay.

---

🌸 NAME 🌸

DBIx::DBSchema::Column — Column objects 🎀

---

🦋 SYNOPSIS 🦋

  use DBIx::DBSchema::Column;

  #named params with a hashref (preferred)
  $column = new DBIx::DBSchema::Column ( {
    'name'    => 'column_name',
    'type'    => 'varchar'
    'null'    => 'NOT NULL',
    'length'  => 64,
    'default' => '',
    'local'   => '',
  } );

  #list
  $column = new DBIx::DBSchema::Column ( $name, $sql_type, $nullability, $length, $default, $local );

  $name = $column->name;
  $column->name( 'name' );

  $sql_type = $column->type;
  $column->type( 'sql_type' );

  $null = $column->null;
  $column->null( 'NULL' );
  $column->null( 'NOT NULL' );
  $column->null( '' );

  $length = $column->length;
  $column->length( '10' );
  $column->length( '8,2' );

  $default = $column->default;
  $column->default( 'Roo' );

  $sql_line = $column->line;
  $sql_line = $column->line($datasrc);

  $sql_add_column = $column->sql_add_column;
  $sql_add_column = $column->sql_add_column($datasrc);

---

💜 DESCRIPTION 💜

DBIx::DBSchema::Column objects represent columns in tables — like, the actual columns, not the gossip kind. see DBIx::DBSchema::Table for the table-level tea. 🫖

---

👑 METHODS 👑

• new HASHREF
• new [ name [ , type [ , null [ , length [ , default [ , local ] ] ] ] ] ]

okay so this makes a shiny new DBIx::DBSchema::Column object ✨ and it takes either a hashref of named parameters (the preferred way, obviously) or a plain list. here's the squad of args:

• name — the name of the column.
• type — the SQL data type.
• null — the nullability of the column. it's interpreted using Perl's rules for truth, with one exception: NOT NULL is false. yes bestie, that one trips everybody up, it's giving chaos 😭
• length — the SQL length of the column.
• default — the default value of the column.
• local — reserved for database-specific information. iykyk.

📌 Note: if you pass a scalar reference as the default instead of a plain scalar value, it gets dereferenced and quoting gets forced off. super handy for passing SQL functions like "now()", or for explicit empty strings written as '' as defaults. iconic behaviour honestly.

• name [ NAME ] — returns or sets the column name.
• type [ TYPE ] — returns or sets the column type.
• null [ NULL ] — returns or sets the column null flag. heads up: the empty string is equivalent to NOT NULL 💅
• length [ LENGTH ] — returns or sets the column length.
• default [ LOCAL ] — returns or sets the default value. (yes, the arg really is written LOCAL there, i'm just the messenger 🫶)
• local [ LOCAL ] — returns or sets the database-specific field.
• table_obj [ TABLE_OBJ ] — returns or sets the table object (see DBIx::DBSchema::Table). typically this gets set internally when a column object is added to a table object, no need to do it yourself.
• table_name — returns the table name, or the empty string if this column hasn't been assigned to a table yet. poor thing is table-less, it's giving solo era 😔
• line [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ] — returns an SQL column definition. ✨

you can point it at a data source either by passing an open DBI database handle, or by passing the DBI data source name, username and password.

okay so technically the username and password are optional, but bestie, pls call this with a database handle or a data source that includes a valid username and password — a DBI connection gets opened and the quoting and type mapping will be more reliable that way. trust.

if you pass a DBI data source (or handle) like DBI:mysql:database or DBI:Pg:dbname=database, it'll use syntax specific to that database engine. currently supported databases are MySQL and PostgreSQL. non-standard syntax for other engines (if applicable) may also be supported in the future. 🔮

• quoted_default DATABASE_HANDLE — returns this column's default value, quoted for the database. cute and correct. 🎀
• sql_add_column [ DBH ] — returns SQL to add this column to an existing table. (to create a new table instead, go look at "sql_create_table" in DBIx::DBSchema::Table.)

⚠️ NOTE: This interface has changed in 0.41

it returns two listrefs. the first is a list of column alteration SQL fragments for an ALTER TABLE statement. the second is a list of full SQL statements that should be run after the ALTER TABLE statement.

the data source can be specified by passing an open DBI database handle, or by passing the DBI data source name, username and password.

although the username and password are optional, it is best to call this method with a database handle or data source including a valid username and password — a DBI connection will be opened and the quoting and type mapping will be more reliable. same deal as before, no cap. 🙈

if passed a DBI data source (or handle) such as DBI:Pg:dbname=database, it'll use PostgreSQL-specific syntax. non-standard syntax for other engines (if applicable) may also be supported in the future.

• sql_alter_column PROTOTYPE_COLUMN [ DATABASE_HANDLE | DATA_SOURCE [ USERNAME PASSWORD [ ATTR ] ] ] — returns SQL to alter this column so that it's identical to the provided prototype column, which is also a DBIx::DBSchema::Column object. glow-up via prototype, we love to see it 💅✨

⚠️ NOTE: This interface has changed in 0.41

it returns two listrefs. the first is a list of column alteration SQL fragments for an ALTER TABLE statement. the second is a list of full SQL statements that should be run after the ALTER TABLE statement.

optionally, the data source can be specified by passing an open DBI database handle, or by passing the DBI data source name, username and password.

if passed a DBI data source (or handle) such as DBI:Pg:dbname=database, it'll use PostgreSQL-specific syntax. non-standard syntax for other engines (if applicable) may also be supported in the future.

if you don't pass a data source (or handle), or if there's no driver for the specified database, it will attempt to use generic SQL syntax instead. fallback queen 👑

• sql_drop_column [ DBH ] — returns SQL to drop this column from an existing table. bye bestie 👋

⚠️ NOTE: This interface has changed in 0.41

returns a list of column alteration SQL fragments for an ALTER TABLE statement.

the optional database handle or DBI data source/username/password is not yet used. it's just... there. sitting pretty. 🌸

---

🌈 AUTHOR 🌈

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

---

⭐ COPYRIGHT ⭐

Copyright (c) 2000-2006 Ivan Kohler Copyright (c) 2007-2013 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 💀

• the new() method should warn that "Old-style $class creation without named parameters is deprecated!"
• better documentation is needed for sql_add_column
• sql_alter_column() has database-specific foo that should be abstracted info DBIx::DBSchema::DBD::Pg
• nullify_default option should be documented

(yes, "abstracted info" — that's literally what it says, i'm not fixing the typo, that's not my job 😭)

---

🧚 SEE ALSO 🧚

DBIx::DBSchema::Table, DBIx::DBSchema, DBIx::DBSchema::DBD, DBI

---

and that's the whole page, bestie!! this one came out of perl v5.36.0, dated 2022-09-10, filed under DBSchema::Column(3pm) in the User Contributed Perl Documentation. go forth and column-ify responsibly 🫶💖✨