Last Updated: 9/25/2001

A_Transaction

Purpose

License

Description

Dependencies

Limitations

Performance Considerations

To Do

Usage

Class Methods

Instance Methods

Testing

A_Debug Usage

 

Purpose:

Provide transaction support the A_Table class. This allows you to begin a transaction, perform many inserts, updates, and deletes, and commit or rollback the transaction. A single transaction can include inserts, updates, and deletes for many tables. This also includes support for logging all inserts, updates, and deletes to all tables, this is called the transaction log.

 

Description:

The A_Table class uses two btrees. The first btree contains the data and is the primary index for the table, this is also called the primary key or pkey btree. The second btree is called the lock btree or lock file. It is similar to the first btree but is used only for transaction support. In other words, the first btree contains the data in the table and the second btree contains pending (uncommitted) changes to the table. When a transaction is active and data is inserted, updated, or deleted in a table, the data is added to the lock btree (the pkey btree is unchanged). This basically records a change to table and locks the record being inserted, updated, or deleted. When a commit occurs, all data in the lock btree is moved to the first btree. This applies the insert/update/delete to table (the first btree or primary key btree). When a rollback occurs, all pending inserts/updates/deletes for this transaction are removed from the lock btree. Here are the basic rules I following when designing this module in order of their priority:

1. If the system, server process, or transaction fails or crashes, then database and all tables must be in a usable state with no transaction related data.
2. Keep unnecessary writes/updates to a minimum.
3. Allow transaction support to be disable for faster performance when needed.

Two new errors have been created in this module for supporting transactions:

• NotInTransaction - this is raised whenever you attempt to insert, update, or delete and you have not properly created or started a transaction. Transactions are required.
• TransactionError - this raised whenever you attempt to do something in a transaction this illegal. This is also called when you attempt to update a row in a table that is currently being updated in another transaction.

 

Dependencies:

• a_debug.rb - this provides debugging messages for all of my Ruby code. See a_debug.html for more details.
• a_table.rb - this module does not work without the A_Table class.

 

Limitations:

• There is NO support for nested transactions. You can have multiple concurrent transactions but they are distinct and separate transactions.
• This has not been thoroughly test with multi-threads
• If a transaction updates a row in table A and a second transaction attempts to update the same row in table A, the second transaction will raise an error.
• Table and index changes, such as creating and dropping tables and indexes directly affect the database. These are never a part of a transaction and can't be rolled back.

 

Performance Considerations:

• If you want the best possible performance, then disable all options in the trigger. Please note, there are risks associated with doing this. If the transaction fails or the sever crashed, the data may be unusable. I only do this when importing data and restarting the process from scratch is acceptable.

 

To Do:

• Add better support for multiple threads and deadlock errors.

 

 Usage:

# we need to create a table:

cols = []

cols.push(A_Column.new('member_id', 'I', true, nil, '%d > 0', nil, '%3d'))

cols.push(A_Column.new('last_name', 'v32', true, nil, "'%s' != ''", "'%s'.capitalize", '%-12s'))

cols.push(A_Column.new('first_name', 'v32', nil, '', nil, "'%s'.capitalize", '%-12s'))

m = A_Table.new('Membership', cols, 'member_id')

# start a new transaction

t1 = A_Transaction.new

m.insert(t1, %w(member_id last_name first_name), [102, 'Davis', 'josh'])

m.insert(t1, %w(member_id last_name first_name), [103, 'davis', 'michelle'])

# show data inside the transcation

m.each(t1){|data| print " #{data)}\n"}

# show data outside the transcation

m.each{|data| print " #{data)}\n"}

t1.commit

# show data in the table

m.each{|data| print " #{data)}\n"}

m.close

Class Methods:

A_Transaction.in_transaction?(name)

Returns true if the object matching name is part of any transaction. If the object is not part of any transaction then false is returned.

• name - is the name of a table or index that you want to check on.

A_Transaction.log(filename='')

Start, change, or stop the transaction log. The transaction log records every insert, update, and delete to every table. This closes the current log (if it is currently opened) and re-opens it using the new filename. If filename is '' or nil, then log is closed. This closes the transaction log for all transactions. Each transaction can also disable the transaction log for only that transaction.

• filename - the name of the new transaction log. Nil or '' will close the transaction log.

A_Transaction.log_open?()

Returns true if the transaction log is currently open. If the transaction log is not open, then returns false.

A_Transaction.new(transactions_disabled=nil, logging_disabled=nil, triggers_disabled=nil, constraints_disabled=nil, actions_disabled=nil, indexes_disabled=nil)

Creates a new transaction. This starts or begins a transaction. You can disable many features of ArunaDB for better performance when needed within a transaction. As a general rule, I disable these features only when loading tables into the database. The features that you can disable are:

• transactions_disabled - when enabled (the default) inserts, updates, and deletes are written to the lock btree. Inserts, update, and deletes are moved to the pkey btree (put in the table) when the transaction is committed. This allows you rollback a group of inserts, updates, and deletes if one of them fails. Set this to true to disable this feature. When set to true or disabled, all inserts, updates, and deletes are written directly to the pkey btree (directly to the table). When disabled the transaction is faster because it uses a single write to the table, but you can't rollback is something fails.
• logging_disabled - when enabled (the default) every insert, update, and delete to every table is written to the transaction log (provided it has been opened). Set to true to disable logging for this transaction only. You can close the transaction log if you don't want to log any transactions. This is useful when you want to load a table and don't need these inserts logged. When set to true or disabled the transaction is faster because there is no logging but you loose a record of the inserts, updates, and deletes that took place during the transaction. Data is not written to the transaction log until the transaction is committed. In other words, only committed transactions appear in the transaction log.
• triggers_disabled - when enabled (the default) trigger methods are called. Set this to true to disable calling the trigger methods. Triggers are methods that you create and attach to one of size trigger events associated with each table. Triggers allow you to check data, update other pieces of data, and make sure the data is consistent before and after insert, updates and deletes. When set to true or disabled the transaction is faster because the trigger methods are not called but the checking and other updates that occur in the trigger methods are not applied.
• constraints_disabled - when enabled (the default) all column constraints on all columns are checked before every insert and update. Set this to true to disable this feature. See the A_Column class for an explanation of all column constraints. When set to true or disabled, the column constraint checking is disabled. When disabled the transaction is faster because each there is no constraint checking on each row but you could insert incorrect or inappropriate data into your tables.
• actions_disabled - when enabled (the default) all column actions on all columns are called before every insert and update. Set this to true to disable this feature. A column action is an attribute associated with a column that allows you to modify the data as it is inserted into tables. See the A_Column class for an explanation of column methods. When set to true or disabled, the column actions are not performed. When disabled the transaction is faster because the column methods aren't called but you could get unexpected data in your table.
• indexes_disabled - when enabled (the default) all indexes are updated as appropriate when rows are inserted, updated, and deleted. Set this to true to disable the updating of indexes. When set to true or disabled, the indexes are not updated to match the changes in the tables. This will leave your indexes in a state that will not match your tables. When disabled the transaction is faster because the indexes are not updated but you must reload all your indexes when the transaction is completed. If you are doing a lot of inserts, updates, and deletes to a table, it may be faster to disable the indexes, complete the transaction, and reload the indexes associated with this table than performing the inserts, updates, and deletes with the indexes active.

A_Transaction.tlog(type, object_name, data=nil)

This method (and the instance method tlog) is called when writing to the transaction log. This is the only method that writes directly to the transaction log. A time stamp and the Thread name are included in the log. Here is the actual write to the log:

Marshal.dump([Time.new, Thread.get_name, type, object_name, data], @@transaction_log_fp)

• type - I use two letter acronyms to indicate what kind of log this transaction is. Here are the acronyms currently used:
• 'CI' - Changing an Index definition
• 'SI' - System Infomation - this an FYI rather an actual update
• 'CT' - Changing a Table definition
• 'U' - Updating a table
• 'D' - Deleting from a table
• 'I' - Inserting into a table
• 'SL' - Starting the transaction Log
• 'EL' - Enable Logging for this transaction
• 'DL' - Enable Logging for this transaction
• 'ETr'- Enable Triggers
• 'DTr'- Disable Triggers
• 'EI' - Enable Indexes
• 'DI' - Disable Indexes
• 'EC' - Enable column Constraints
• 'DC' - Disable column Constraints
• 'EA' - Enable column Actions
• 'DA' - Disable column Actions
• object_name - the name of the object (table name, index name, view name, etc.) being affected by this update or log.
• data - the actual object being affected (inserted, updated, or deleted) by this update or log.

 

Instance Methods:

actions_disabled()

Returns true if column actions are disabled in this transaction. Returns nil if column actions are enabled.

close()

This closes the transaction. You should not call this method directly. Both commit() and rollback() call this method after the commit and rollback have completed.

commit()

Commits the current transaction. Any pending insert, update, and delete associated with this transaction is actually applied to the table. In other words, any pending insert, update, and delete in the lock btree for each table associated with this transaction is applied to the pkey btree.

constraints_disabled()

Returns true if column constraints are disabled in this transaction. Returns nil if column constraints are enabled.

disable_actions()

Turns off column actions. This allows you to enable and disable actions at any point in a transaction. Column actions can also be disabled when creating a new transaction. See A_Transaction.new() for more information.

disable_constraints()

Turns off column constraint checking. This allows you to enable and disable column constraint checking at any point in a transaction. Column constraint checking can also be disabled when creating a new transaction. See A_Transaction.new() for more information.

disable_logging()

Turns off transaction logging. This allows you to enable and disable transaction logging at any point in a transaction. Transaction logging can also be disabled when creating a new transaction. See A_Transaction.new() for more information.

disable_triggers()

Turns off triggers. This allows you to enable and disable triggers at any point in a transaction. Triggers can also be disabled when creating a new transaction. See A_Transaction.new() for more information.

enable_actions()

Turns on column actions. This allows you to enable and disable actions at any point in a transaction. Column actions can also be enabled when creating a new transaction. See A_Transaction.new() for more information.

enable_constraints()

Turns on column constraint checking. This allows you to enable and disable column constraint checking at any point in a transaction. Column constraint checking can also be enabled when creating a new transaction. See A_Transaction.new() for more information.

enable_logging()

Turns on transaction logging. This allows you to enable and disable transaction logging at any point in a transaction. Transaction logging can also be enabled when creating a new transaction. See A_Transaction.new() for more information.

enable_triggers()

Turns on triggers. This allows you to enable and disable triggers at any point in a transaction. Triggers can also be enabled when creating a new transaction. See A_Transaction.new() for more information.

id()

Returns the id associated with this transaction. Each transaction gets an id assigned to it between 1 and 65530. When transaction id counter grows beyond 65530, it is reset back to 1.

indexes_disabled()

Returns true if indexes are disabled in this transaction. Returns nil if indexes are enabled.

log_open?()

Returns true if the transaction log is opened. Returns nil if the transaction log is not opened.

logging_disabled()

Returns true if transaction logging is disabled in this transaction. Returns nil if transaction logging is enabled.

objects()

Returns a Hash of all objects that are a part of or have been updated in this transaction. The key of the Hash is the name of the object (table name, index name, view name, etc.). The value of the Hash is the object itself. Each object in this Hash must have commit and rollback methods defined because A_Transaction.commit calls the objects commit method for every object in this Hash.

owner()

Returns the name of the Thread that created or owns this transaction.

register_object(name, object)

This method adds this name/object pair to the Hash of objects associated with this transaction. You can call this to have your objects commit/rollback method called when the transaction is committed or rolled back. The insert, update, and delete methods for A_Table call this method to register the table with this transaction when the table is updated.

rollback()

Rolls back the current transaction. Any pending insert, update, and delete associated with this transaction is backed out. In other words, any pending insert, update, and delete is removed from lock btree and is never applied to the table.

tlog(type, object_name, data=nil)

Alias for the class method A_Transaction.tlog(). This the class method for details.

to_s()

Returns a printable string showing the status of this transaction.

transactions_disabled()

Returns true if transactions are disabled in this transaction. Returns nil if transactions are enabled. If disabled, then inserts, updates, and deletes are written directly to the table (the pkey btree).

triggers_disabled()

Returns true if triggers are disabled in this transaction. Returns nil if triggers are enabled.

 

Testing: 

See tst_a_table.rb and tst_a_index.rb

 

A_Debug Usage:

1 - prints high level stuff like turning transaction logging on and off and changing the nature of a transaction

14 - prints information about starting and committing transactions.