File Transfer Protocol (FTP) Setup Guide
Follow our setup guide to sync files from an FTP or FTPS server to your destination.
Prerequisites
To connect an FTP or FTPS server to Fivetran, you need:
- An account on an FTP or FTPS server containing files with supported file types and encodings.
- The ability to log in to this account using a password.
Setup instructions
Connect to your server
- In the connection setup form, enter the Destination schema name of your choice.
- Enter the Destination table name.
- Enter your User name.
- Enter your Password.
- Enter the Host Address.
- Enter the Port number.
- (Optional) If you use FTP over SSL (FTPS), set the Secure FTP toggle to ON.
- (Optional) Click Run connection test to validate the connection and your login credentials for the FTP server.
You may choose to skip this intermediate test and continue to the next step. However, if skipped, the test will be automatically performed once your configuration is complete.
Specify file type and format
(Optional) Folder path - Use the folder path to specify a portion of the file system in which you'd like Fivetran to look for files. We examine files under the specified folder and all of its nested subfolders for files we can sync. If you don't provide a prefix, we'll look through the entire file system for files to sync.
(Optional) File Pattern - Use a regular expression as the file pattern to determine if specific files can be synced. The pattern you specify applies to everything under the prefix (base folder path). If you're unsure what regular expression to use, you can leave this field blank, and we'll sync everything under the prefix.
For example, under the prefix you have a folder
data
, which has subfolders,subFolder1
andsubFolder2
. These subfolders have JSON files with the formatreport_03/12/2050.json
. You could use the following regex patterns to decide whether or not to sync specific files:data/.*
matches all files in the data folder, including those in subfolders.data/.*json
matches all JSON files in the data folder, including those in subfolders.data/subFolder2/report_.*\.json
matches all the JSON files in thesubFolder2
folder that have a name that starts with the prefixreport_.
. For example,report_file.json
.report_\d{2}/\d{2}/\d{4}\.json
matches all the JSON files that begin with the prefixreport_
and are followed by a date format ofDD/MM/YYYY
orMM/DD/YYYY
. For example,report_03/12/2050.json
.We recommend that you test your regex.
(Optional) Click Preview Files to validate the file pattern.
You can skip this intermediate test and proceed to the next step. However, if you choose to skip, we will perform this test once you have finished your configuration.
Compression - Use the compression option to choose the compression strategy to decompress files without compression extensions. If your files are compressed but do not have extensions indicating the compression method, you can decompress them according to the selected compression algorithm.
- If all of your compressed files are correctly marked with a matching compression extension (.bz2, .gz, .gzip, .tar, or .zip), you can select infer.
- If you select uncompressed, we do not decompress the files and sync the uncompressed files.
- If you choose a compression format, we decompress every file using the format you select. For example, if you have an automated CSV output system that GZIPs files to save space but saves them without a .gzip extension, you can set this field to GZIP. We will decompress every file that we examine using GZIP.
(Optional) Archive Folder Pattern - Use a regular expression to filter and sync files from archived folders. We sync the files in compressed archives with filenames matching the specified pattern. If there are multiple files within archive (TAR or ZIP) folders, you can use the archive folder pattern to filter file types. For example, if you specify the archive folder pattern as
.*json
, we will sync only the files that end in a .json file extension from the archive folder.This is only used to filter the files within the archived folder.
File Type - We process all files as the selected file type. Use the File Pattern field to select the file extensions you want to sync. If your file type is XML, we load your XML data into the
_data
column without flattening it.If your file type is CSV or TSV then enter the following details:
To access some of the options listed below, set the Enable Advanced Options toggle to ON:
- (Optional) Delimiter - Specify the delimiter used in your CSV file. If your CSV file uses a custom delimiter, replace the default comma
,
with your specific delimiter. For example, if your file is tab-delimited, enter\t
, or if it’s pipe-delimited, enter|
. If you leave this field blank, we’ll attempt to detect the delimiter for each file automatically. However, note that automatic detection may not work in all cases. If your files sync with an incorrect number of columns or use a unique delimiter, consider specifying the delimiter. You can store files with different delimiters in the same folder. For more details on how delimiter inference works, see our documentation. - Quote character - Typically, CSVs use double quotes
"
to enclose a value. Set the toggle to off if you don’t want to use an enclosing character. - Non-Standard escape character - Set the toggle to ON if your CSV generator uses non-standard ways of escaping characters like newline, delimiter, etc. Not standard in CSVs.
- Null Sequence - Set the toggle to ON if your CSVs use a special value indicating null. Specify the value indicating null only if you are sure your CSVs have a null sequence. Typically, CSVs have no native notion of a null character. However, some CSV generators have created one, using characters such as
\N
to represent null. - Skip Header Lines - Use this option to skip over a fixed number of header lines at the beginning of your CSV files. Set the toggle to ON, and then in the Number of skipped header lines field, specify the number of header lines you want to skip.
- Skip Footer Lines - Use this option to skip over a fixed number of footer lines at the end of your CSV files. Set the toggle to ON, and then in the Number of skipped footer lines field, specify the number of footer lines you want to skip.
- Headerless files - Set the toggle to ON if your CSV-generating software doesn't provide a header line. Fivetran can generate generic column names and sync data rows with them.
- Line Separator - Line separators are used in CSV files to separate one row from the next. By default, we use the new line character
\n
as the line separator. If you use a different line separator for your CSV files, replace\n
with your custom line separator.
If your file type is JSON or JSONL, then configure the following:
- JSON Delivery Mode - Use this option to choose how Fivetran should handle your JSON data.
- If you select Packed, we load all your JSON data into the
_data
column without flattening it. - If you select Unpacked, we flatten one level of columns and infer their data types.
- If you select Packed, we load all your JSON data into the
- (Optional) Delimiter - Specify the delimiter used in your CSV file. If your CSV file uses a custom delimiter, replace the default comma
Primary Key used for file process and load - Use this option to let Fivetran know how you'd like to update the files in your destination. When you modify a previously synced file, the option you select determines if we should replace the rows in the destination table or append new rows to the table:
- If you select Upsert file using file name and line number, we will upsert your data using the surrogate primary keys
_file
and_line
. If a file has a unique name, we will sync the data for that file as new data. - If you select Append file using file modified time, we will upsert your files using surrogate primary keys
_file
,_line
, and_modified
. You can track the full history of a file or set of files and your files will have a combination of old and new data or data that is updated periodically. - If you select Upsert file using custom primary key, you can keep the most recent version of every record and your files will have a combination of the old and new data or data that is updated periodically. You can choose the primary keys you want to use after you save and test. For more information, see our documentation.
You can modify the primary keys only if your initial sync fails. If your initial sync is successful, the option to modify the primary keys is not available.
- If you select Upsert file using file name and line number, we will upsert your data using the surrogate primary keys
Error Handling - Use the error handling option to choose how to handle errors in your files. If you know that your files contain some errors, you can choose to skip poorly formatted lines.
- If you select skip, we ignore improperly formatted data within a file, allowing you to sync only valid data.
- If you select fail, we fail the sync with an error on finding any improperly formatted data.
We recommend that you select fail unless you are sure that you have undesirable, malformed data.
You will receive a notification on your Fivetran dashboard if we encounter errors.
(Optional) PGP Encryption Options - Use this option to sync PGP encrypted files. Set the toggle to ON and specify the following:
- PGP Private Key - Upload the PGP secret key as an attachment.
- (Optional) Passphrase - Enter the passphrase you used to generate the key.
- (Optional) Signer's Public Key - Upload the signer's public key as an attachment. This key is used for verifying the files.
For PGP decryption processes, we strictly comply with the RFC4880 standard. We support syncing only base64 encoded files.
Finish Fivetran configuration
Click Save & Test. Fivetran will take it from here.
Fivetran tests and validates the FTP connection. Upon successful completion of the setup tests, you can sync your FTP data to your destination.
Setup tests
Fivetran performs the following FTP connection tests:
The Validating Connection Parameters test validates the username, password, host address, and port number you specified in the setup form.
The Connecting to FTP Server test validates the server credentials you specified in the setup form and checks the accessibility of your FTP server.
The Validating File Pattern Regex test validates the file pattern regex you specified in the setup form. We perform this test only if you specify a regex in the File Pattern field.
The Validating Archive Pattern test validates the archive pattern regex you specified in the setup form. We perform this test only if you specify a regex in the Archive Folder Pattern field.
The Validating EscapeChar test validates the escape character you specified for your CSV files and checks the length of the character, which must not be more than one. We perform this test only if you specify an escape character in the Escape Character field.
The Validating Infer FileType test validates whether
infer
is added as a value in thefile_type
parameter for connections created using the API. We perform this test only if you have set up your connection using the API.The Multi-Character Delimiter Support test validates the length of the delimiter, which must be within 15 characters. We perform this test only if you specify the delimiter for your CSV files in the Delimiter field.
The Finding Matching Files test checks if the connector can successfully retrieve a minimum of one sample file and a maximum of ten sample files based on the configuration you specified in the setup form.
The PGP Support test validates whether the connector can successfully retrieve a minimum of one sample file and a maximum of ten sample files from FTP and decrypt them using the PGP keys you uploaded. We perform this test only if you set the PGP Encryption Options toggle to ON.
The tests may take several minutes to complete.
Related articles
description Connector Overview
settings API Connection Configuration