ORDS How-To 05: Manage databases and database versions

1. About this guide

This document is one of a series of How-To guides for the Online Research Database Service (ORDS).

Contents

1.1. Pre-requisites

This How-To assumes that you have already registered to use the ORDS, and have either created or been given access to at least one project containing at least one database.

If this is not the case, please see the earlier guide in this series. These can be accessed via the main ORDS documentation page.

2. Managing your ORDS database

The owner of an ORDS project and project administrators are able to edit database details. The project owner can also delete databases.

These action are performed via the database page. To reach the database page, log in to ORDS, click the name of the project which contains the database you wish to work on, and then click the name of the database itself.

2.1. Editing database details

The Database Details pane is in the top left-hand corner of the database page.

Database Details pane

To make changes to the details (metadata) of your database, click Edit database details.

You will be taken to the Edit Database Details form. The fields here are the same as in the Add Database to Project form – see section 2.2. of How to Build and Structure Databases for details.

When you have finished editing the database details, click Save changes to save your changes.

Alternatively, to abandon any changes you have made, click Cancel.

You will be returned to the database page, and any changes you have made will be visible in the Database Details pane.

2.2. Deleting a database

Deleting a database is also done using the Database Details pane.

Database details pane

To permanently delete a whole ORDS database, including any database versions and datasets associated with the database, click Delete database.

You will be taken to a confirmation page. Please note that deleting a database cannot be undone.

If you are certain you wish to delete the whole database, click Delete. You will be returned to the database page, and should see a message confirming that the database has been successfully deleted.

To return to the database page without deleting the database, click Cancel.

It is possible to delete individual database versions without deleting the whole database. See section 3.5. below for details.

3. Creating and working with database versions

If you are the project owner, or a project administrator, you can also create and delete database versions, and set a test database version to be the main database version.

3.1. ORDS database versions

The ORDS system allows you to have up to three versions of each database. All databases will have a main version: it is also possible to create a milestone version, and/or a test version.

  • The main database version is the primary copy of the database
  • A milestone database version is intended to provide a snapshot of the database as it was at a particular point
  • A test database version is intended to provide a safe environment in which to experiment with changes before implementing these in the main version

At the point when a milestone or test version is created, it will be an exact copy of the main database version at that time. However, after that point, the versions then operate independently: any changes made to the contents or structure of the main version will not affect test or milestone versions, and vice versa.

The contents of tables in milestone and test database versions can be viewed, queried, and edited in exactly the same way as the contents of tables in the main database version. The structure of test and milestone database versions can also be edited in the same way as the structure of a main database version. Please see the other guides in this series for further details.

While only project owners and project administrators can create database versions, other project members can work with any database version in accordance with their permissions level – that is, all members can view and query data, contributors can edit data or add new records, and project owners and administrators can also edit the database structure. (For more details about ORDS roles and permissions, see section 4.1.2. of How to create and manage projects.)

Please note that, at present, it is not possible to export milestone or test database versions. We hope to be able to offer this feature in the future.

3.2. Main database versions

As the name suggests, the main database version is typically the one with which most of the work (adding or editing records, querying, creating datasets, etc.) will be done.

When a database is uploaded to the ORDS, or created using the schema designer, this automatically becomes the main database version.

3.3. Milestone database versions

A milestone database version is intended to provide a snapshot of the database as it was at a particular point. This can be used to enable comparison of past and present versions of the data.

For example, if a pre-existing database is uploaded to the ORDS, a milestone database version might be created to preserve a copy of the data in its original form. The main database version could then be edited as desired and used for day-to-day work, with the milestone version remaining available for reference purposes.

3.3.1. Creating a milestone version

To create a milestone version, go to the appropriate database page. Towards the bottom of the page, you will see three panes, one for each of the three potential database versions.

If there is currently no milestone version for this database, the Main database version information pane will contain a Set as milestone version button.

Database version information panes with Set as milestone version button highlighted

Click this to create a milestone database version. You should see a message confirming that the milestone version has been successfully created.

Three new buttons – View and edit database structure, View, edit, and query data, and Delete – will appear in the Milestone database version information pane.

Additionally, the Set as milestone version button in the Main database version information pane will be replaced by a Create new milestone version button.

Database version information panes after creation of milestone version

3.3.2. Replacing a milestone database version

To replace an existing milestone version with a copy of the current main database, click Create new milestone version.

You will be taken to a confirmation page, where ORDS alerts you to the fact that your existing milestone version will be lost. To continue, click Confirm.

3.4. Test database versions

A test database version is intended to provide a safe environment in which to experiment with changes before implementing these in the main version.

For example, if a major change to the structure of the database is planned, it is best to create a test version and to try the changes here first. If the changes are successful, the test version can be set to be the main database version. Alternatively, the test version can simply be deleted, leaving the main version intact and unchanged.

3.4.1. Creating a test version

To create a test version, go to the appropriate database page. Towards the bottom of the page, you will see three panes, one for each of the three potential database versions.

Database version information panes with Create new test version button highlighted

If there is currently no test version for this database, the Test database version information pane will contain a Create new test version button. Click this to create a test database version. You should see a message confirming that the test version has successfully been created.

Four new buttons – View and edit database structure, View, edit, and query data, Delete, and Make this the main database – will appear in the Test database version information pane.

Additionally, the Create new test version button will move from the Test database version information pane to the Main database version information pane.

Database version information panes after creating test database version

3.4.2. Replacing a test database version

To replace an existing test version with a copy of the current main database, click Create new test version.

You will be taken to a confirmation page, where ORDS alerts you to the fact that your existing test version will be lost. To continue, click Confirm.

3.4.3. Setting a test database version to be the main database version

If you have created a test version, edited it, and are happy with the changes that have been made, you may now wish to make the edited test version into the main database version. To do this, click the Make this the main database button in the Test database version information pane.

Database version information panes with Make this the main database button highlighted

You will be taken to a confirmation page, where ORDS alerts you to the fact that your existing main version will be lost. To continue, click Confirm.

Please note that any changes made to the content or structure of the main database version since the test version was created will be overwritten when the test database version is set to be the new main database version. If you are working collaboratively on a database, we recommend ensuring that all project members are aware of any proposed changes.

The test database version will now be a duplicate of the main database version. You can either keep the test database version (in case you wish to experiment with additional changes, for example), or delete it.

3.5. Deleting database versions

Test or milestone versions can be deleted without affecting any other versions of the same database.

However, if you delete a main database version, any test or milestone versions of that database will be deleted at the same time. (You will be left with an empty database: you can either delete this (see section 2.2. above), or upload or create a new main database version.)

If you wish to keep a test database version but not the main version of the same database, this can be accomplished by setting the test version to be the new main version - see section 3.4.3. above.

When you delete any database version, all datasets associated with that version will also be deleted. It is therefore good practice to check that there are no datasets which ought to be retained before deleting. (See section 3. of How to view, create, and share datasets for details of how to view ORDS datasets.)

To delete a database version, click the Delete button in the appropriate database version information pane.

You will be taken to a confirmation page. Please note that deleting a database version cannot be undone. If you wish to continue, click Confirm. You should see a message confirming that the database version has been successfully deleted.

4. What next?

You may want to have a look at some of the other guides in this series. For a full list, visit the ORDS documentation home page.

You can also find out more about the ORDS service by visiting the ORDS home page, http://ords.ox.ac.uk/. If you have specific queries, you can contact the ORDS help desk by emailing ords@it.ox.ac.uk.

Service area: 

Written by IT Services. Latest revision 11 January 2016