Repository navigation
Document that bcp load hints (-h) work on Linux and macOS - #10473
Rudi Bruchez (rudi-bruchez) wants to merge 2 commits into
Conversation
|
Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
|
Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
|
Learn Build status updates of commit 5d6ddf3: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Can you review the proposed changes? Important: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
There was a problem hiding this comment.
🟡 Changes recommended
The documentation claims support for macOS even though the PR evidence verifies the option only on Linux, so the platform support statement needs qualification or macOS validation.
1 open issue
What changed in this PR
This pull request updates the bcp utility documentation to indicate that the -h bulk-import hint option is supported beyond Windows, based on demonstrated Linux behavior.
Changes:
- Marks
-has supported on Linux and macOS in the options table. - Removes the outdated Windows-only applicability statement from the
-hsection.
| File | Description | Review comments |
|---|---|---|
docs/tools/bcp/bcp-utility.md |
Updates platform-support metadata and applicability text for -h hints. |
Validate macOS support or qualify the shared Linux/macOS claim. Also preserve or document the Fabric SQL Database exception, since the section applies there while the table marks -h as unsupported. |
Review effort: Lite
| | [-a *packet_size*](#-a-packet_size) | Yes | Yes | Yes | | ||
| | [-b *batch_size*](#-b-batch_size) | Yes | Yes | Yes | | ||
| | [-h"*hint* \[,...*n*\]"](#-h-hints---n) | Yes | No | No | | ||
| | [-h"*hint* \[,...*n*\]"](#-h-hints---n) | Yes | Yes | No | |
There was a problem hiding this comment.
Agreed, I only tested on Linux. The table now flags the option as Linux only through a footnote, and the option section says it applies to Windows and Linux, keeping the page's existing statement for macOS.
|
Learn Build status updates of commit 9181dbf: ✅ Validation status: passed
For more details, please refer to the build report. |

What's wrong
In
docs/tools/bcp/bcp-utility.md, the command-line options table marks-h"hint [,...n]"as "No" under "Supported on Linux and macOS", and the-hsection starts with "Applies to: Windows only. Not supported on Linux and macOS." On Linux,bcpaccepts-h, sends the hints to the server, and the server applies them:TABLOCKgives a minimally logged load,CHECK_CONSTRAINTSmakes the load fail on rows that violate aCHECKconstraint, andFIRE_TRIGGERSruns the insert trigger. An invalid hint comes back as a server syntax error, so the option isn't ignored by the client.Evidence
bcp18.7.0001.1 (in themssql-tools18folder of the SQL Server images) against SQL Server 2025 RTM-CU10 (17.0.5035.5) and SQL Server 2022 RTM-CU27-GDR (16.0.4305.5), Developer Edition, Linux containers. Alsobcp13.1.0007.0 (imagemcr.microsoft.com/mssql-tools) against SQL Server 2025 CU10 forTABLOCK. Fresh database in theSIMPLErecovery model; 200,000 rows exported withbcp out -n, loaded withbcp in -ninto an empty heap after aCHECKPOINT; log read withfn_dblog.Observed (SQL Server 2025 CU10,
bcp18.7):LOP_INSERT_ROWS-h TABLOCKSQL Server 2022 CU27 gives the same picture (41,178 KB, then 271 KB), and
bcp13.1 too (41,178 KB, then 337 KB).is_not_trusted = 1. With-h CHECK_CONSTRAINTS, the load fails ("The statement has been terminated", native error 3621, then "BCP copy in failed") and no row is loaded.-h FIRE_TRIGGERS, it runs once and sees 200,000 rows.-h NOT_A_HINTfails with "Incorrect syntax near 'NOT_A_HINT'" (SQLState 37000, native error 102), returned by the server.Expected per the current text:
-hnot supported on Linux.macOS wasn't tested. The change keeps the table's single "Linux and macOS" column.
Change
Sets
-hto "Yes" under "Supported on Linux and macOS" in the options table, and removes the "Windows only" line from the-hsection.