docs: instance-based transaction idiom (schema.connection.transaction)#231
Merged
Merged
Conversation
…tion) Replaces the global-singleton `dj.conn().transaction` in transaction examples with the instance-based form, which is the same Connection object the schema's tables use (Schema binds every table to schema.connection) but names it at the natural altitude and stays correct when tables live on a non-default connection. - Module-level examples -> `schema.connection.transaction` (the schema object is in scope by convention in every pipeline module). - In-method examples (self in scope) -> `self.connection.transaction` (computation-model.md WRONG-nesting example; autopopulate.md). Mechanical idiom change only; other dj.conn() uses (accessor, .query, .connect) are untouched. 17 occurrences across 9 files (incl. 2 tutorial notebooks, text-only edits).
dimitri-yatsenko
added
the
documentation
dimitri-yatsenko
added a commit
that referenced
this pull request
Jul 20, 2026
Convert transaction examples and mentions in this PR's pages from the global dj.conn().transaction to schema.connection.transaction, matching the docs-wide sweep (#231), so the pages read consistently.
This was referenced Jul 20, 2026
Merged
dimitri-yatsenko
added a commit
that referenced
this pull request
Jul 20, 2026
… & make-transaction fixes (#226) * docs(delete-data): reference garbage collection for reclaiming object storage Deleting rows leaves in-store objects (<blob@>/<attach@>/<object@>/<npy@>) in place by design; add a 'Reclaiming Object Storage' note + See-also link to the garbage-collection how-to so readers know deletes don't free external storage. * docs(data-ops): insertion discipline, update how-to, master-part & make-transaction fixes - insert-data: add a 'What Not to Insert' section — don't hand-insert into Computed/Imported (rows come from make()/populate()); Lookup rows come from contents; insert parents before children; no transaction inside make(). (#221) - add how-to/update-data.md — updates are rare/surgical; prefer delete+reinsert+ recompute; update1() for single-row corrections. (#223) - master-part spec: state transitive completeness — a dependency on the master is a dependency on all its parts. (#222) - autopopulate spec §5.5: fix contradiction — was showing a transaction opened inside make(); make() is already transactional (nested raises). (#224) - delete-data: cross-link update-data. Closes #221, #222, #223, #224. * docs(master-part): soften §2.1 composite-reference claim; clarify insertion atomicity Per review on #226: a downstream FK to a specific Part is legal and common (framework-tested), so drop the '(and cannot)' framing. Also distinguish make()-enforced insertion atomicity (Computed/Imported) from the convention used for Manual master-part sets. * docs(insert-data): correct Manual-tier definition Manual tables are the tier whose rows are inserted directly from outside the pipeline — whether entered by a person (form/GUI) or loaded by an automated ingestion tool — not 'entered by hand'. The defining property is direct insertion vs. production by make(), not human authorship. * docs: use instance-based transaction idiom in data-ops pages Convert transaction examples and mentions in this PR's pages from the global dj.conn().transaction to schema.connection.transaction, matching the docs-wide sweep (#231), so the pages read consistently.
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
2 participants
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.
What
Global sweep of transaction examples from the global-singleton
dj.conn().transactionto the instance-based form. 17 occurrences across 9 files.schema.connection.transaction— theschemaobject is defined at module top in every pipeline (theschema = dj.Schema(...)/@schemaconvention), so it is in scope, and a transaction usually spans several tables in that schema.self.connection.transaction— whereselfis in scope (explanation/computation-model.mdWRONG-nesting example;reference/specs/autopopulate.md).Why
dj.conn()returns the singletonConnection, and aSchemabinds every table to that same object (schemas.py:285table._connection = schema.connection), so at runtime the two are identical in the default single-connection case. Butschema.connection.transaction:dj.Instance, an explicitconnection=on the schema),dj.conn()returns the default singleton, a different object, and would wrap the wrong connection.Scope
Mechanical idiom change only. Other
dj.conn()uses (the accessor itself,.query(...),.connect(), thread-safe-mode references) are intentionally left untouched. Notebook edits are text-only (no re-execution).Note: the new explanation pages in #226/#227 (
transactions.md,master-part.md,insert-data.md,delete-data.md) are not onmainyet, so they are not covered here — they still usedj.conn().transactionand can be swept once they merge (or in those PRs). A one-line shared-connection caveat belongs ontransactions.md(in #227); happy to add it there.