') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); })(); docs/claude-code.md at main · SQLAnvil/docs · GitHub
Skip to content

claude-code.md

Latest commit

History

History
71 lines (54 loc) · 3.47 KB

claude-code.md

File metadata and controls

71 lines (54 loc) · 3.47 KB
Raw

Using SQLAnvil with Claude Code

SQLAnvil ships a Claude Code skill that teaches the assistant to write correct SQLAnvil code. Because SQLAnvil is a fork of Dataform, an AI's Dataform/BigQuery instincts produce subtly broken SQLAnvil projects — wrong config blocks, wrong credentials shape, BigQuery DDL, ; separators, the wrong CLI. The sqlanvil-engineering-fundamentals skill is the correction layer, and it also teaches the SQLAnvil-specific features (the postgres: {} block, named connections, introspect).

Install

The skill ships in the sqlanvil-toolkit plugin on the public ihistand marketplace. In a Claude Code session:

# 1. Add the marketplace (once)
/plugin marketplace add ihistand/claude-plugins
# 2. Install the toolkit
/plugin install sqlanvil-toolkit@ihistand

Then restart Claude Code. (The marketplace is a public GitHub repo, so /plugin marketplace add works directly — no extra setup.)

What you get

Skill — sqlanvil-engineering-fundamentals. Activates automatically when you edit a .sqlx file, workflow_settings.yaml, or .df-credentials.json in a Postgres/Supabase project. It steers Claude onto:

  • Flat warehouse: config and a flat PostgresConnection.df-credentials.json (not the BigQuery shapes), and sqlanvilCoreVersion (not dataformCoreVersion)
  • First-class postgres: {} DDL — indexes (numeric method enum), partitioning, storage options, materialized views — never hand-rolled post_operations DDL
  • --- as the statement separator; procedures/functions/triggers via type: "operations"
  • Supabase extras: RLS policies, Realtime, pgvector
  • Named connections — read a BigQuery table as a live foreign table via the auto-generated FDW bridge, generated with introspect (see Named Connections)

Slash commands:

CommandPurpose
/sqlanvil-compileCompile and surface config/graph errors (static, no warehouse)
/sqlanvil-testValidate model(s) against a --schema-suffix dev sandbox
/sqlanvil-runRun/deploy to the warehouse with pre-flight checks
/sqlanvil-new-tableCreate a new table via TDD (RED → GREEN → REFACTOR)
/sqlanvil-introspectGenerate a cross-warehouse source declaration from a named connection

Verify it's active

Open a SQLAnvil project and ask Claude to create a table. With the skill active it reaches for a postgres: {} block and ${ref()}, documents columns, and avoids BigQuery-isms like partitionBy or bigquery: {}. You can also run a command directly, e.g. /sqlanvil-new-table.

Skill only (without the plugin)

If you'd rather use just the skill — for a different agent, or a personal-skill setup — the canonical SKILL.md lives in the ihistand/claude-skills repo under sqlanvil-engineering-fundamentals/. Copy it to ~/.claude/skills/sqlanvil-engineering-fundamentals/SKILL.md (a personal skill loads in every project), or symlink it so it stays current as the skill is updated.

Build your own for your team's standards

Skills layer. You can write a thin, org-specific skill on top of sqlanvil-engineering-fundamentals — name it as a prerequisite and add only your team's conventions (naming, target datasets, review rules) without repeating the generic rules. The acuantia-dataform plugin in the same marketplace is a worked example of this pattern for a Dataform team; the same approach works on top of the SQLAnvil skill.