Altium Vault with Oracle Backend - Restore

This documentation page references Altium Vault, which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace.

 

Parent page: Altium Vault with Oracle Backend

This document is intended for an IT administrator who is restoring their Altium Vault data when the Vault is using an Oracle Database Backend. It contains details about the Altium Vault, it’s restore procedure within the context of using Oracle, important information on system requirements, as well as an example outlining data restoration on the Microsoft Windows platform.

To follow this guide, you should have a general understanding of Oracle database concepts and the windows operating system environment. For more information on how to backup your Altium Vault and its associated Oracle data, see Altium Vault with Oracle Backend - Backup.

Restore Process Overview

Restoring the Altium Vault when using an Oracle backend depends on how your company manages its Oracle Databases. Some companies run Oracle Databases on top of Windows Server Operating Systems, while others have entire Oracle datacenters. The restore process typically involves three steps, as illustrated in the following image.

It is important that the steps be followed in the order they are presented.

High level overview of the Altium Vault and Oracle database restore procedure.High level overview of the Altium Vault and Oracle database restore procedure.

Assumptions Made Throughout this Document

While Oracle configurations can vary from site to site, the following assumptions are made throughout this document:

  1. A full backup of the Altium Vault data and its associated Oracle data dump has been performed as outlined in the document Altium Vault with Oracle Backend - Backup.
  2. An IT administrator performs the restoration. At minimum, the user performing Vault restoration should have administrative rights to the host machine.
  3. A DBA should be present to perform the Oracle data import. At minimum, the user following this guide should have full read/write access to import and modify the company Oracle database.
  4. This guide assumes that there is an existing installation of the Altium Vault, configured and working with an Oracle backend. (See the example section for more details on how to handle an environment where a new Altium Vault is being deployed on a machine and data is imported into that Altium Vault instance).
  5. The Oracle Schema and Oracle application credentials used on source and destination Oracle servers must be the same.

High-level Overview of the Altium Vault Architecture

Similar to other software designed to run on Microsoft Windows, the Altium Vault is a multi-threaded, multi-service server application. Since this document solely focuses on parts of the Altium Vault that may interact with an Oracle Database, the following image is simplified to represent the overall Altium Vault Backend Architecture.

High level overview of the Altium Vault architecture. The Backend Storages of Altium Vault contains most of customer
binary data, while the Windows Services is a collection of supporting services.

This document focuses on the Backend Storages since the data within this block is what gets backed-up, potentially migrated to another machine, then restored either on the same or different machine. Within the Backend Storages, the following items can be found:

  • Databases - contains metadata such as component footprint and schematic symbol association, parameters, file paths, links to component supply chain data sources and more. This information could reside inside a Firebird or Oracle database.
  • File Storage - this File Storage area holds binary data inside the Vault’s SVN repository. This binary data includes information such as PCB and Schematic Project documents, footprints, symbols, Draftsman and other native or non-native Vault documents.

High-level Overview of the Altium Restore Tool

The Altium restore tool is called avbackup.exe. It is the same utility used for backup and restore purposes with the Altium Vault. This is a command line utility that IT administrators can execute to restore their Altium Vault data. avbackup.exe is the same utility used for restore purposes when the Altium Vault is configured with a default Firebird database backend, or when using the Oracle database as a backend.

When using avbackup.exe on a Vault implementation that uses an Oracle Database, administrators should be mindful of the following:

  1. avbackup.exe does NOT support restoring your Vault metadata to an Oracle Database. This feature only works on Altium Vault implementations using a Firebird database backend that was originally auto-configured by the Altium Vault Installer.
  2. avbackup.exe accepts the Zip file that it generates when used as a backup tool. This Zip file contains all Vault binary data.
  3. The Altium Vault must be running. avbackup.exe will automatically shut down all Altium Vault services (including IIS services) during data restoration, then restart all services it shut down, after a successful restore.

Example Restoration of Vault Data with Oracle backend on the Windows Platform

In this example, the instructions also cater to smaller businesses who may not have a dedicated Oracle DBA, but still have the need to restore their Vault and associated Oracle data on their network. The following steps show how a basic backup of Altium Vault and Oracle 11G Express can be restored onto a new machine and Oracle database.

Alternatively, more advanced IT administrators can write batch files that automatically perform the following procedure.

Required Items

  • Pre-existing working instance of the Altium Vault with Oracle backend.
  • Pre-existing folders and data sources:
    • Folders where your Altium Vault and Oracle data will be located need to already exist, and contain a copy of your Vault backup zip file and Oracle .DMP file.
  • Admin access to the Altium Vault Host machine. This is required to properly run the Altium Vault backup Command utility (avbackup.exe).
  • Appropriate DBA access to the Oracle server (i.e. Add user’s Windows account to sysDBA role in Windows environment).

Restore Procedure

  1. If no pre-existing instance of the Altium Vault with Oracle backend has been setup, please read the document Altium Vault with Oracle Backend - Installation for an example of how to setup Altium Vault using Oracle backend on a new machine.
  2. At this point, you should already have an existing instance of the Altium Vault with Oracle - either because of a new, or previous installation.
  3. On the Altium Vault Host machine:
    1. Create a restore folder (it helps to have common file paths, for example: C:\Backups). Place the Vault backup Zip file into this folder.
    2. Restore your Altium Vault data by running the avbackup.exe tool as Admin. The tool is located in the C:\Program Files (x86)\Altium\Altium Vault\Tools\BackupTool folder.
    3. Shut down IIS Vault services, or shutdown the Vault Host machine. This will prevent any unintended write operations to your Oracle Database by Vault services.
For more information on how to use the restore tool, see Oracle Database Vault Backup.

Example restore commands:

  • Command line to navigate to the backup tool directory: cd C:\Program Files (x86)\Altium\Altium Vault\Tools\BackupTool\.
  • Command line to restore the Altium Vault data from the file named 2017_Backup.zip, which is stored in the folder C:\Backups: avbackup restore -z "C:\Backups\2017_Backup.zip" -i "C:\Program Files (x86)\Altium\Altium Vault\LocalVault.ini".
  1. On the Oracle Database Host machine:
    1. Create a restore folder and place the Oracle .dmp file in this folder (it helps to have common file paths, for example: C:\Backups).
    2. Drop/delete existing schema and user account from Oracle database.
The Altium Vault initializes its internal SYSTEM variables and other Vault parameters during installation, then writes that information to the Oracle database. This only occurs during a brand-new installation of the Vault, but not during an upgrade. Because the SYSTEM variables and other Vault parameters may have changed between old and new Vault installation, it is much simpler to delete/drop the existing user account, schema and its data from the Oracle database, and create a new user account with at least the same name as the account that was assigned to the Vault in the source Oracle database . When the .dmp file is imported into the Oracle database, the imported SYSTEM variables and Vault parameters will match those stored inside the Altium Vault backup Zip file.

Dropping an Oracle user account and its associated schema can be achieved as follows. For this example, we'll drop existing user account AVUSER3_0_11 and its associated Schema from an Oracle 11G Database on Microsoft Windows:

  1. Launch a command prompt with Admin privileges.
  2. Stop IIS services if they are present on the Oracle machine using command: net stop WAS, then press Y and enter.
  3. Connect to Oracle DB by launching an SqlPlus session:

sqlplus / as sysdba

shutdown immediate;

startup restrict;

  1. Drop schema associated with Vault (in this example AVUSER3_0_11 is the name of the schema we want to delete):

drop user AVUSER3_0_11 cascade;

  1. re-activate DB normally either by restarting the machine, or using the following commands:

shutdown immediate;

startup;

  1. Create Identical Schema on Oracle Server and assign elevated rights:
    1. Open command line as admin and type:

sqlplus / as sysdba;

CREATE user AVUSER3_0_11 identified by “Altium”;

GRANT ALL PRIVILEGES TO AVUSER3_0_11;

GRANT IMP_FULL_DATABASE TO AVUSER3_0_11;

  1. Alternatively, you can temporarily grant DBA role to this user, import files and then revoke this privileges as shown below:

GRANT DBA TO AVUSER3_0_11;

  1. After successfully importing the DB, revoke the DBA privileges:

revoke DBA from AVUSER3_0_11;

  1. Restore Oracle data (this section assumes that the user account and schemas are both named AVUSER3_0_11 and have password Altium):
    1. Launch command prompt with Admin privileges
    2. Stop IIS Servers using command:

net stop WAS

  1. Import the Oracle Data. An example of an import command is:

imp AVUSER3_0_11/Altium@xe file=c:\Backups\AVUSER3_0_11.dmp log=c:\Backups\AVUSER3_0_11_import.log fromuser=AVUSER3_0_11 touser=AVUSER3_0_11

where,

AVUSER3_0_11 - user that has full privileges on scheme and rights to access the DB.

Altium -  password for Oracle user account associated to the Altium Vault.

xe - network service name of target DB contained in tnsnames.ora.

file = c:\Backups\AVUSER3_0_11.dmp - location of backup.

log = c:\Backups\AVUSER3_0_11_import.log - restore log (optional).

fromuser=AVUSER3_0_11 - owner of the backup scheme.

touser=AVUSER3_0_11 - the new owner of the scheme (if the owners are different, you must create new user with appropriate privileges and roles).

  1. Verify data integrity.
    1. Check tnsname.ora file. You should update the network service name (if you changed DB server).
    2. Validate IIS server settings. Check column “Host name" in bindings in IIS Manager to current. There should be current FQDN of your Vault server.
    3. Check values for the following parameters in C:\Program Files (x86)\Altium\Altium Vault\LocalVault.ini file.
      1. Domain - your name of domain.
      2. WebsiteDomain - FQDN of your Vault server.
      3. DataSourceType=Oracle - if using Oracle DB.
      4. User=AVUSER3_0_11 - owner of the scheme.
      5. Password=Altium - DBA defined user password.
      6. DBLocation=FQDN or ip_address:1521 - address of your DB server.
      7. DatabaseName=xe - current network service name of DB, contained in tnsnames.ora.

Conclusion

Although the aforementioned example includes additional details pertaining to interfacing and manipulating an Oracle Database, there are only three key steps to restoring your Altium Vault data:

  1. Step 1 is to stop the IIS services and Vault IIS Application Pools.
  2. Step 2 is to restore the Altium Vault data.
  3. Step 3 is to restore the Oracle data associated with the Altium Vault.

Performing this procedure in the order described greatly reduces the likelihood of data corruption due to Oracle database and Vault binary data mismatch.

It might be necessary for the DBA to remap tablespaces of the metadata being imported to the Schema assigned to the Altium Vault's Oracle DB account, or the Oracle DB import may not work. Especially if the IMPDP/EXPDP commands were used instead of IMP/EXP to generate the Oracle DB backup.

Example:

  1. Create directory reference, note that this does not create a physical folder on the HDD. Simply a pointer in Oracle memory to that folder. You must first create said folder on the HDD manually, then copy its path to the FOLDERPATH placeholder bellow.
    1. CREATE OR REPLACE DIRECTORY MyDirectoryName AS 'FOLDERPATH’;
  2. drop user ALTIUM cascade;
  3. create user ALTIUM identified by PASSWORD;
  4. grant DBA to ALTIUM;
  5. grant connect, resource, create session to ALTIUM;
  6. impdp ALTIUM/PASSWORD@XE full=y directory=MyDirectoryName dumpfile=DMPFILENAME.DMP logfile=LOGFILENAME.log remap_tablespace=ALTIUM:USERS

 

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
Content