Local File System Setup Guide Private Preview

Follow our setup guide to sync files from your local file system to your destination using the Local File System connector.

Prerequisites

Before you set up a Fivetran Local File System connection, verify that:

• Hybrid Deployment Model is configured in your local environment
• your destination is configured to use the Hybrid Deployment Model
• the file system you want to sync is accessible to the Hybrid Deployment Agent
• the files you want to sync are in the supported file formats and encodings

Setup instructions

Configure connection

1. In the connection setup form, enter the Destination schema name of your choice.
2. Enter the Table group name. We combine this with the destination schema to form the Fivetran connection name <destination_schema>.<table_group_name>. This enables you to create multiple connections per destination schema. The Table group name value is used only in Fivetran and does not appear in your destination.

3. In the Destination names field, choose the naming convention you want Fivetran to use for the schemas, tables, and columns in your destination:

   • Fivetran naming: Standardizes the schema, table, and column names in your destination according to the Fivetran naming conventions.
   • Source naming: Preserves the original column names from the source system in your destination. The source naming rules apply only to the column names, while the schema and table names follow the Fivetran naming rules.
   If you want to modify your selection, make sure you do it before you start the initial sync.

Connect

1. Enter your Base folder path.
   • If you are using Hybrid Deployment with Docker or Podman, enter the host filesystem path where your files are accessible. For example, /mnt/nfs-share/reports.
   • If you are using Hybrid Deployment with Kubernetes, enter the name of your PersistentVolumeClaim (PVC), optionally followed by a sub-path within the PVC using the format <pvc-name>:/sub/path. For example, finance-reports-pvc or finance-reports-pvc:/reports/finance.

Configure settings

Format

1. 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 you select XML, we load your XML data into the _data column without flattening it.

   • If you select XLS/XLSX/XLSM, proceed to Configure files to specify the cell reference for your spreadsheet.

   • If you select CSV or TSV, then enter the following details:

     • (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 choose one of 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.

Configure files

1. File Mapping - You can map the files to a destination using the following options:

   Define per table

   • Select Define per table.

   • Click + Add files to specify destination tables and their corresponding file name pattern.

   • Table name - Use names that are unique across all S3 connections within the same destination schema.

   • (Optional) File pattern - Use a regular expression as the file pattern to determine whether to sync specific files. The pattern you specify applies to everything under the prefix (base folder path). If you want to sync everything under the prefix, leave this field blank.

     For example, if under the prefix you have a folder data, which has sub-folders, subFolder1, subFolder2, etc. These sub-folders have JSON files with the format report_03/12/2050.json. 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 the subFolder2 folder that have a name that starts with the prefix report_.. For example, report_file.json.

     • report_\d{2}/\d{2}/\d{4}\.json matches all the JSON files that begin with the prefix report_ and are followed by a date format of DD/MM/YYYY or MM/DD/YYYY. For example, report_03/12/2050.json.

       We recommend that you test your regex.

   • (Optional) Archive File 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. 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.

     You need to configure archive patterns per table. This is useful when an archive folder contains files following different naming patterns, allowing you to route each type to a specific destination table based on its pattern.

     For example, if the archive folder contains test12.json and check12.json, you can configure test.*\.json as archive pattern for Table1 to sync only test12.json to Table1, and check.*\.json for Table2 to sync only check123.json to Table2.

   • If you have selected XLS/XLSX/XLSM as your file type, in the Cell reference for syncs field, enter the cell reference to specify the starting cell for data sync. We use the cell reference to sync all contiguous data starting from that cell in all the spreadsheets matching the name.

   • Click Save.

   Dynamically extract tables

   • Select Dynamically extract tables.
   • Use this option to dynamically extract table names from file paths using a regular expression with a named capture group.
   • Table extraction pattern - Specify a regular expression with a named capture group (?<table>...) to extract the table name from matching file paths.

   For example, if your files follow a naming pattern like 20250101/report/customers.csv, 20250101/report/orders.csv, etc., you can use the pattern \d{8}/report/(?<table>\w+)\.csv. Fivetran will automatically create separate destination tables for each unique table name extracted from the pattern (e.g., customers, orders). To learn more about Dynamic File Mapping, see How to use Dynamic File Mapping?

   We recommend that you test your regex to ensure it correctly captures the table name.

   • By default, we add new tables that we find after the setup to your destination. You can configure this behavior in your Schema change settings.

2. 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.

Additional options

1. Compression - 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.

2. 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 when 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.

3. (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.
   • To support PGP encryption on compressed files, the file name must contain both a valid compression extension and the .pgp encryption extension. For example: sample.csv.zip.pgp — where .zip is the compression extension, and .pgp is the encryption extension.

4. The Hybrid Deployment Agent associated with your destination is pre-selected for the connection. To assign a different agent, click Replace agent, select the agent you want to use, and click Use Agent.

Finish Fivetran configuration

1. Click Save & Test. Fivetran will take it from here and sync data from your file system.

Fivetran tests and validates the Local File System connection. On successful completion of the setup tests, you can sync your data to your destination.

Setup tests

Depending on your configuration, Fivetran performs the following connection tests:

• The Verifying folder path accessibility test checks that the configured Base folder path exists and is readable on the Hybrid Deployment agent.

• (Define per table) The Finding tables test validates that you have specified at least one table in the file mapping configuration.

• (Define per table) The Validating regex file patterns test validates all file pattern regexes you specified in the setup form.

• (Define per table) The Validating regex archive patterns test validates the archive pattern regex. We perform this test only if you specify a regex in the Archive File Pattern field.

• (Dynamically extract tables) The Validating Table extraction pattern test validates the extraction pattern regex and ensures it includes a valid (?<table>...) named capture group.

• The Validating Excel Cell Reference Per Table test validates the cell reference you specified for each table. We perform this test only if you selected XLS/XLSX/XLSM as your file type.

• The Finding matching files test checks if the connection can successfully retrieve sample files. For Define per table, it retrieves up to five sample files per table. For Dynamically extract tables, it retrieves up to three sample files per discovered table (up to 5 tables).

• The Validating escapeChar test validates the escape character you specified for your CSV files and checks that it is exactly one character long. We perform this test only if you specify an escape character in the Escape Character field.

• The Validating file type test validates that infer is not used as a file type for this connector. We perform this test only if you have set up your connection using the API.

• The Validating Multi-Character Delimiter Support test validates that the delimiter does not exceed 15 characters. We perform this test only if you specify a delimiter in the Delimiter field.

• The Validating PGP Support test verifies that the connection can successfully retrieve and decrypt sample files using the PGP keys you uploaded. We perform this test only if you set the PGP Encryption Options toggle to ON.

Related articles

Connector Overview

Schema Information

API Connector Configuration

Documentation Home