SQL::Tr...or::Diff(3)

💖 NAME 💖

This is SQL::Translator::Diff(3), straight from the User Contributed Perl Documentation shelf, bestie — and it’s here to make schema diffs make sense. No cap.

SQL::Translator::Diff — determine differences between two schemas.

---

🌸 DESCRIPTION 🌸

Okay so picture this: it takes two input SQL::Translator::Schemas (or SQL files), compares them, and produces ALTER statements to make them the same. It’s giving “glow-up, but for databases.” 💅

---

✨ SNYOPSIS ✨

Simplest usage, bestie:

use SQL::Translator::Diff;
my $sql = SQL::Translator::Diff::schema_diff($source_schema, 'MySQL', $target_schema, 'MySQL', $options_hash)

OO usage:

use SQL::Translator::Diff;
my $diff = SQL::Translator::Diff->new({
  output_db     => 'MySQL',
  source_schema => $source_schema,
  target_schema => $target_schema,
  %$options_hash,
})->compute_differences->produce_diff_sql;

---

🎀 OPTIONS 🎀

• ignore_index_names — match indexes based on types and fields, ignoring name. Name? Never heard of her.
• ignore_constraint_names — match constraints based on types, fields and tables, ignoring name.
• output_db — which producer to use to produce the output. This is the main-character setting, fr fr.
• case_insensitive — ignore case of table, field, index and constraint names when comparing.
• no_batch_alters — produce each alter as a distinct "ALTER TABLE" statement even if the producer supports the ability to do all alters for a table as one statement. One alter at a time, periodt.
• ignore_missing_methods — if the diff would need a method that is missing from the producer, just emit a comment showing the method is missing, rather than dying with an error.
• sqlt_args — hash of extra arguments passed to "new" in SQL::Translator and the below "PRODUCER FUNCTIONS".

---

👑 PRODUCER FUNCTIONS 👑

The following producer functions should be implemented for completeness. If any of them are needed for a given diff, but not found, an error will be thrown. So yeah, bestie, don’t skip these.

• "alter_create_constraint($con, $args)"
• "alter_drop_constraint($con, $args)"
• "alter_create_index($idx, $args)"
• "alter_drop_index($idx, $args)"
• "add_field($fld, $args)"
• "alter_field($old_fld, $new_fld, $args)"
• "rename_field($old_fld, $new_fld, $args)"
• "drop_field($fld, $args)"
• "alter_table($table, $args)"
• "drop_table($table, $args)"
• "rename_table($old_table, $new_table, $args)" (optional)
• "batch_alter_table($table, $hash, $args)" (optional)

If the producer supports "batch_alter_table", it will be called with the table to alter and a hash, the keys of which will be the method names listed above; values will be arrays of fields or constraints to operate on. In the case of the field functions that take two arguments this will appear as an array reference.

I.e. the hash might look something like the following:

{
  alter_create_constraint => [ $constraint1, $constraint2 ],
  add_field   => [ $field ],
  alter_field => [ [$old_field, $new_field] ]
}

• preprocess_schema($schema) (optional)

preprocess_schema is called by the Diff code to allow the producer to normalize any data it needs to first. For example, the MySQL producer uses this method to ensure that FK constraint names are unique.

Basically any changes that need to be made to produce the SQL file for the schema should be done here, so that a diff between a parsed SQL file and (say) a parsed DBIx::Class::Schema object will be sane.

As an aside: DBIx::Class, for instance, uses the presence of a preprocess_schema function on the producer to know that it can diff between the previous SQL file and its own internal representation. Without this method on the producer it will diff the two SQL files — which is slower, but known to work better on old-style producers. Iykyk.

---

💜 AUTHOR 💜

Original Author(s) unknown.

Refactor/re-write and more comprehensive tests by Ash Berlin "ash@cpan.org".

Redevelopment sponsored by Takkle Inc. Shoutout, sponsorship era. 🫶

---

okay that’s the whole page, bestie! Source/version: perl v5.42.0. Date: 2024-12-12. Footer manual label: SQL::Tr...or::Diff(3). 💅✨