One of the ongoing issues with the IRIS system is that, due to the way records are linked in the system, renaming devices is not simple. Usually, custom SQL scripts need to be written to safely rename anything.

The iris_renamer is a Python script designed to make it significantly easier to rename IRIS devices. (It also can be used to identify many records associated with a device.)

The renamer does a global search of all iris and public tables in an IRIS PostgreSQL database for a user-provided device name. It also identifies secondary records (_device_io, camera_preset, comm_link, controller, and others) that reference that device.

It then creates new copies of all the associated records with new record names. It uses the new device name as the name for the new primary device record(s) and generates appropriate associated record names for the new associated records. It then deletes the original records (primary and associated) leaving the 'renamed' records in place.

Note that as a safety precaution, the iris_renamer is currently limited to only being able to rename the following types of devices:

• camera
• dms
• detector
• gate_arm
• gate_arm_array

Other device types can be added as needed. Please contact SRF Consulting if you need to rename other types of IRIS records.

To avoid creating a naming conflict, the renamer will refuse to rename any device TO or FROM a term that's used in any of IRIS's static reference tables.

The current version of the iris_renamer is a beta-release tool, still in early development. We strongly recommend, as a precaution, that you make a backup of your IRIS database before each time you use the renamer.

The following assumes the reader has a basic understanding of how to use Python tools via a command line interface and (for the installation step) a method to edit the script using an ASCII text editor (not a word processor).

To install and run the renamer, you will need to have Python 3 installed on a machine with network access to the IRIS server and the PostgreSQL database for that server. In addition to the default Python 3 libraries, you will also need to have the psycopg2 library installed.

(Optional) Rename the script from iris_renamer_v0.5.py to iris_renamer.py.

If you plan on using the renamer with more than one IRIS server/database, we recommend creating a copy of the script for each server with an "_systemname" suffix on the Python script filename before the ".py".

Open the iris_renamer.py file in a text editor and modify the four variables near the top of the file in the section marked "configuration variables" to match your system.

There are four different commands the renamer can perform. These are each described below.

The following examples assume that the script name is iris_renamer. If you've renamed it to something else, please adjust the commands accordingly.

If your system doesn't recognize "iris_renamer" as a valid command, try adding a .py suffix. If that doesn't work, try adding "python" or "python3" as a prefix followed by a space before the script name.

If there's a space in a device name, use quotes around the device name in the command so that name isn't interpreted as two names.

The '<' and '>' marks in the command examples below are only there to indicate the start and end of that command argument and should not be included in the command.

Command format: iris_renamer -h

Produces a basic list of commands like:

iris_renamer script v0.5 - for localhost
Usage: iris_renamer [-v|-v -v] [-h|-s|-p|-r] oldname [newname]

Options:
  -h, --help     show this help message and exit
  -v, --verbose  show record data, repeat for pretty-print format
  -s, --search   
  -p, --pretest  
  -r, --rename
  -o AOUTPUT, --output=AOUTPUT
                        output queries to the file AOUTPUT

Command format: iris_renamer -s <searchterm>

This command will print out a count of all iris and public records with fields that exactly match the searchterm. This will also include _gps records that are associated with the exact match records.

Adding a verbose flag (-v) to the command will print a compact list of the records it found.

Adding a doubled verbose flag (-v -v) to the command will print a pretty-printed list of the matching records.

This does NOT do wildcard, case-change, or partial matching. The contents of the record's field must match exactly.

Command format: iris_renamer -p <oldname> <newname>

This command will attempt to perform all operations required to rename a device from oldname to newname, but will NOT finalize the changes.

Adding a verbose flag (-v) to the command will print a compact list of the old records and the new records.

Adding a doubled verbose flag (-v -v) to the command will print a pretty-printed list of the old records and the new records.

This can be used to check if a rename operation is likely to work, and what records would be changed without actually changing the database.

Command format: iris_renamer -r <oldname> <newname>

This command will attempt to perform all operations required to rename a device from oldname to newname.

Due to negative side effects of modifying the database WHILE IRIS is running, the irisIpAddress and irisTcpPort variables in the script allow the script to test to see if IRIS is running and (IF they are set properly) will prevent using the RENAME command while IRIS is running.

Adding a verbose flag (-v) to the command will print a compact list of the old records and the new records.

Adding a doubled verbose flag (-v -v) to the command will print a pretty-printed list of the old records and the new records.

NOTE!! If the rename operation fails in some obvious way (i.e. the database refuses to allow all of the necessary insert or delete operations) then NONE of the operations will be performed, and the script will print "OPERATION ABORTED" before exiting.