Skip to content

Document that bcp load hints (-h) work on Linux and macOS - #10473

Open
Rudi Bruchez (rudi-bruchez) wants to merge 2 commits into
MicrosoftDocs:livefrom
rudi-bruchez:fix/bcp-linux-load-hints
Open

Rudi Bruchez (rudi-bruchez) wants to merge 2 commits into
MicrosoftDocs:livefrom
rudi-bruchez:fix/bcp-linux-load-hints

Conversation

@rudi-bruchez

Copy link
Copy Markdown
Contributor

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 -h section starts with "Applies to: Windows only. Not supported on Linux and macOS." On Linux, bcp accepts -h, sends the hints to the server, and the server applies them: TABLOCK gives a minimally logged load, CHECK_CONSTRAINTS makes the load fail on rows that violate a CHECK constraint, and FIRE_TRIGGERS runs the insert trigger. An invalid hint comes back as a server syntax error, so the option isn't ignored by the client.

Evidence

bcp 18.7.0001.1 (in the mssql-tools18 folder 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. Also bcp 13.1.0007.0 (image mcr.microsoft.com/mssql-tools) against SQL Server 2025 CU10 for TABLOCK. Fresh database in the SIMPLE recovery model; 200,000 rows exported with bcp out -n, loaded with bcp in -n into an empty heap after a CHECKPOINT; log read with fn_dblog.

bcp verif_doc_bcp.dbo.src out src.bcp -n -S localhost -U sa -u
bcp verif_doc_bcp.dbo.dst in  src.bcp -n -S localhost -U sa -u                       # no hint
bcp verif_doc_bcp.dbo.dst in  src.bcp -n -S localhost -U sa -u -h TABLOCK
bcp verif_doc_bcp.dbo.chk in  src.bcp -n -S localhost -U sa -u -h CHECK_CONSTRAINTS  # 200 rows violate CHECK (amount >= 0)
bcp verif_doc_bcp.dbo.trg in  src.bcp -n -S localhost -U sa -u -h FIRE_TRIGGERS      # AFTER INSERT trigger logs COUNT(*) FROM inserted
bcp verif_doc_bcp.dbo.dst in  src.bcp -n -S localhost -U sa -u -h NOT_A_HINT

Observed (SQL Server 2025 CU10, bcp 18.7):

Load Log records Log KB LOP_INSERT_ROWS Rows loaded
No hint 230,389 41,178 200,009 200,000
-h TABLOCK 5,596 354 8 200,000

SQL Server 2022 CU27 gives the same picture (41,178 KB, then 271 KB), and bcp 13.1 too (41,178 KB, then 337 KB).

  • Without a hint, the 200,000 rows load and the constraint becomes 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.
  • Without a hint, the trigger doesn't run. With -h FIRE_TRIGGERS, it runs once and sees 200,000 rows.
  • -h NOT_A_HINT fails with "Incorrect syntax near 'NOT_A_HINT'" (SQLState 37000, native error 102), returned by the server.

Expected per the current text: -h not supported on Linux.

macOS wasn't tested. The change keeps the table's single "Linux and macOS" column.

Change

Sets -h to "Yes" under "Supported on Linux and macOS" in the options table, and removes the "Windows only" line from the -h section.

@prmerger-automator

Copy link
Copy Markdown
Contributor

Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

@prmerger-automator

Copy link
Copy Markdown
Contributor

Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 5d6ddf3:

✅ Validation status: passed

File Status Preview URL Details
docs/tools/bcp/bcp-utility.md ✅Succeeded

For more details, please refer to the build report.

@v-dirichards

Copy link
Copy Markdown
Contributor

cwebb-msft

Can you review the proposed changes?

Important: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

@prmerger-automator prmerger-automator Bot added the aq-pr-triaged tracking label for the PR review team label Oct 29, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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 -h as supported on Linux and macOS in the options table.
  • Removes the outdated Windows-only applicability statement from the -h section.
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

Comment thread docs/tools/bcp/bcp-utility.md Outdated
| [-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 |

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 9181dbf:

✅ Validation status: passed

File Status Preview URL Details
docs/tools/bcp/bcp-utility.md ✅Succeeded

For more details, please refer to the build report.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants