/ 
DBIx-OnlineDDL-v1.0.1
River stage zero No dependents
/ DBIx::OnlineDDL::Helper::Base

NAME

DBIx::OnlineDDL::Helper::Base - Private OnlineDDL helper for RDBMS-specific code

VERSION

version v1.0.1

DESCRIPTION

This is a private helper module for any RDBMS-specific code. As a private module, any methods or attributes here are subject to change.

You should really be reading documentation for DBIx::OnlineDDL. The documentation here is mainly to benefit any developers who might want to create their own subclass module for their RDBMS and submit it to us. Or fix bugs with the existing helpers.

PRIVATE ATTRIBUTES

online_ddl

Points back to the parent DBIx::OnlineDDL. This comes with a bunch of handles to be able to call common methods with fewer keystrokes.

PRIVATE CLASS "ATTRIBUTES"

dbms_uses_global_fk_namespace

If true, OnlineDDL will rename the FKs in the new table to make sure they don't conflict, and rename them back after the swap.

child_fks_need_adjusting

If true, OnlineDDL will call helper methods to adjust FKs bound to child tables.

null_safe_equals_op

This is the operator that the DB uses for NULL-safe equals comparisons. It would match this truth table:

   0 <op> 0    --> TRUE
   0 <op> 1    --> FALSE
   0 <op> NULL --> FALSE (instead of NULL)
NULL <op> NULL --> TRUE  (instead of NULL)

The ANSI SQL version is IS NOT DISTINCT FROM, but others RDBMS typically use something less bulky.

mmver

The major/minor version of the currently connected server, converted to "numified" form via version, after parsing out the dotted notation (ie: 5.7.33 instead of 5.7.33-36-log). This allows for version comparisons.

PRIVATE HELPER METHODS

As the base module, all of these methods will use ANSI SQL, since there is no assumption of the type of RDBMS used yet. Some of these methods may just immediately die, as there may not be a (safe) standard way of doing that task.

current_catalog_schema

($catalog, $schema) = $helper->current_catalog_schema;

Figure out the currently-selected catalog and schema (database name) from the database.

insert_select_stmt

$insert_select_stmt = $helper->insert_select_stmt($column_list_str);

Return an INSERT...SELECT statement to copy rows from the old table to the new, in such a way that doesn't cause "duplicate row" errors. This is used by DBIx::BatchChunker for the copy operation, so it will need BETWEEN ? AND ? placeholders.

post_connection_stmts

@stmts = $helper->post_connection_stmts;

These are the SQL statements to run right after a $dbh re-connect, typically session variable set statements.

is_error_retryable

$bool = $helper->is_error_retryable($error);

Returns true if the specified error string (or exception object from DBIC/D:C:R) is retryable. Retryable errors generally fall under the categories of: lock contentions, lost DB connections, and query interruptions.

create_table_sql

$sql = $helper->create_table_sql($table_name);

Get the CREATE TABLE SQL statement for the specified table. This is RDBMS-specific, since information_schema isn't always available and usually doesn't house all of the details, anyway.

rename_fks_in_table_sql

$sql = $helper->rename_fks_in_table_sql($table_name, $sql)
    if $helper->dbms_uses_global_fk_namespace;

Given the CREATE TABLE SQL, return the statement with the FKs renamed. This should use find_new_identifier to find a valid name.

Only used if "dbms_uses_global_fk_namespace" is true.

has_conflicting_triggers_on_table

die if $helper->has_conflicting_triggers_on_table($table_name);

Return true if triggers exist on the given table that would conflict with the operation.

find_new_trigger_identifier

$trigger_name = $helper->find_new_trigger_identifier($trigger_name);

Return a free trigger identifier to use in the new trigger, using the inputted name as a base. This should use find_new_identifier to find a valid name.

modify_trigger_dml_stmts

$helper->modify_trigger_dml_stmts( \%trigger_dml_stmts );

Given the DML SQL statements to be plugged into the triggers, mutate the statements, tailored to the RDBMS. The input is a hashref of SQL statements for the following keys:

replace            # used in the INSERT/UPDATE triggers
delete_for_update  # used in the UPDATE trigger
delete_for_delete  # used in the DELETE trigger

Since it's already a reference, this method will mutate the SQL strings.

analyze_table

$helper->analyze_table($table_name);

Run the DDL statement to re-analyze the table, typically ANALYZE TABLE.

swap_tables

$helper->swap_tables($new_table_name, $orig_table_name, $old_table_name);

Runs the SQL to swap the tables in a safe and atomic manner. The default ANSI SQL solution is to run two ALTER TABLE statements in a transaction, but only if the RDBMS supports transactional DDL.

foreign_key_info

my $sth = $helper->foreign_key_info(
    $pk_catalog, $pk_schema, $pk_table_name,
    $fk_catalog, $fk_schema, $fk_table_name
);

Returns a statement handle in the same manner as a "foreign_key_info" in DBI call. In the default case, this is just that call, but certain implementations may need it to be overloaded or overridden.

remove_fks_from_child_tables_stmts

@stmts = $helper->remove_fks_from_child_tables_stmts if $helper->child_fks_need_adjusting;

Return a list of statements needed to remove FKs from the child tables. These will be run through "dbh_runner_do" in DBIx::OnlineDDL.

Only used if "child_fks_need_adjusting" is true.

rename_fks_back_to_original_stmts

@stmts = $helper->rename_fks_back_to_original_stmts if $helper->dbms_uses_global_fk_namespace;

Return a list of statements needed to rename the FKs back to their original names. These will be run through "dbh_runner_do" in DBIx::OnlineDDL.

Only used if "dbms_uses_global_fk_namespace" is true.

add_fks_back_to_child_tables_stmts

@stmts = $helper->add_fks_back_to_child_tables_stmts if $helper->child_fks_need_adjusting;

Return a list of statements needed to add FKs back to the child tables. These will be run through "dbh_runner_do" in DBIx::OnlineDDL.

Only used if "child_fks_need_adjusting" is true.

post_fk_add_cleanup_stmts

@stmts = $helper->post_fk_add_cleanup_stmts if $helper->child_fks_need_adjusting;

Return a list of clean up statements to run after the FKs are re-added back to the child tables. These will be run through "dbh_runner_do" in DBIx::OnlineDDL.

Only used if "child_fks_need_adjusting" is true. The base method does nothing.

AUTHOR

Grant Street Group <developers@grantstreet.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 - 2024 by Grant Street Group.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)