DBIx::OnlineDDL::Helper::Base - Private OnlineDDL helper for RDBMS-specific code
version v1.0.0
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.
Points back to the parent DBIx::OnlineDDL. This comes with a bunch of handles to be able to call common methods with fewer keystrokes.
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.
If true, OnlineDDL will call helper methods to adjust FKs bound to child tables.
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.
IS NOT DISTINCT FROM
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.
5.7.33
5.7.33-36-log
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.
($catalog, $schema) = $helper->current_catalog_schema;
Figure out the currently-selected catalog and schema (database name) from the database.
$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.
INSERT...SELECT
BETWEEN ? AND ?
@stmts = $helper->post_connection_stmts;
These are the SQL statements to run right after a $dbh re-connect, typically session variable set statements.
$dbh
$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.
$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.
CREATE TABLE
information_schema
$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.
find_new_identifier
Only used if "dbms_uses_global_fk_namespace" is true.
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.
$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.
$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.
$helper->analyze_table($table_name);
Run the DDL statement to re-analyze the table, typically ANALYZE TABLE.
ANALYZE TABLE
$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.
ALTER TABLE
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.
@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.
@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.
@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.
@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.
Grant Street Group <developers@grantstreet.com>
This software is Copyright (c) 2018 - 2022 by Grant Street Group.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
To install DBIx::OnlineDDL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::OnlineDDL
CPAN shell
perl -MCPAN -e shell install DBIx::OnlineDDL
For more information on module installation, please visit the detailed CPAN module installation guide.