The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DBIx-OnlineDDL-0.92
River stage zero No dependents
1 ++
/ DBIx::OnlineDDL::Helper::Base

NAME

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

VERSION

version 0.92

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.

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_triggers_on_table

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

Return true if triggers exist on the given table. This is a fail-safe to make sure the table is trigger-free prior to 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.

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.

AUTHOR

Grant Street Group <developers@grantstreet.com>

LICENSE AND COPYRIGHT

Copyright 2019 Grant Street Group

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0