Automating the download of the Octopus database (GetDbApp)

Table of contents

Introduction

The GetDB (ESI.Octopus.GetDBApp.exe) program allows to download the Octopus database from a database hosted on our servers. The program can be automated using the Windows Scheduled Tasks to download the database everyday. Note that the Octopus database is in SQL. 

Prerequisites

Before using GetDbApp, you need to have :

  • A server running SQL Server 2014 Standart SP1 as a minimum version.

  • A DB name on that server which can be used to restore the DB. Warning, the program GetDbApp destroys the existing DB if it already exists

  • A shared directory on the SQL server to which GetDbApp will download the backup file from the Octopus server. Ex: (\\MySqlServer\OctopusBackups\).

  • A computer which will execute GetDbApp (included with the Octopus installation).

How does it work?

When GetDB program is executed, the following steps are performed:

  1. Connect to the Octopus server
  2. Download the Octopus DB backup to the shared directory on the SQL server
  3. Disconnect from the Octopus server
  4. Decompress the downloaded file to the shared directory (if necessary)
  5. Connect to the SQL server
  6. Replace the current DB with the newly downloaded DB
  7. Disconnect from the SQL server
  8. Delete the downloaded files (an option exists in the command line to avoid erasing the file, /KeepDownloadedBackup )
NOTE: The backup of the Octopus data is performed every evening. On execution of the program GetDB, so you get a copy of the previous day.

How to use GetDB

GetDB is a "command line" type of program (DOS).  Is is designed to be easily automated (the section for Use GetDB from a command line describes how to automate the GetDBApp execution). 

  • The complete name of the GetDB program is : ESI.Octopus.GetDBApp.exe
  • It is located in the local Octopus directory of your computer (C:\Program Files\Octopus) or in (\%homepath%\AppData\Local\Octopus).
  • Here are some example of where you can find the Octopus folder :
    • For Windows 7 : C:\Users\slevesque\AppData\Local\Octopus
    • For Windows XP : C:\Documents and Settings\Slevesque\Local Settings\Application Data\Octopus

Parameters

There are 6 available parameters, 3 of which are mandatory to execute GetDB :

Mandatory Parameters

  • /Login
    • Octopus username
  • /Password
    • Octopus password
  • /ConfigFilePath
    • Path (including filename) of the configuration file
  • /Team (from version 3.8 only)

    • The number of the team to be updated. By default, the IT team is 1

The next section explains how to prepare the configuration file.

Optional Parameters

  • /KeepDownloadedBackup
    • This parameter allows you to keep the downloaded file (backup) in your shared folder after it was restored on your SQL server. Without this parameter, GetDB will delete it. 
  • /LogFilePath
    • Will move the log file. By default, this file named GetDBApp.log will be located in the Octopus folder, where you find the GetDBApp executable. If you move this file from the Octopus folder, make sure the folder exist (the system cannot create the folder). Also, the path needs to contain the name of the file.
  • /NoRestore
    • This parameter allows to download the file without restoring it.

Operation Log Files

File generated by the execution of the GetDBApp program:

  • GetDBApp.log
    • Log file generated automatically each time the program runs

Configuration File (XML)

The configuration file is a text file which contains the information about the SQL server, the shared folder and other parameters required by the program. This file uses the XML format.

NOTE: Before starting to create the configuration file, be careful not to break the file format by modifying the tags or the file structure. One missing or additional character (for example, a "/", ">", or "<") could make the file useless. Make sure that the specified values are valid. Don't leave any blank spaces before or after the values. If an error occurs with the configuration file, the software will shut itself down without a problem. However, error notifications aren't very clear, so it could be difficult to find errors. A thorough verification of the values is recommended before starting the program.
  • Open the following template in Notepad : GetDBAppConfiguration.txt
  • You need to modify the section highlighted in yellow. The tags are described in the next section.

Tag Description

  • <serverBackupLocationUNC>\\MySqlServer\OctopusBackups</serverBackupLocationUNC>
    • Backup server name
      • Replace \\MySqlServer\OctopusBackups with the name of the shared folder where the backup of the database will be saved
  • <serverName>MySqlServer</serverName>
    • SQL.server name
      • Replace MySqlServer by the name of the server where the database will be restored
  • <databaseName>OctopusDatabase</databaseName>
    • Database name
      • Replace OctopusDatabase by the database name where the Octopus DB will be restored
  • <authenticationMode>sql</authenticationMode>
    • Authentication mode
      • The authenticationMode tag can be integrated. In this case, the username and password tags will not be used. This mode can only be used if it is supported in the SQL server configuration. If this is not the case, then use SQL and make sure that you have the username and password of the database
  • <username>sa</username>
    • SQL user name of the database owner (DB_Owner)
  • <password>password</password>
    • SQL user password.

Execute GetDB from a command line

Note:Before you test GetDB, it is recommended to test the SQL server connection.


To run GetDB, you need to open a DOS prompt and place yourself in the Octopus folder. Then you need to enter the following command line:

ESI.Octopus.GetDBApp.exe /login:system /password:AbCd123 /ConfigFilePath:C:\Program Files\Octopus\GetDBAppConfiguration.xml /team:1

Automate GetDB daily downloads

To automate, refer to the Windows Schedules Tasks article..

Note that the database is available from 4h00 AM (UTC -5:00).

 

Troubleshooting

This section describes the ways to help you troubleshoot issues.

  • RegQueryValueEx() returned error 2, 'The system cannot find the file specified.'
    • This message is part of the normal process of restoring your database.
  • Device dropped.
    • ​This message is part of the normal process of restoring your database.
X
Help us improve our articles








Help us improve our articles