Skip to content

docs: correct the bacpac claims, and document --schema-only - #25

Merged
JeePeeTee merged 1 commit into
mainfrom
docs/bacpac-and-schema-only
Sep 2, 2026
Merged

JeePeeTee merged 1 commit into
mainfrom
docs/bacpac-and-schema-only

Conversation

@JeePeeTee

Copy link
Copy Markdown
Owner

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 writing
that 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 to
include. 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-only existed but was invisible

It 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:

  • output is not byte-identical between runs yet (Deterministic export output between runs #21), so a nightly commit can show changes when
    nothing moved
  • a schema-only archive restores as empty tables, and verify then compares zero against zero and
    reports OK — correct, but surprising

Cross-linked from When it is the right tool.

Checks

  • One claim in my own first draft was wrong and got fixed before commit: I wrote that
    --schema-only writes no work directory. It does — openSpool runs before the SchemaOnly
    check, so a .part directory is created and then discarded. Verified by running it: the archive
    has 0 data/ entries and nothing is left behind, but the work directory does exist during
    the run. The text now says what actually happens.
  • Every internal anchor re-validated: 4 links against 27 headings, none broken.
  • No real server or database names introduced — checked against the list this repo has previously
    had scrubbed from it.
  • Documentation only; no code touched.

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.
@JeePeeTee
JeePeeTee merged commit 32c421b into main Sep 2, 2026
2 checks passed
@JeePeeTee
JeePeeTee deleted the docs/bacpac-and-schema-only branch September 2, 2026 06:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README overstates what a bacpac leaves out (users, roles, and 'all-or-nothing')

1 participant