Created
August 17, 2026 07:58
-
-
Save lassebenni/fd10d46f11d08119abcdcbc08a0ae6e8 to your computer and use it in GitHub Desktop.
Code Explainer: Week 15 publish staging swap
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
| <!DOCTYPE html> | |
| <html lang="en"> | |
| <head> | |
| <meta charset="UTF-8"> | |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| <title>Code Explainer: publish staging swap</title> | |
| <style> | |
| * { margin: 0; padding: 0; box-sizing: border-box; } | |
| body { | |
| background: #0d1117; | |
| display: flex; | |
| justify-content: center; | |
| align-items: flex-start; | |
| min-height: 100vh; | |
| font-family: 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; | |
| padding: 12px; | |
| color: #c9d1d9; | |
| } | |
| .explainer-container { | |
| width: 100%; | |
| max-width: 860px; | |
| background: #161b22; | |
| border-radius: 10px; | |
| overflow: hidden; | |
| box-shadow: 0 16px 36px rgba(0,0,0,0.6); | |
| border: 1px solid #30363d; | |
| display: flex; | |
| flex-direction: column; | |
| } | |
| .titlebar { | |
| background: #0d1117; | |
| padding: 10px 16px; | |
| display: flex; | |
| align-items: center; | |
| gap: 8px; | |
| border-bottom: 1px solid #21262d; | |
| user-select: none; | |
| } | |
| .dot { width: 12px; height: 12px; border-radius: 50%; } | |
| .dot.r { background: #ff5f56; } | |
| .dot.y { background: #ffbd2e; } | |
| .dot.g { background: #27c93f; } | |
| .titlebar .title { | |
| color: #8b949e; | |
| font-size: 13px; | |
| flex: 1; | |
| text-align: center; | |
| font-family: 'SF Mono', 'Fira Code', monospace; | |
| font-weight: 500; | |
| } | |
| .code-body { | |
| padding: 14px 0; | |
| font-family: 'SF Mono', 'Fira Code', 'Menlo', monospace; | |
| font-size: 12px; | |
| line-height: 1.55; | |
| overflow-x: auto; | |
| background: #0d1117; | |
| max-height: 400px; | |
| overflow-y: auto; | |
| } | |
| .code-line { | |
| display: flex; | |
| padding: 2px 16px; | |
| cursor: pointer; | |
| transition: background 0.15s ease, border-color 0.15s ease; | |
| user-select: text; | |
| border-left: 3px solid transparent; | |
| } | |
| .code-line:hover { background: #161b22; } | |
| .code-line.annotated { | |
| border-left-color: #1f6feb; | |
| background: rgba(31, 111, 235, 0.06); | |
| } | |
| .code-line.annotated:hover { background: rgba(31, 111, 235, 0.22); } | |
| .code-line.annotated.active { | |
| background: rgba(56, 139, 253, 0.28); | |
| border-left-color: #58a6ff; | |
| } | |
| .line-num { | |
| width: 36px; | |
| color: #484f58; | |
| text-align: right; | |
| padding-right: 16px; | |
| user-select: none; | |
| flex-shrink: 0; | |
| } | |
| .line-content { white-space: pre; flex: 1; } | |
| .kwd { color: #ff7b72; font-weight: 600; } | |
| .fn { color: #d2a8ff; } | |
| .str { color: #a5d6ff; } | |
| .cmnt { color: #8b949e; font-style: italic; } | |
| .var { color: #ffa657; } | |
| .explanation-dock { | |
| background: #161b22; | |
| border-top: 1px solid #30363d; | |
| padding: 16px 20px; | |
| min-height: 120px; | |
| display: flex; | |
| flex-direction: column; | |
| justify-content: center; | |
| } | |
| .dock-header { display: flex; align-items: center; gap: 10px; margin-bottom: 6px; } | |
| .badge { | |
| font-size: 11px; | |
| text-transform: uppercase; | |
| font-weight: 700; | |
| padding: 2px 8px; | |
| border-radius: 12px; | |
| letter-spacing: 0.5px; | |
| } | |
| .badge.key { background: rgba(255, 166, 87, 0.15); color: #ffa657; border: 1px solid rgba(255, 166, 87, 0.3); } | |
| .badge.delta { background: rgba(56, 139, 253, 0.15); color: #58a6ff; border: 1px solid rgba(56, 139, 253, 0.3); } | |
| .badge.dbt { background: rgba(46, 160, 67, 0.15); color: #3fb950; border: 1px solid rgba(46, 160, 67, 0.3); } | |
| .dock-title { font-size: 14px; font-weight: 600; color: #f0f6fc; } | |
| .dock-body { font-size: 13px; line-height: 1.5; color: #c9d1d9; } | |
| .hint-text { display: flex; align-items: center; gap: 8px; font-size: 13px; color: #8b949e; } | |
| </style> | |
| </head> | |
| <body> | |
| <div class="explainer-container" id="container"> | |
| <div class="titlebar"> | |
| <span class="dot r"></span><span class="dot y"></span><span class="dot g"></span> | |
| <span class="title">data/src/publishing/sync.py — publish()</span> | |
| </div> | |
| <div class="code-body" id="codeBody"> | |
| <div class="code-line annotated" data-key="guard" onclick="selectLine(this,'guard')" onmouseenter="selectLine(this,'guard')"><span class="line-num">96</span><span class="line-content"> <span class="kwd">if</span> <span class="kwd">not</span> rows:</span></div> | |
| <div class="code-line annotated" data-key="guard" onclick="selectLine(this,'guard')" onmouseenter="selectLine(this,'guard')"><span class="line-num">97</span><span class="line-content"> <span class="kwd">raise</span> <span class="fn">ValueError</span>(<span class="str">"refusing to publish zero rows…"</span>)</span></div> | |
| <div class="code-line"><span class="line-num">98</span><span class="line-content"></span></div> | |
| <div class="code-line annotated" data-key="names" onclick="selectLine(this,'names')" onmouseenter="selectLine(this,'names')"><span class="line-num">101</span><span class="line-content"> staging = <span class="fn">Identifier</span>(schema, <span class="str">f"{table}__staging"</span>)</span></div> | |
| <div class="code-line annotated" data-key="names" onclick="selectLine(this,'names')" onmouseenter="selectLine(this,'names')"><span class="line-num">102</span><span class="line-content"> published = <span class="fn">Identifier</span>(schema, table)</span></div> | |
| <div class="code-line"><span class="line-num">108</span><span class="line-content"> connection = psycopg.<span class="fn">connect</span>(dsn, autocommit=<span class="kwd">False</span>)</span></div> | |
| <div class="code-line annotated" data-key="load" onclick="selectLine(this,'load')" onmouseenter="selectLine(this,'load')"><span class="line-num">111</span><span class="line-content"> cursor.<span class="fn">execute</span>(<span class="fn">SQL</span>(<span class="str">"drop table if exists {}"</span>).<span class="fn">format</span>(staging))</span></div> | |
| <div class="code-line annotated" data-key="load" onclick="selectLine(this,'load')" onmouseenter="selectLine(this,'load')"><span class="line-num">112</span><span class="line-content"> cursor.<span class="fn">execute</span>(<span class="fn">SQL</span>(<span class="str">"create table {} ({})"</span>).<span class="fn">format</span>(staging, definition))</span></div> | |
| <div class="code-line annotated" data-key="load" onclick="selectLine(this,'load')" onmouseenter="selectLine(this,'load')"><span class="line-num">113</span><span class="line-content"> cursor.<span class="fn">executemany</span>(<span class="fn">SQL</span>(<span class="str">"insert into {} …"</span>), rows)</span></div> | |
| <div class="code-line annotated" data-key="swap" onclick="selectLine(this,'swap')" onmouseenter="selectLine(this,'swap')"><span class="line-num">123</span><span class="line-content"> cursor.<span class="fn">execute</span>(<span class="fn">SQL</span>(<span class="str">"drop table if exists {}"</span>).<span class="fn">format</span>(published))</span></div> | |
| <div class="code-line annotated" data-key="swap" onclick="selectLine(this,'swap')" onmouseenter="selectLine(this,'swap')"><span class="line-num">124</span><span class="line-content"> cursor.<span class="fn">execute</span>(<span class="fn">SQL</span>(<span class="str">"alter table {} rename to {}"</span>).<span class="fn">format</span>(staging, <span class="fn">Identifier</span>(table)))</span></div> | |
| <div class="code-line annotated" data-key="stamp" onclick="selectLine(this,'stamp')" onmouseenter="selectLine(this,'stamp')"><span class="line-num">130</span><span class="line-content"> cursor.<span class="fn">execute</span>(<span class="fn">SQL</span>(<span class="str">"comment on table {} is {}"</span>)…)</span></div> | |
| <div class="code-line annotated" data-key="commit" onclick="selectLine(this,'commit')" onmouseenter="selectLine(this,'commit')"><span class="line-num">135</span><span class="line-content"> connection.<span class="fn">commit</span>()</span></div> | |
| </div> | |
| <div class="explanation-dock" id="dock"> | |
| <div class="hint-text" id="hint"><span>💡</span><span>Hover or tap any blue-accented line to see what it does.</span></div> | |
| <div id="dockContent" style="display:none;"> | |
| <div class="dock-header"> | |
| <span class="badge key" id="dockBadge">key</span> | |
| <span class="dock-title" id="dockTitle">Title</span> | |
| </div> | |
| <div class="dock-body" id="dockBody">Body</div> | |
| </div> | |
| </div> | |
| </div> | |
| <script> | |
| const explanations = { | |
| guard: { | |
| type: 'key', | |
| badge: 'Safety', | |
| title: 'Refuse empty publishes', | |
| body: 'If dbt built zero rows, publishing would wipe yesterday\'s mart. The script fails loudly instead of serving an empty table to the backend.' | |
| }, | |
| names: { | |
| type: 'key', | |
| badge: 'SQL safety', | |
| title: 'Identifier(), not f-strings', | |
| body: 'Table names are composed with psycopg SQL objects so a weird table name cannot become SQL injection. Values use Placeholder() in the INSERT.' | |
| }, | |
| load: { | |
| type: 'delta', | |
| badge: 'Staging load', | |
| title: 'Load into __staging first', | |
| body: 'Readers still query analytics.fct_postings (yesterday) while today\'s rows land in fct_postings__staging. No truncate on the live table.' | |
| }, | |
| swap: { | |
| type: 'delta', | |
| badge: 'Atomic swap', | |
| title: 'Drop old, rename staging', | |
| body: 'Inside one transaction: drop the old published table, rename staging to fct_postings. A reader sees all old rows or all new rows — never a half-loaded table.' | |
| }, | |
| stamp: { | |
| type: 'key', | |
| badge: 'Provenance', | |
| title: 'COMMENT ON TABLE', | |
| body: 'Records which Databricks schema published (e.g. team_a.dev_alex). Helpful when several trainees share analytics_dev and the last publish wins.' | |
| }, | |
| commit: { | |
| type: 'dbt', | |
| badge: 'Transaction', | |
| title: 'commit() makes it visible', | |
| body: 'autocommit=False keeps load + swap atomic. If anything fails, rollback leaves the previous good mart in place.' | |
| } | |
| }; | |
| function selectLine(el, key) { | |
| if (!explanations[key]) return; | |
| document.querySelectorAll('.code-line').forEach(l => l.classList.remove('active')); | |
| document.querySelectorAll(`.code-line[data-key="${key}"]`).forEach(l => l.classList.add('active')); | |
| const exp = explanations[key]; | |
| document.getElementById('hint').style.display = 'none'; | |
| document.getElementById('dockContent').style.display = 'block'; | |
| document.getElementById('dockBadge').textContent = exp.badge; | |
| document.getElementById('dockBadge').className = 'badge ' + exp.type; | |
| document.getElementById('dockTitle').textContent = exp.title; | |
| document.getElementById('dockBody').textContent = exp.body; | |
| } | |
| </script> | |
| </body> | |
| </html> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment