TeamDesk Knowledge Base & Support

   Home      FAQ      Forum      Idea Exchange      Ask a Question      My Stuff      Help   
  
TeamDesk Backup and Restore Tools
DOWNLOAD LINKS
=========================

Console Tool v3, Intel/AMD 64-bit processors:
-------------------------
Windows: td-win-x64.zip, macOS: td-osx-x64.tar.gz, Linux: td-linux-x64.tar.gz

Console Tool v3, ARM 64-bit processors
-------------------------
Windows: td-win-arm64.zip, macOS: td-osx-x64.tar.gz (please run x64 emulated), Linux: td-linux-arm64.tar.gz

GUI Tools for Windows v3

Backup: tdbackupwin.zip, Restore: tdrestorewin.zip

CHANGELOG
=========================
07/18/2023 - v3.0.0
* Windows tools were mistakenly packed in TGZ format. Now packed with ZIP.

07/03/2023 - v3.0.0
* Cross-platform, zero-dependency, all-in-one console tool
* Import files from URLs
* New --culture option to control locale used to parse and format the data from and to CSV files.

For more information, please check:
https://www.teamdesk.net/blog/whats-new/backup-and-restore-tools-crossplatform/

04/27/2020 - v2.8.1
* Extended list of recognized file extensions

04/06/2019 - v2.8.0
* Ensure new column types won't break the backup/restore

09/25/2018 - v2.7.0
* Enabled TLS 1.1 and TLS1.2 connections

09/25/2018 - v2.6.0
* Fixed tdrestore won't import Location columns
* Fixed tdbackup sometimes writes "filename;revision;guid", not the path to the file
* Changed tdbackup to write path to the attachment file relative to .CSV file

09/17/2018 - v2.5.0
* Date Created/Created By/Last Modified By columns are now included in backup

04/18/2017 - v2.4.1
* Fixed bug with table names containing question mark

01/25/2017 - v2.4.0
* New -x option to exclude table from backup/restore

10/06/2016 - v2.3.1
* Minor changes and fixes in error reporting

06/27/2016 - v2.3.0
* Backup retains last-modified-on-top order of records in CSV files. No changes in restore, simple version bump.

06/09/2016 - v2.2.5
* Ignore non-printable control characters while reading/writing CSV files

11/04/2015 - v2.2.4
* Recover from network loss wherever possible

09/02/2015 - v2.2.3
* Fixed .NET version requirement (tools claimed to run on v4.0 but in fact required v4.5)

06/25/2015 - v2.2.2
* Increased operation timeouts in all tools

06/25/2015 - v2.2.1
* Restore/Win now properly reports problems on an attempt to open .CSV file

06/11/2015 - v2.2.0
* Restore now checks whether the file already exists on a server and skips uploading file's data to improve performance in data roundtrip scenarios.

06/11/2015 - v2.1.0
* tdrestorewin now has an ability to restore from .CSV file directly without a map file.

06/09/2015 - v2.0.1
* Fixed problem backing up files with semicolon in the name
* Fixed folder pattern handling
* Added error/message colorization in console apps

04/06/2015 - v2.0.0
* Initial release

OVERVIEW
=========================

Backup and restore tools provided in two forms – console version (td) is suitable for performing scheduled operations and runs on Windows, macOS and Linux on Intel, AMD and ARM-based 64-bit processors. GUI versions of tools (tdbackupwin.exe, tdrestorewin.exe) are Windows-only, rely on .NET Framework 4.7.2, collect parameters through user interface and run the same process as console version do – the input and output of console and GUI version of a tool is identical.

Backup tool stores the database data in comma-separated (.CSV) files, table by table. In addition it writes tables' structure collected during the backup into text-based .tdbackup file. Next time tool runs, it compares stored structure with actual structure. If structure was not changed, backup requests a list of records in a table and rewrites data file removing deleted records and copying not modified records as-is. Then it requests new and modified records from the server in batches by 500 records and adds them to the file and downloads file attachments. If table information or data file is missing or changed, all records are downloaded and CSV file is written anew. Will the process fail for some reason – due to network error for example, original files are left intact, and the process can be safely repeated again later.

Restore works in opposite direction – it scans the file created by backup, establish the connection between CSV file and its columns and a database table and columns, splits file's records into a batches by 500 records or 20Mb and sends them to server. If some records cannot be inserted or updated (due to validation rules violation, for example), new file is written alongside original data file containing bad record's data and the error description as a last column. Original data file is left intact. You can then analyze error file, fix problems and repeat the process again.

Restore is not limited to operate in pair with backup – the file the structure is stored is text based and has quite simple structure.
* Semicolon at the beginning of the line denotes the comment
* Mappings between file and database are specified in blocks.
* First line denotes correspondence of CSV file to database table specified by its singular name
* Lines next to table map are maps of file's column to a database column
* Empty line denotes the end of the block
* There are two special column mappings:
_ * Star-to-star (* -> *) attempts to match all columns in a file to a database
_ * Column-to-empty (Column ->) ignores file's column (to override mapping created by *->*)

; Sample file

Invoices.csv -> Invoice
Invoice # -> Id
Address -> Address

Items.csv -> Item
Id -> Id
Invoice # -> Invoice

Note: do not modify .tdbackup files directly, rather copy them to a file .txt extension and do all the modifications there. Also, while backup writes column type after database column's name this information is not required for restoration process.

CONSOLE TOOL
=========================

Use td --help to list commands or td <command> --help to list option for the command.

Below are frequently used commands and options:

td backup <url> [options]
td restore <url> [options]

URL – is a REST API endpoint or any URL to your database or simply a database ID; all of forms listed below point to the same application

21995 (database id, https://www.teamdesk.net/secure/api/v2/ is assumed)
https://www.teamdesk.net/secure/api/v2/21995/ (REST API endpoint)
https://www.teamdesk.net/secure/api/21995/service.asmx (SOAP API endpoint)
https://www.teamdesk.net/secure/db/21995/overview.aspx?t=29323 (database URL)

-u=user, --user=user
Required option is either user's email or API token. Restore requires the user to have Manage Data setup privilege.

-p=password, --password=password
If the user is specified via email, specifies user's password. Do not use this option with API token

-f=folder, --folder=folder (backup mode)
Specifies the folder to back up application data to. The folder should not contain backup files from another database.

For the folder name you may use {0:format} to include current date and time to the folder name. Format is the combination of format patterns listed below:

dd or d: The day of the month.
MM or M: The numeric month.
yyyy: The year in four digits.

-f=file-or-folder, --file=file-or-folder (restore mode)
The path to the file that defines mapping between file and its columns and the database table and its columns. If path points to the folder, restore will search for <database-id>.tdbackup file in this folder.

-t=table-name, --table=table-name
The name of the table to backup or restore. You can use this option multiple times, for example:
td backup ... -t=Invoice -t=Item (back up Invoice and Item tables)

-X=table-name, --exclude=table-name
The name of the table to exclude from backup or restore. You can use this option multiple times, for example:
td backup ... -X=Invoice -X=Item (back up everything but Invoice and Item tables)

-v, --verbose
Display progress messages

-b, -break
Normally backup and restore tools attempt error recovery and continue operation whenever possible. This option allows overriding this behavior and bailing out on first error encountered. It might be useful for problem identification.

CSV FILE-RELATED OPTIONS
=========================

-d=char, -delimiter=char
Character to use to separate columns, TAB is default.

--quote=char
Character to use to quote the value containing the delimiter or line break. Double quote is the default.

--linebreak=format
Format of the line break, either CR or LF or CRLF. Latter is the default.

--encoding=encoding
Text encoding name as described here ( http://www.iana.org/assignments/character-sets/character-sets.xhtml ), UTF-8 is the default.
We urge you to delete all CSV files from backup folder prior to changing CSV-related switches.

--culture=locale-name
Affects the way numbers and dates are formatted into and parsed from CSV files.

VERSION v2.8 (OBSOLETE)
=========================
Backup, command-line version: tdbackup.zip
Backup, GUI version: tdbackupwin.zip
Restore, command-line version: tdrestore.zip
Restore, GUI version: tdrestorewin.zip
ID
856
Category
Integration/API
Date Created
4/6/2015 8:02:58 AM
Date Updated
7/18/2023 3:56:06 PM
Related articles
Was this information helpful?
 
Back to Search Results