Connection Parameters
FastBCP requires connection information to access your database. This page covers all connection-related parameters.
Connection Type
Specify the type of database connection driver to use. This parameter determines how FastBCP connects to your database.
./FastBCP \
...
--connectiontype mssql \
...
Syntax:
- Short form:
-C "connection_type" - Long form:
--connectiontype "connection_type"
Available Connection Types:
| Connection Type | Description |
|---|---|
adbc_mssql | Microsoft SQL Server via ADBC (Arpe.io ADBC FastDriver) - 2x faster for Parquet exports |
adbc_pgsql | PostgreSQL via ADBC (Arpe.io ADBC FastDriver) - ultra-fast Parquet exports |
adbc_oracle | Oracle via ADBC (Arpe.io ADBC FastDriver) - ultra-fast Parquet exports |
adbc_netezza | Netezza / IBM NPS via ADBC (embedded ArpeNetezza driver) - no NZdotNET needed, works with IBM Cloud NPS |
adbc_teradata | Teradata via ADBC (embedded ArpeTeradata driver) - TLS logon needs no Teradata client software |
backup_mssql | SQL Server full and differential backup files (.bak) read directly, without restoring them (embedded ArpeMSBackup ADBC driver) - see SQL Server backup files |
backup_rman | Oracle RMAN backup sets, full and incremental, read directly, without Oracle and without restoring them (embedded ArpeOraBackup ADBC driver) - see Oracle RMAN backup sets |
clickhouse | ClickHouse database |
hana | SAP HANA database |
mssql | Microsoft SQL Server (default) |
mysql | MySQL/MariaDB database |
nzsql | IBM Netezza |
odbc | Generic ODBC connection |
oledb | Generic OLE DB connection |
oraodp | Oracle Data Provider |
pgcopy | PostgreSQL with COPY protocol |
pgsql | PostgreSQL standard connection |
teradata | Teradata database |
The ADBC FastDriver connectors (adbc_mssql, adbc_pgsql, adbc_oracle, adbc_netezza, adbc_teradata, backup_mssql, backup_rman) are available on Windows x64 and Linux x64 only. They are not supported on Linux ARM64.
ADBC connectors (adbc_mssql, adbc_pgsql, adbc_oracle, adbc_netezza, adbc_teradata, backup_mssql, backup_rman) only support exporting to Parquet format. No other output format is supported with these connection types.
Since FastBCP 1.3, the ADBC connectors run fully on their ADBC driver: the metadata and planning step (row counts, column types, Ntile, Random, Timepartition, DBPartition, …) uses the same driver and the same connection string as the data step. No SqlClient, Npgsql, ODP.NET or NZdotNET is involved.
DSN (Data Source Name)
If you have chosen an ODBC connection type, you must define the DSN with the -N or --dsn parameter, or alternatively define a connection string using -g or --sourceconnectstring.
./FastBCP \
...
--connectiontype odbc \
--dsn "MyODBCDataSource" \
...
Syntax:
- Short form:
-N "DSN_name" - Long form:
--dsn "DSN_name"
Provider
If you have chosen an OLEDB connection type, you must define the OLEDB provider with the -P or --provider parameter.
./FastBCP \
...
--connectiontype oledb \
--provider MSOLEDBSQL \
...
./FastBCP \
...
--connectiontype oledb \
--provider NZOLEDB \
...
Syntax:
- Short form:
-P "provider_name" - Long form:
--provider "provider_name"
Server
Except if you have defined a connection string (-g or --sourceconnectstring), you must define a server (or could also be a TNS entry for Oracle).
Syntax:
- Short form:
-S "server" - Long form:
--server "server"
Server Format Examples
The server parameter accepts different formats depending on your database:
IP address or DNS name:
./FastBCP \
...
--server "myserver.mydomain.com" \
...
IP address or DNS name with port number:
./FastBCP \
...
--server "myserver.mydomain.com:2433" \
...
or
./FastBCP \
...
--server "myserver.mydomain.com,2433" \
...
IP address or DNS name with named instance:
./FastBCP \
...
--server "myserver.mydomain.com\myinstance" \
...
For Oracle - Easy Connect string:
./FastBCP \
...
--server "myserver.mydomain.com:1521/myinstance" \
...
For SQL Server backup files (backup_mssql) - the directory holding the backups:
./FastBCP \
...
--server "D:\Backups\MSSQL" \
...
For Oracle RMAN backup sets (backup_rman) - the directory holding the backup pieces:
./FastBCP \
...
--server "/backup/rman/orcl" \
...
Trusted or User & Password
Trusted
You can used a trusted (Windows or Kerberos Authentication) using the --trusted switch parameter.
./FastBCP \
...
--server "myserver.mydomain.com\myinstance \
--trusted \
--database MySourceDB" \
...
User and Password
You can also provide a user and password
the --user and --password can be used like this
./FastBCP \
...
--server "myserver.mydomain.com\myinstance \
--user "FastUser" \
--password "FastPassword" \
--database MySourceDB" \
...
Source Connection String
You can use a connection string to define the connection to the database. This connection string will override any other connection parameters and can be used if the other authentication mode are not enougth for your case
You can use the connection string for any connection type. The connection string must be enclosed in double quotes.
Example:
./FastBCP \
...
--sourceconnectstring "Server=myserver;Database=mydb;User ID=FastUser;Password=FastPassword;Encrypt=True;TrustServerCertificate=True"
...
Syntax:
- Short form:
-g "connection_string" - Long form:
--sourceconnectstring "connection_string"
Passwords are masked in logs and telemetry, including quoted passwords containing ; (e.g. Password="p;w=1").
Connection Strings with ADBC Connectors
With the ADBC connection types (adbc_mssql, adbc_pgsql, adbc_oracle, adbc_netezza, adbc_teradata), --sourceconnectstring accepts:
- The native syntax of the database (ADO.NET-style
Key=Value;pairs), translated to the driver keys - Explicit
adbc.*/arpeio.*keys, which win over translated keys - A whole-connection
uri/adbc.<driver>.connection_string
Native keys with no driver equivalent (e.g. Pooling=false) are dropped with a warning. With a whole-connection uri / connection_string, native keys are dropped with a warning: put them inside the URI / connection string instead.
A Driver= path in --sourceconnectstring is used for both the metadata and the data step.
adbc_netezza
Keys do not need the adbc.arpenz. prefix. All of the following are accepted:
| Kind | Keys |
|---|---|
| Friendly / ADO.NET keys | Server, Host, host:port, Port, Database, User ID, Password, SSL Mode, Application Name, … |
| Plain driver keys | sslmode, tls_min_version, char_encoding, login_timeout, … |
| Whole connection | uri, connection_string |
Keys the driver does not support (e.g. propagate, Pooling) are ignored, with a single warning. Application Name defaults to FastBCP.
./FastBCP \
--connectiontype adbc_netezza \
--sourceconnectstring "Server=nps-host;Port=5480;Database=SALES;User ID=admin;Password=FastPassword;SSL Mode=require" \
...
NPS 7.x servers only offer TLS 1.0/1.1. Add tls_min_version=1.0 to the connection string to connect to them.
adbc_pgsql
Like -C pgsql, -C adbc_pgsql honours PGUSER, PGPASSWORD, PGPASSFILE / ~/.pgpass and PGSSLROOTCERT when -U / -X / -g do not provide them.
A NaN in a NUMERIC column fails the read. Add adbc.arpepgsql.numeric_special=null to --sourceconnectstring to read it as NULL instead.
adbc_oracle
Like -C oraodp, -C adbc_oracle resolves TNS aliases through tnsnames.ora (looked up in TNS_ADMIN, then $ORACLE_HOME/network/admin), so --server can be a TNS alias.
Network encryption and data integrity are negotiated with encryption=accepted and data_integrity=accepted, so the server decides, as with -C oraodp. Use the FASTBCP_ADBC_ENCRYPTION / FASTBCP_ADBC_DATA_INTEGRITY environment variables or explicit keys to override this.
adbc_teradata
-C adbc_teradata reads Teradata through the embedded ArpeTeradata ADBC driver, for both the metadata step and the data step. It uses the Teradata SQL dialect, like -C teradata.
Connection:
--server host[:port](legacy port, default1025),--user,--passwordand an optional--database, or a--sourceconnectstringin the Teradata provider spelling.- Keys translated from
--sourceconnectstring:Host/Server/Data Source,Port/DBS Port/Port Number,Database/Initial Catalog,User Id/User Name/UID,Password/PWD,SSL Mode,HTTPS Port,SSL CA,SSL CA Path,TMODE,Login Timeout/Connect Timeout/Connection Timeout,Query Timeout,TTU Path. Explicitadbc.arpeteradata.*keys are passed as is and win. - Trusted authentication (
--trusted/-A) is not supported: FastBCP stops with-C adbc_teradata does not support trusted (-A) authentication: give -U and -X.
Logon and Teradata Tools and Utilities (TTU):
- The default logon (
sslmode=prefer) uses TLS on the HTTPS port (443) and needs no Teradata client software. - When the server has no TLS, the driver falls back to the legacy port (1025).
sslmode=disablein--sourceconnectstringalways uses the legacy port. The legacy-port logon needs the customer's TTU (CLIv2). - Linux: FastBCP looks for TTU in the
FASTBCP_TTU_PATHenvironment variable, then in attuorTeradataToolsAndUtilitiesBasedirectory next to the FastBCP binary. The library directory found is passed to the driver (adbc.arpeteradata.ttu_path) and logged. When nothing is found, the driver searches itself (ARPETERADATA_TTU_PATH,/opt/teradata/client, the system library path). - Windows: FastBCP passes nothing; the driver finds
wincli32.dllitself (ARPETERADATA_TTU_PATH, its own directory, the registered TTU installation).
See FASTBCP_TTU_PATH for the TTU folder layouts accepted on Linux and how to prepare Teradata's TTU download without installing it.
./FastBCP \
--connectiontype adbc_teradata \
--server "td-host" \
--user "FastUser" \
--password "FastPassword" \
--database "TPCH" \
...
SQL Server Backup Files (backup_mssql)
--connectiontype backup_mssql reads SQL Server full and differential backups (.bak files) directly, without restoring them and without any SQL Server instance, through the embedded ArpeMSBackup ADBC driver (metadata and data steps). The backup is read in place (random access by page): it is never loaded in memory, so backups much larger than the RAM are read with a bounded memory.
Connection:
--server(-S) is the directory of the backups (D:\Backups\MSSQL,/var/opt/mssql/backup).--database(-I) names the backup files in that directory: a file name, a pattern (*,?), or a list separated by;, in any order. With a full backup and its differentials, name them all: see Differential backups.- No database credentials:
--trustedis not used, and--userand--passwordonly serve for encrypted backups, where they name the private key of the certificate.--sourceconnectstringonly serves to set driver options, such asadbc.arpemsbackup.geospatial. The driver is licensed like the other Arpe.io ADBC FastDrivers.
Backups read:
- Full backups and copy-only full backups, uncompressed or compressed with MS_XPRESS or ZSTD, any
BLOCKSIZE/MAXTRANSFERSIZE. - Differential backups, with the full backup they were taken from (since FastBCP 1.6.7). Log backups are not applied.
- Encrypted backups (
WITH ENCRYPTION) and backups of TDE databases, with the private key of the certificate (since FastBCP 1.6.6). - Striped backups (
BACKUP DATABASE ... TO DISK = a, DISK = b, ...): name all the stripes with a pattern (-I "mydb_*.bak") or a list separated by;(-I "mydb_1.bak;mydb_2.bak;mydb_3.bak"), in any order. An incomplete set, stripes of different backups or a lone stripe are refused with a message naming the missing stripes. - Several backups in one file (
WITH NOINIT): the latest version they hold is read, a full backup and its newest differential (a copy-only full backup counts). Up to FastBCP 1.6.6, the last full backup of the file was read. - Databases over several data files and filegroups, from SQL Server 2017, 2019, 2022 and 2025 (Windows or Linux).
Tables read: rowstore tables (heaps, clustered indexes, partitions, ROW / PAGE compression, LOBs including text / ntext / image and xml, row-overflow, sparse columns, computed persisted columns) and clustered columnstore tables (including archive compression and the open delta store).
Data types: a backup and an adbc_mssql export of the same table give the same Parquet since FastBCP 1.6.5. See SQL Server backup files → Parquet.
Refused with a clear message: tables with a json or vector(n, float16) column (SQL Server 2025): list the other columns in --query to export them. A damaged or truncated backup stops with an error, and so does any backup that could be the newest and cannot be used. QAT_DEFLATE backup compression is not supported.
Queries and parallelism:
--sourceschema/--sourcetable, or--querylimited toSELECT * | col1, col2, … FROM [schema.]table.- Parallel methods:
None, orPhysical, which resolves to the Pages method for this source: each thread reads a slice of the data pages (rowstore) or of the rowgroups (columnstore). See Parallel parameters. - Parquet output only.
A backup taken while the database is written to is read as its pages are: the transaction log contained in the backup is not replayed. This goes for a differential too: taken during writes, it can give other rows than a RESTORE of the same backups.
The first export from a backup reads its structure; FastBCP keeps it in a small file in the local application data of the user (%LOCALAPPDATA%\ArpeMSBackup\index on Windows, ~/.cache/arpemsbackup/index on Linux), so the next exports from the same backup open in a few milliseconds (since FastBCP 1.6.3). A rewritten or moved backup is opened in full again; files unused for 30 days, or beyond 2 GB in all, are removed automatically. FASTBCP_INDEX_DIR names another directory, for an account without a usable home (since FastBCP 1.6.6).
./FastBCP \
--connectiontype backup_mssql \
--server "D:\Backups\MSSQL" \
--database "tpch_full.bak" \
--sourceschema "dbo" \
--sourcetable "orders" \
--directory "D:\export\orders" \
--fileoutput "orders.parquet" \
--parallelmethod "Physical" \
--paralleldegree 8
A striped backup, on Linux:
./FastBCP \
--connectiontype backup_mssql \
--server "/var/opt/mssql/backup" \
--database "tpch_*.bak" \
--sourceschema "dbo" \
--sourcetable "lineitem" \
--directory "/export/lineitem" \
--fileoutput "lineitem.parquet" \
--parallelmethod "Physical" \
--paralleldegree 8
Differential Backups
Since FastBCP 1.6.7, --connectiontype backup_mssql reads the latest version of a table: the newest full backup among the files, and the newest differential taken from it. You always get the whole table, not what changed. Nothing to set: give FastBCP the files.
./FastBCP \
--connectiontype backup_mssql \
--server "/var/opt/mssql/backup" \
--database "sales_full.bak;sales_diff.bak" \
--sourceschema "dbo" \
--sourcetable "orders" \
--directory "/export/orders" \
--fileoutput "orders.parquet" \
--parallelmethod "Physical" \
--paralleldegree 8
| How the backups are stored | --database |
|---|---|
| One file each | A list in any order, "sales_full.bak;sales_diff.bak", or a pattern, "sales_*.bak" |
| Several days in one directory | A pattern, "sales_*.bak": older backups can match too, only the latest version is read |
One file, WITH NOINIT | The file, "sales.bak" |
| Striped | All the stripes of each backup, usually a pattern |
FastBCP checks that the differential was taken from that full backup: the names and the order of the files do not matter. A differential holds every change since its full backup, so one is enough. All the files must be in the --server directory, and be backups of one database.
Encrypted backups work the same way, with the key of their certificate.
Backups That Cannot Be Used
A backup that could be the newest and cannot be used fails the export, naming it, rather than reading older data without saying so. That is the case of:
- a differential whose full backup is not among the files,
- a stripe that is missing,
- a backup that is truncated, interrupted or still being written,
- a file that matches the pattern and is not a backup,
- an encrypted backup without its key,
- a file, filegroup or partial backup,
- backups of a database and of a restored copy of it.
The logs say what can be done about it. Two variables change this behaviour without touching the command:
| Variable | Effect |
|---|---|
FASTBCP_BACKUP_RESTORE_MODE=best_effort | The backup is skipped, and the newest usable version is read, however old |
FASTBCP_BACKUP_RESTORE_POINT=full | The last full backup of one backup is read, as up to FastBCP 1.6.6 |
The options adbc.arpemsbackup.restore_mode and adbc.arpemsbackup.restore_point in --sourceconnectstring do the same, and win over the variables.
Upgrading to 1.6.7
Without these variables, an export can behave differently from FastBCP 1.6.6. Each line was measured on both versions, with backups of SQL Server 2025.
These worked and now fail, naming the backup:
| With these files | 1.6.6 | To read anyway |
|---|---|---|
A WITH NOINIT file whose newest differential has its full backup in another file | The older full backup of the file | Give both files, for the newest rows. FASTBCP_BACKUP_RESTORE_POINT=full or FASTBCP_BACKUP_RESTORE_MODE=best_effort, for the rows of 1.6.6 |
A WITH NOINIT file with a file, filegroup or partial backup after the full backup | The tables of that backup, from it; the other tables failed | FASTBCP_BACKUP_RESTORE_POINT=full, as 1.6.6. FASTBCP_BACKUP_RESTORE_MODE=best_effort, every table from the full backup, so older rows |
A WITH NOINIT file whose last differential lost the end of the file, after its data | The older full backup of the file | FASTBCP_BACKUP_RESTORE_POINT=full or FASTBCP_BACKUP_RESTORE_MODE=best_effort, for the rows of 1.6.6 |
| A full backup alone that lost the end of the file, after its data | Read | FASTBCP_BACKUP_RESTORE_POINT=full, as 1.6.6: best_effort has no other version to read. Check the file first: it was cut, or is still being copied |
These read other rows, or read what used to fail:
| With these files | 1.6.6 | 1.6.7 | To keep 1.6.6 |
|---|---|---|---|
A WITH NOINIT file with a full backup and differentials | The last full backup | The full backup and its newest differential: fresher rows | FASTBCP_BACKUP_RESTORE_POINT=full |
| A pattern or a list matching several complete backups of a database | Failed | The latest version among them | A narrower --database |
These failed and still fail, with a clearer message, and FASTBCP_BACKUP_RESTORE_MODE=best_effort now reads them:
| With these files | With best_effort |
|---|---|
| A file cut in the data of a backup, with an older complete full backup | The older version |
| Several backups, the newest truncated or still being written | The older version |
| A pattern also matching a file that is not a backup | The backups, without that file |
| Backups of a database and of a restored copy of it | The newest of the two, whichever database it is: prefer a narrower --database |
The first export from each backup also reads its structure once more, as the format of the index has changed.
Encrypted Backups
Since FastBCP 1.6.6, --connectiontype backup_mssql reads backups WITH ENCRYPTION and backups of TDE databases, alone or together, with the private key of the server certificate. No SQL Server is needed: the key file is all it takes.
| Parameter | Value |
|---|---|
--user (or --sourceuser) | The file of the private key: a .pvk, a .pfx / .p12, a PEM or DER key, or a .cer / .crt certificate with its private key next to it, under the same name. Several files separated by ;: a backup WITH ENCRYPTION of a TDE database can use two certificates |
--password (or --sourcepassword) | The password of that key, if it has one. Hidden in all logs |
./FastBCP \
--connectiontype backup_mssql \
--server "/var/opt/mssql/backup" \
--database "sales_encrypted.bak" \
--sourceuser "/secure/keys/MyCert.pvk" \
--sourcepassword "KeyPassword" \
--sourceschema "dbo" \
--sourcetable "orders" \
--directory "/export/orders" \
--fileoutput "orders.parquet" \
--parallelmethod "Physical" \
--paralleldegree 8
Export the key on the server that holds the certificate, as one PVK file with its certificate, or as one PFX file (SQL Server 2022 and later):
BACKUP CERTIFICATE MyCert TO FILE = 'C:\keys\MyCert.cer'
WITH PRIVATE KEY (FILE = 'C:\keys\MyCert.pvk', ENCRYPTION BY PASSWORD = 'KeyPassword');
BACKUP CERTIFICATE MyCert TO FILE = 'C:\keys\MyCert.pfx'
WITH FORMAT = 'PFX', PRIVATE KEY (ENCRYPTION BY PASSWORD = 'KeyPassword', ALGORITHM = 'AES_256');
What is read: AES 128, 192 and 256 and Triple DES, compressed or not, striped, from SQL Server 2017, 2019, 2022 and 2025. A backup that is not encrypted ignores these two parameters.
Without the right key, the export stops and the message names the certificate by its thumbprint, the one sys.certificates shows. A wrong or a missing password stops it too, with a message saying so.
Whoever has the private key can read the backups it opens, with no server involved: keep it as carefully as the backups themselves. The index FastBCP keeps for such a backup holds no key, and the key is needed at every export.
- SQL Server gives the files written by
BACKUP CERTIFICATEto its service account alone: grant the account running FastBCP read access to them, or useCERTPRIVATEKEYandCERTENCODED, which return the same bytes. - Keys in an EKM provider (
SERVER ASYMMETRIC KEY) are not supported. - An uncompressed backup of a TDE database taken while its key was being changed (
encryption_state4) is refused when the export reaches a page still under the previous key. Take the backup again once the change is over, orWITH COMPRESSION, which reads normally. - A password with non-ASCII characters in a PVK file depends on the code page of the server. If it is reported as wrong, export the key with an ASCII password.
Oracle RMAN Backup Sets (backup_rman)
--connectiontype backup_rman reads Oracle RMAN backup sets directly, without Oracle and without restoring them, through the embedded ArpeOraBackup ADBC driver (metadata and data steps). The backup pieces are read in place: nothing is restored, copied or loaded in memory as a whole.
Connection:
--serveris the directory of the backup pieces (/backup/rman/orcl,D:\Backups\RMAN).--databasenames the pieces: names, paths or patterns, several of them separated by;, in any order (--database "full_*",--database "l0/*;l1/**"). Give every piece of the backup: the pieces of a multi-piece set and of every set, and with incremental backups the whole chain. See Naming the backup pieces.- No credentials:
--user,--passwordand--trustedare not used.--sourceconnectstringonly serves to set driver options, such as the restore point and restore mode. The driver is licensed like the other Arpe.io ADBC FastDrivers.
Backups read:
- Full backup sets (
BACKUP DATABASE,BACKUP TABLESPACE,BACKUP DATAFILE,BACKUP PLUGGABLE DATABASE), uncompressed orAS COMPRESSED BACKUPSETwith the BASIC, LOW, MEDIUM or HIGH algorithm. - Incremental backups, levels 0 to 4, differential and cumulative: the latest version of the table (since FastBCP 1.6.8).
- Multi-piece sets (
MAXPIECESIZE), several channels or sets (FILESPERSET),SECTION SIZE,COPIES 2. When several backups of the same files are given, the latest version of each datafile is read. - Archived log, control file and SPFILE pieces among the files are ignored.
- Container databases (the root and the PDBs) and non-CDB databases, bigfile and smallfile tablespaces.
- Backups of Oracle 19c, 21c, 23ai and 26ai databases running on Linux x86-64.
Tables read: heap tables, including deleted, chained and migrated rows, tables of more than 255 columns and empty tables. See the datatypes conversion for the column types.
Refused with a clear message:
- Encrypted backup sets (
SET ENCRYPTION, password or wallet). - Any backup that could be the newest and cannot be used, such as an incremental backup without its level 0, or a set without one of its pieces (since FastBCP 1.6.8).
- Image copies (
BACKUP AS COPY,RECOVER COPYstrategies) are not read. - Partitioned, index-organized, clustered, object, nested, temporary and external tables.
- LOB (
CLOB,NCLOB,BLOB,BFILE),INTERVAL,ROWID/UROWID,JSON,VECTOR,XMLTYPEand object columns: the other columns of the table can still be exported, listed in--query. - Tablespaces with a non-default block size, and backups of big-endian platforms.
Queries and parallelism:
--sourceschema(the owner) /--sourcetable, or--querylimited toSELECT * | col1, col2, … FROM [[container.]owner.]table.- In a container database with a single PDB, tables are named
OWNER.TABLE; the tables of the root or of another PDB are namedCONTAINER.OWNER.TABLEin--query. - Parallel methods:
None, orPhysical, which resolves to the Pages method for this source: each thread reads a range of the table's blocks. See Parallel parameters. - Parquet output only.
A backup taken while the database is open (an online backup, in ARCHIVELOG mode) is read as its blocks are: the redo is not applied. A backup taken with the database mounted is consistent. This goes for incremental backups too.
The first export from a backup reads its structure; FastBCP keeps it in a small file in the local application data of the user (%LOCALAPPDATA%\ArpeOraBackup\index on Windows, ~/.cache/arpeorabackup/index on Linux), so the next exports from the same backup open in a few milliseconds (since FastBCP 1.6.4). After a new incremental backup, only the new backup is opened in full: the backups already opened stay fast (since FastBCP 1.6.8). A rewritten or moved backup is opened in full again; files unused for 30 days, or beyond 2 GB in all, are removed automatically. FASTBCP_INDEX_DIR names another directory, for an account without a usable home (since FastBCP 1.6.6).
./FastBCP \
--connectiontype backup_rman \
--server "/backup/rman/orcl" \
--database "full_*" \
--sourceschema "SALES" \
--sourcetable "ORDERS" \
--directory "/export/orders" \
--fileoutput "orders.parquet" \
--parallelmethod "Physical" \
--paralleldegree 8
A few columns of a table of another PDB, on Windows:
.\FastBCP.exe `
--connectiontype backup_rman `
--server "D:\Backups\RMAN" `
--database "full_*;ctl_*" `
--query "SELECT ID, NAME, CREATED FROM HRPDB.HR.EMPLOYEES" `
--directory "D:\export\employees" `
--fileoutput "employees.parquet" `
--parallelmethod "Physical" `
--paralleldegree 4
Naming the Backup Pieces
--database is a list of entries separated by ;. Each entry is a name, a path or a pattern, relative to the --server directory or absolute:
| Linux | Windows | What it matches |
|---|---|---|
full_*, ORCL_??_* | full_*, ORCL_??_* | * and ? match within a name, in the --server directory |
l0/* | l0\* | The files of the subdirectory l0 |
l1/** | l1\** | The files of l1 and of all its subdirectories, at any depth |
** | ** | Every file below --server |
**/ORCL_* | **\ORCL_* | The files named ORCL_*, in --server or in any of its subdirectories |
l0 | l0 | A directory named last stands for its files |
/backup/l0/*;/backup/l1/2026-11-*/* | D:\Backups\l0\*;D:\Backups\l1\2026-11-*\* | Absolute paths, patterns included |
- Path separator:
/on Linux. On Windows,\or/, both work. - Each entry must match at least one file, or the export fails, naming it (
no file matches 'l2/**'): a typo does not silently drop a level of the chain. - A name starting with
.is matched only by a pattern starting with.. **does not go down into a directory link it finds; a link named in the entry, or--serveritself, is followed.- At the start of each export, the log gives the number of files found:
Backup files : 42 file(s) matching 'l0/*;l1/**' in /backup/rman/orcl.
Incremental Backups
Since FastBCP 1.6.8, --connectiontype backup_rman reads incremental backups, levels 0 to 4, differential and cumulative. Give the level 0 and the incremental backups taken on it, or the whole backup directory: each datafile is read at the latest version the files give. You always get the whole table, not the changed rows.
./FastBCP \
--connectiontype backup_rman \
--server "/backup/rman/orcl" \
--database "l0/*;l1/**" \
--sourceschema "SALES" \
--sourcetable "ORDERS" \
--directory "/export/orders" \
--fileoutput "orders.parquet" \
--parallelmethod "Physical" \
--paralleldegree 8
| How the backups are stored | --database |
|---|---|
| All in one directory | A pattern, "ORCL_*", or "*": older backups can match too, only the latest version is read |
| A directory per level | "l0/*;l1/*" (Windows: "l0\*;l1\*") |
| A directory per day, below each level | "l0/*;l1/**" (Windows: "l0\*;l1\**") |
Anywhere below --server | "**" |
FastBCP checks that each incremental backup belongs to the chain: the names and the order of the files do not matter, and a newer full or level 0 backup among the files starts a new chain. Backups of the abandoned branch, after a restore and OPEN RESETLOGS, are not read.
- The more incremental backups to read through, the longer the read, most of all with BASIC compression. A cumulative backup, or a new level 0, keeps the chain short.
- A level 1 taken under heavy writes can fail the export of a table, naming the block it lacks: the next level 1, taken at a quieter time, reads it.
- Image copies (
BACKUP AS COPY,RECOVER COPYstrategies) are not read. - The
**pattern is forbackup_rman;backup_mssqlreads the files of the--serverdirectory only.
Backups That Cannot Be Used
A backup that could be the newest and cannot be used fails the export, naming it, rather than reading older data without saying so. That is the case of:
- an incremental backup whose level 0, or a level in between, is not among the files: the message names the backup needed,
- a backup set without one of its pieces, or still being written,
- an encrypted backup set.
The other tables are read, and the logs say what can be done about it. The same two variables as for backup_mssql change this behaviour without touching the command:
| Variable | Effect |
|---|---|
FASTBCP_BACKUP_RESTORE_MODE=best_effort | The backup is skipped, and the newest usable version is read, however old |
FASTBCP_BACKUP_RESTORE_POINT=full | The most recent full or level 0 backup of each datafile is read, the incremental backups ignored |
The options adbc.arpeorabackup.restore_mode and adbc.arpeorabackup.restore_point in --sourceconnectstring do the same, and win over the variables.
Upgrading to 1.6.8
Each line was measured on both versions, with backups of Oracle 23ai.
| With these files | 1.6.7 | 1.6.8 | To keep 1.6.7 |
|---|---|---|---|
| One full or level 0 backup | Read | Same | — |
| A level 0 and incremental backups on it | Failed: is an incremental level 1 backup | The latest version: fresher rows | FASTBCP_BACKUP_RESTORE_POINT=full: the level 0 |
| Incremental backups without their level 0 | Failed | Fails, naming the backup needed | — |
| A chain with a hole (a level missing, a newer one given) | Failed | Fails, naming the backup and what it needs | FASTBCP_BACKUP_RESTORE_MODE=best_effort: the version before the hole |
--database with a subdirectory (l0/*) | Failed: no file matches | Read | — |
Also on full backups:
| With these files | 1.6.7 | 1.6.8 |
|---|---|---|
| A backup set without its last piece | Read short, without an error | Fails, naming it. best_effort: the version before it |
| A table truncated, then its tablespace backed up alone | Read empty | Refused, naming it |
A column added with a DEFAULT, on the rows written before | NULL | The default value |
Archived log pieces in the directory, more than 64 pieces, COPIES 2 | Refused | Read |
| A dropped PDB | Its tables listed | No longer listed |
FastBCP 1.6.0 read a level 1 backup as a full one, so the export held only the rows of the changed blocks, with no error. Export again any table read from a level 1 backup with 1.6.0.
Database
Optionally define a source database. With backup_mssql, --database names the backup files (see SQL Server backup files); with backup_rman, the names, paths or patterns of the backup pieces (see Oracle RMAN backup sets).
Example:
./FastBCP \
...
--database "AdventureWorks" \
...
Syntax:
- Short form:
-I "database_name" - Long form:
--database "database_name"
Application Intent
Specifies the application workload type when connecting to SQL Server. This parameter is only applicable for SQL Server (mssql, adbc_mssql) and OLEDB (oledb) connection types.
With adbc_mssql, an ApplicationIntent key in --sourceconnectstring is also passed to the driver.
Syntax:
- Long form:
--applicationintent "ReadOnly|ReadWrite"
Values:
ReadOnly(default) - Declares the read-only workload type when connecting to a read-only replica in an Always On availability groupReadWrite- Declares a read-write workload type (standard connection)
Example (Read-Only):
./FastBCP \
--connectiontype mssql \
--server "myserver.mydomain.com" \
--applicationintent ReadOnly \
--database "AdventureWorks" \
...
Example (Read-Write):
./FastBCP \
--connectiontype mssql \
--server "myserver.mydomain.com" \
--applicationintent ReadWrite \
--database "AdventureWorks" \
...
When using ReadOnly, the connection will be routed to a read-only replica if available in an Always On availability group configuration. This is useful for offloading reporting and export workloads from the primary replica.