docs: correct the bacpac claims, and document --schema-only - #25
Merged
Merged
Conversation
Two commenters on the launch thread pushed back on the same passage, and both were right. A bacpac carries database users and database roles, not only contained users. What it does not carry is the server logins behind them, so they restore orphaned - which is the real limitation and the one worth stating. The claim came from reading one database's model.xml, which held no user or role elements at all, and generalising that into a fact about the format. One sample is not a specification. The corrected passage says what was measured and what it does and does not license. "All-or-nothing" was also too strong: sqlpackage takes /p:TableData= and selects which tables' data to include. The distinction that survives is narrower and still real - no row filter within a table, and the schema is always complete. Also corrected a sentence in "when not to use this" that said a bacpac does not "hold more", which was about artifact size but now reads as a claim about coverage. Separately, --schema-only gets a section of its own. It has existed since the first commit and skips the data path entirely, but it appeared only as a row in a flag table, so #19 was filed asking for a feature that was already there - by someone who had read the README. Comparable flags each have a section; this one now does too, with the nightly-schema-into-git job it exists for, and two caveats worth knowing in advance: output is not yet byte-identical between runs, and verify reports OK on an archive with no rows in it. Fixes #23. Fixes #24.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #23 and #24, both of which came out of the r/SQLServer thread.
#23 — the bacpac claims were wrong
Two commenters pushed back on the same passage, independently, and both were right.
Users and roles. A bacpac carries database users and database roles — not "contained users at
best". What it does not carry is the server logins behind them, so they restore orphaned. That
is a real limitation and a more useful thing to tell the reader.
The error is worth naming precisely, because it is a reasoning failure rather than a typo: the
claim came from opening one database's
model.xml, finding no user or role elements, and writingthat up as what the format does. One sample is not a specification. The corrected passage now says
what was measured, and what that does and does not license.
"All-or-nothing". Also too strong —
sqlpackage /p:TableData=selects which tables' data toinclude. What survives is narrower and still true: no row filter within a table, and the schema is
always complete. Corrected in the README and in
docs/dbdumper-vs-dacfx.md.One more, found while auditing. When not to use this said a server-side bacpac is preferable
"not because a bacpac holds more" — that sentence is about artifact size (488 MB vs 498 MB), but
after the correction above it reads as a claim about coverage. Reworded to say "smaller".
#24 —
--schema-onlyexisted but was invisibleIt has worked since the first commit and skips the data path entirely, but it appeared only as a
row in the export flag table. #19 was filed asking for the feature — by someone who had read the
README. That is about as clear a signal as documentation feedback gets.
It now has a section next to the other filtering features, covering the nightly-schema-into-git job
that motivated the request, and two caveats a reader deserves up front:
nothing moved
verifythen compares zero against zero andreports
OK— correct, but surprisingCross-linked from When it is the right tool.
Checks
--schema-onlywrites no work directory. It does —openSpoolruns before theSchemaOnlycheck, so a
.partdirectory is created and then discarded. Verified by running it: the archivehas 0
data/entries and nothing is left behind, but the work directory does exist duringthe run. The text now says what actually happens.
had scrubbed from it.