DRAFT 1.1 Migration Guide

This page covers migrating from CollectOSS v1.0 to CollectOSS v1.1. Since this release contains several changes that may affect the configuration of existing instances, we are providing this migration guide with suggestions for how to handle some of the changes.

Schema names

v1.1 has renamed the core database schemas. If you have queries that are hardcoded to relying on the schema names, please rename them as follows:

• augur_data -> data
• augur_operations -> operations

Unfortunately, it is not technically possible to configure CollectOSS to preserve the functioning of both names in order to provide a transition period.

If your deployment has downstream applications relying on hardcoded schemas, we encourage you to update your downstream applications to utilize the postgres schema search path. We recommend setting the search path so that it contains the string data,augur_data, ensuring that any unqualified table queries will first hit data (the new schema name) if it is present, falling back to augur_data (the old name) if it isn't. This also makes the transition easier since it reduces the need to coordinate and deploy updates to multiple applications at the same time.

Note

The data and operations schemas are considered internal to CollectOSS and may be subject to breaking changes. In a future version, we will be introducing a stable schema that will be tested and will become part of our public/stable API commitment.

Environment Variables

CollectOSS v1.1 introduces a new environment variable subsystem that allows the application to read from environment variables that are present with either the new COLLECTOSS_ or the old AUGUR_ prefixes. We recommend you migrate to the new names at your convenience.

Any environment variables that don't have a prefix, such as CONFIG_DATADIR can remain the same.

Config File Naming

CollectOSS v1.1 also changed the name of the primary config file from augur.json to collectoss.json. The config manager will first look for the new file name, falling back to the old one if it cannot be found. This config file, if used, should be located in the directory specified by the CONFIG_DATADIR environment variable.

Docker Entrypoints

Optional: Database rename

This part concerns renaming your database. This is a breaking change for anything that is connected to your database and is completely optional. It is recommended, but not required to perform this step after you have already migrated to collectoss 1.1.

To rename your database:

1. stop collection (using a command like docker stop collectoss-redis-1 collectoss-core-1 collectoss-rabbitmq-1 collectoss-flower-1 collectoss-keyman-1 collectoss-core-1 if your docker compose file was started from a folder called "collectoss")
2. ensure that all connections to the database are disconnected (you may need to create a new database just to connect and issue the following command)
3. run ALTER DATABASE augur RENAME TO collectoss; (or choose your own new name instead of CollectOSS)
4. ensure that the new database name is being supplied to environment variables for collectoss containers (specifically: database, core, and flower)
5. Ensure other downstream applications that connect to your database are updated too, including: the collectoss-monitoring stack (if in use), as well as 8Knot or any other downstream tools connecting to your database for analysis work.