.. _database_commands_for_transaction_management:

Database Commands for Transaction Management
--------------------------------------------

.. _19.1.1|EKB-1033:


.. important::

   On a Modular Architecture deployment, ``voss`` system specific commands
   can only be run on application nodes and for Unified and Single Node architectures, *not* on database or web proxy type nodes.
  


Commands are available to count, delete and export transactions from the database.
All the commands take a ``<days>`` parameter that indicates transactions tasks are for
transactions *older than* this number of days, counting from the current time.

For transaction **archive** and **delete** commands, 
the user is prompted on the command line to proceed or not.

If the transaction commands fail or are aborted:

* For *all* commands, a notification message is sent. 
* For transaction **archive** and **delete** commands,
  the number of successful transaction deletes are applied.
* For transaction **export** commands, no export file is created.

If transactions are exported, the exported archive file will be in the ``media/txn_archive/`` directory.
Available partition space is checked before any transaction export carried out and reported on.
Estimated export sizes are based on average transaction sizes.
If this directory contains files older than 30 days, an error notification is sent,
with a message to remove these files.

The exported file is of the format *transaction_archive-YYYYMMDD_HHMMSS.gz*, 
where the UTC date stamp is the *current time*, for example: ::

 media/txn_archive/transaction_archive-20190130_110122.gz

The exported ``.gz`` archive file contains a text file with lines of JSON formatted strings of the transactions.

* For suggestions on transaction archiving best practices, also refer to :ref:`transaction_archive_best_practice`.
* For more details on scheduling the transaction archiving to happen automatically, see :ref:`enable_database_schedule`.


.. index:: voss;voss transaction count


* **voss transaction count <days>** - Count the number of transaction entries in the database that
  are older than the number of days specified. When running the commands interactively, this command
  is typically used before deleting or exporting.

  Example:
  
  ::

     $ voss transaction count 11
     167,582



.. index:: voss;voss transaction delete

* **voss transaction delete <days> [limit <number>]** - Delete transaction entries from the database that
  are older than the number of days specified, optionally limiting the number of *oldest* transactions to delete.

  The optional **[limit <number>]** parameter limits the number of transactions deleted and is typically used
  when a large number of transactions are older than the specified number of days
  (using **voss transaction count <days>**), which would impact the time
  to delete transactions. The parameter can then be used to manage the delete transaction time.

  The user is prompted to continue or not.

  Example:

  ::

     $ voss transaction delete 11
     You are about to delete transactions from the system. Do you wish to continue?y
     Available space:    27,219,492 KB
     Estimated space:        25,737 KB
     Deleting 167,582 transactions [###############################################] 100%



.. index:: voss;voss transaction export


* **voss transaction export <days>** - Create an archive file of the transaction entries in the database that
  are older than the number of days specified. No entries are deleted from the database. The export file has the format
  indicated above.

  Example:
  
  ::

     $ voss transaction export 11
     Available space:    27,219,492 KB
     Estimated space:        25,737 KB
     Exporting 167,582 transactions [##############################################] 100%



.. index:: voss;voss transaction archive


* **voss transaction archive <days>** - First create an archive file of and then delete transaction
  entries in the database that are older than the number of days specified. This command 
  therefore combines two commands: **voss transaction export <days>** and **voss transaction delete <days>**.
  The export file has the format indicated above.

  The user is prompted to continue or not.

  Example:
 
  ::

    $ voss transaction archive 11
    You are about to delete transactions from the system. Do you wish to continue?y
    Available space:    27,219,492 KB
    Estimated space:        25,737 KB
    Exporting 167,582 transactions [###############################################] 100%
         Used space:       24,767 KB
    Archive saved to media/txn_archive/transaction_archive-20190130_110122.gz
    Deleting 167,582 transactions [################################################] 100%