Category: Zig Programming Language

The Zig Programming Language category provides comprehensive documentation on Zig’s role in Geode, including why Zig was chosen as the implementation language, how to build Geode from source, contributing guidelines, and insights into Zig’s unique features that make Geode performant and reliable. <h3 id="why-zig-for-geode" class="position-relative d-flex align-items-center group"> Why Zig for Geode? <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="why-zig-for-geode" aria-haspopup="dialog" aria-label="Share link: Why Zig for Geode?"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script>Geode is written in Zig, a modern systems programming language that prioritizes safety, performance, and developer experience. This choice was deliberate and fundamental to Geode’s architecture, enabling capabilities that would be difficult or impossible with other languages. <h4 id="memory-safety-without-garbage-collection" class="position-relative d-flex align-items-center group"> Memory Safety Without Garbage Collection <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="memory-safety-without-garbage-collection" aria-haspopup="dialog" aria-label="Share link: Memory Safety Without Garbage Collection"> Share link </button> </h4>Zig provides compile-time memory safety checks without the runtime overhead of garbage collection. Every allocation and deallocation is explicit, giving Geode precise control over memory usage - critical for database performance where predictable latency matters. Compile-time safety checks prevent: <ul> <li>Buffer overflows</li> <li>Use-after-free bugs</li> <li>Double frees</li> <li>Memory leaks (with proper review)</li> <li>Null pointer dereferences (optional types)</li> </ul> Unlike C/C++, Zig makes unsafe operations explicit with <code>@</code> builtins, making code review straightforward. Unlike Rust, Zig’s approach is simpler and more direct, reducing cognitive overhead while maintaining safety. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const std = @import("std"); pub fn processQuery(allocator: std.mem.Allocator, query: []const u8) ![]const u8 { // Explicit allocation - compiler tracks ownership var result = try allocator.alloc(u8, 1024); errdefer allocator.free(result); // Automatic cleanup on error // Safe array access - bounds checking in debug mode if (query.len > 0) { result[0] = query[0]; } return result; // Ownership transferred to caller } </code></pre></div> <h4 id="performance-zero-cost-abstractions" class="position-relative d-flex align-items-center group"> Performance: Zero-Cost Abstractions <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-zero-cost-abstractions" aria-haspopup="dialog" aria-label="Share link: Performance: Zero-Cost Abstractions"> Share link </button> </h4>Zig compiles to optimized machine code comparable to C, with no hidden control flow, no hidden allocations, and no runtime overhead from language features. What you write is what executes. Performance characteristics: <ul> <li>Direct memory access without runtime indirection</li> <li>SIMD operations for vectorized processing</li> <li>Inline assembly when needed for critical paths</li> <li>Compile-time code generation (comptime)</li> <li>No vtable overhead for polymorphism</li> </ul> Geode’s query engine benefits from Zig’s performance - graph traversals, index lookups, and transaction processing all run at maximum speed with minimal memory overhead. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Compile-time code generation for type-safe operations fn genericTraversal(comptime T: type, node: *T) void { // Code specialized for each type at compile time // Zero runtime cost for abstraction } </code></pre></div> <h4 id="cross-platform-compilation" class="position-relative d-flex align-items-center group"> Cross-Platform Compilation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="cross-platform-compilation" aria-haspopup="dialog" aria-label="Share link: Cross-Platform Compilation"> Share link </button> </h4>Zig’s advanced cross-compilation makes Geode trivially portable. From a single development machine, you can build for Linux, macOS, Windows, and even embedded targets without installing separate toolchains. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Build for Linux from macOS zig build -Dtarget=x86_64-linux-gnu # Build for Windows from Linux zig build -Dtarget=x86_64-windows-gnu # Build for ARM from x86_64 zig build -Dtarget=aarch64-linux-gnu </code></pre></div>This simplifies CI/CD pipelines and ensures consistent builds across platforms. <h4 id="explicit-error-handling" class="position-relative d-flex align-items-center group"> Explicit Error Handling <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="explicit-error-handling" aria-haspopup="dialog" aria-label="Share link: Explicit Error Handling"> Share link </button> </h4>Zig’s error handling is explicit and compile-time checked, eliminating hidden failure paths and making error recovery straightforward. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const QueryError = error{ SyntaxError, AuthenticationFailed, ConstraintViolation, OutOfMemory, }; pub fn executeQuery(query: []const u8) QueryError!Result { // Compiler enforces error handling at every call site const parsed = try parseQuery(query); // Propagate errors with 'try' const authorized = try checkPermissions(parsed); return executeInternal(authorized); } </code></pre></div>Every possible error path is documented in the function signature and must be handled by callers. This makes Geode’s error handling robust and predictable. <h4 id="comptime-compile-time-execution" class="position-relative d-flex align-items-center group"> Comptime: Compile-Time Execution <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="comptime-compile-time-execution" aria-haspopup="dialog" aria-label="Share link: Comptime: Compile-Time Execution"> Share link </button> </h4>Zig’s <code>comptime</code> feature allows arbitrary code to run during compilation, enabling powerful metaprogramming without macros or templates. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Generate code at compile time pub fn generateIndexImpl(comptime IndexType: type) type { return struct { data: IndexType, pub fn insert(self: *@This(), key: []const u8, value: u64) !void { // Implementation specialized for IndexType } pub fn lookup(self: *const @This(), key: []const u8) ?u64 { // Optimized for specific index type } }; } // Use compile-time generated code const BTreeIndex = generateIndexImpl(BTree); const HashIndex = generateIndexImpl(HashMap); </code></pre></div>Geode uses comptime extensively for: <ul> <li>Type-safe query execution</li> <li>Optimized data structure generation</li> <li>Protocol serialization/deserialization</li> <li>Test generation</li> </ul> <h4 id="simple-predictable-language" class="position-relative d-flex align-items-center group"> Simple, Predictable Language <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="simple-predictable-language" aria-haspopup="dialog" aria-label="Share link: Simple, Predictable Language"> Share link </button> </h4>Zig’s syntax is straightforward and familiar to C programmers, but with modern conveniences. There are no hidden behaviors, no mysterious runtime systems, and no complex language features that obscure what the code actually does. Language principles: <ul> <li>No hidden control flow</li> <li>No hidden allocations</li> <li>No preprocessor</li> <li>No macros (comptime instead)</li> <li>No operator overloading</li> <li>No exceptions (explicit error values)</li> <li>No RAII (explicit defer/errdefer)</li> </ul> This simplicity makes Geode’s codebase approachable for contributors and maintainable long-term. <h3 id="building-geode-from-source" class="position-relative d-flex align-items-center group"> Building Geode from Source <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="building-geode-from-source" aria-haspopup="dialog" aria-label="Share link: Building Geode from Source"> Share link </button> </h3> <h4 id="prerequisites" class="position-relative d-flex align-items-center group"> Prerequisites <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="prerequisites" aria-haspopup="dialog" aria-label="Share link: Prerequisites"> Share link </button> </h4>Zig 0.1.0 or later: Download from <a href="https://ziglang.org/download/" aria-label="ziglang.org – opens in new window" target="_blank" rel="noopener noreferrer" >ziglang.org ↗ </a> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Verify Zig installation zig version # Should output: 0.1.0 or later </code></pre></div>System dependencies: <ul> <li>Git for source control</li> <li>Make for build automation</li> <li>QUIC library (bundled in Geode)</li> </ul> <h4 id="build-process" class="position-relative d-flex align-items-center group"> Build Process <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="build-process" aria-haspopup="dialog" aria-label="Share link: Build Process"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Clone repository git clone https://github.com/codeprosorg/geode cd geode # Build debug version (fast compile, includes debug symbols) make build # Build release version (optimized, slower compile) make release # Run tests make test # Install system-wide make install </code></pre></div> <h4 id="build-configuration" class="position-relative d-flex align-items-center group"> Build Configuration <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="build-configuration" aria-haspopup="dialog" aria-label="Share link: Build Configuration"> Share link </button> </h4>Zig’s build system is written in Zig itself (<code>build.zig</code>): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const std = @import("std"); pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{}); const exe = b.addExecutable(.{ .name = "geode", .root_source_file = .{ .path = "src/cli/main.zig" }, .target = target, .optimize = optimize, }); // Add dependencies exe.linkLibC(); exe.addIncludePath(.{ .path = "include" }); b.installArtifact(exe); } </code></pre></div>Build modes: <ul> <li><code>Debug</code>: Fast compilation, runtime safety checks, debug symbols</li> <li><code>ReleaseSafe</code>: Optimized with safety checks (recommended for production)</li> <li><code>ReleaseFast</code>: Maximum optimization, safety checks disabled</li> <li><code>ReleaseSmall</code>: Optimize for binary size</li> </ul> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Specify build mode explicitly zig build -Doptimize=ReleaseSafe </code></pre></div> <h4 id="development-workflow" class="position-relative d-flex align-items-center group"> Development Workflow <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="development-workflow" aria-haspopup="dialog" aria-label="Share link: Development Workflow"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Fast iteration during development zig build && ./zig-out/bin/geode serve # Run specific tests zig build test --summary all # Check for issues without building zig build check # Format code zig fmt src/ # Generate documentation zig build docs </code></pre></div> <h3 id="contributing-to-geode" class="position-relative d-flex align-items-center group"> Contributing to Geode <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="contributing-to-geode" aria-haspopup="dialog" aria-label="Share link: Contributing to Geode"> Share link </button> </h3>Geode welcomes contributions from the community. The codebase follows evidence-based development practices with CANARY markers tracking requirements and implementations. <h4 id="getting-started" class="position-relative d-flex align-items-center group"> Getting Started <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="getting-started" aria-haspopup="dialog" aria-label="Share link: Getting Started"> Share link </button> </h4><ol> <li>Read the contribution guide: See <code>geode/CLAUDE.md</code> and <code>geode/docs/CONTRIBUTING.md</code></li> <li>Set up development environment: Install Zig 0.1.0+</li> <li>Build and test: Ensure <code>make test</code> passes</li> <li>Pick an issue: Check GitLab issues for good first issues</li> </ol> <h4 id="code-style" class="position-relative d-flex align-items-center group"> Code Style <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="code-style" aria-haspopup="dialog" aria-label="Share link: Code Style"> Share link </button> </h4>Geode follows Zig’s standard formatting: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Format code automatically zig fmt src/ zig fmt geode/ </code></pre></div>Naming conventions: <ul> <li><code>camelCase</code> for local variables and functions</li> <li><code>PascalCase</code> for types and namespaces</li> <li><code>SCREAMING_SNAKE_CASE</code> for constants</li> <li>Descriptive names preferred over abbreviations</li> </ul> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Good const QueryExecutor = struct { const MAX_QUERY_DEPTH = 10; pub fn executeQuery(self: *QueryExecutor, query: []const u8) !Result { var resultBuffer = try self.allocator.alloc(u8, 1024); defer self.allocator.free(resultBuffer); // ... } }; // Avoid const QE = struct { const mqd = 10; pub fn eq(s: *QE, q: []const u8) !R { ... } }; </code></pre></div> <h4 id="memory-management-patterns" class="position-relative d-flex align-items-center group"> Memory Management Patterns <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="memory-management-patterns" aria-haspopup="dialog" aria-label="Share link: Memory Management Patterns"> Share link </button> </h4>Always use explicit allocators: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">pub fn processData(allocator: std.mem.Allocator, input: []const u8) ![]u8 { // Allocate memory var buffer = try allocator.alloc(u8, input.len * 2); errdefer allocator.free(buffer); // Cleanup on error // Process data @memcpy(buffer[0..input.len], input); return buffer; // Caller owns memory } // Caller's responsibility to free const result = try processData(allocator, data); defer allocator.free(result); </code></pre></div>Arena allocators for temporary allocations: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">pub fn handleQuery(gpa: std.mem.Allocator, query: []const u8) !void { var arena = std.heap.ArenaAllocator.init(gpa); defer arena.deinit(); // Frees all allocations at once const allocator = arena.allocator(); // All allocations automatically freed when arena is destroyed const parsed = try parseQuery(allocator, query); const optimized = try optimizeQuery(allocator, parsed); const result = try executeQuery(allocator, optimized); } </code></pre></div> <h4 id="error-handling-patterns" class="position-relative d-flex align-items-center group"> Error Handling Patterns <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-handling-patterns" aria-haspopup="dialog" aria-label="Share link: Error Handling Patterns"> Share link </button> </h4>Define error sets clearly: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const DatabaseError = error{ ConnectionFailed, QueryTimeout, ConstraintViolation, OutOfMemory, }; pub fn connect(config: Config) DatabaseError!Connection { if (config.host.len == 0) { return error.ConnectionFailed; } // ... } </code></pre></div>Use error unions and handle appropriately: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Propagate errors const result = try riskyOperation(); // Handle specific errors const result = riskyOperation() catch |err| switch (err) { error.FileNotFound => return default, error.OutOfMemory => return error.OutOfMemory, else => |e| return e, }; // Provide context with error traces const result = riskyOperation() catch |err| { std.log.err("Failed to process: {}", .{err}); return err; }; </code></pre></div> <h4 id="testing" class="position-relative d-flex align-items-center group"> Testing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="testing" aria-haspopup="dialog" aria-label="Share link: Testing"> Share link </button> </h4>Write comprehensive tests: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const testing = std.testing; test "query execution handles syntax errors" { const query = "INVALID GQL SYNTAX"; const result = executeQuery(query); try testing.expectError(error.SyntaxError, result); } test "index lookup returns correct values" { var index = try Index.init(testing.allocator); defer index.deinit(); try index.insert("key1", 100); try index.insert("key2", 200); try testing.expectEqual(@as(u64, 100), index.lookup("key1").?); try testing.expectEqual(@as(u64, 200), index.lookup("key2").?); try testing.expectEqual(@as(?u64, null), index.lookup("key3")); } </code></pre></div>Run tests with coverage: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">zig build test --summary all </code></pre></div> <h4 id="canary-markers" class="position-relative d-flex align-items-center group"> CANARY Markers <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="canary-markers" aria-haspopup="dialog" aria-label="Share link: CANARY Markers"> Share link </button> </h4>Geode uses CANARY governance markers to track requirements: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// CANARY: REQ=REQ-XXX; FEATURE="PatternMatching"; ASPECT=BasicMatch; STATUS=TESTED; TEST=TestBasicNodePattern; OWNER=engine; UPDATED=2026-01-24 // Requirement: Implement basic node pattern matching // Evidence: TestBasicNodePattern pub fn matchNodePattern(pattern: NodePattern) ![]Node { // Implementation } </code></pre></div>When implementing features: <ol> <li>Find or create CANARY marker</li> <li>Implement functionality</li> <li>Add tests as evidence</li> <li>Reference tests in CANARY comment</li> </ol> <h4 id="documentation" class="position-relative d-flex align-items-center group"> Documentation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="documentation" aria-haspopup="dialog" aria-label="Share link: Documentation"> Share link </button> </h4>Document public APIs with doc comments: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">/// Executes a GQL query and returns results. /// /// Parameters: /// - allocator: Memory allocator for result allocation /// - query: GQL query string /// - params: Query parameters (optional) /// /// Returns: /// Query results on success, error on failure. /// /// Errors: /// - SyntaxError: Invalid GQL syntax /// - AuthenticationFailed: User not authenticated /// - OutOfMemory: Insufficient memory pub fn executeQuery( allocator: std.mem.Allocator, query: []const u8, params: ?QueryParams, ) !QueryResult { // Implementation } </code></pre></div> <h3 id="zig-resources-for-geode-contributors" class="position-relative d-flex align-items-center group"> Zig Resources for Geode Contributors <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="zig-resources-for-geode-contributors" aria-haspopup="dialog" aria-label="Share link: Zig Resources for Geode Contributors"> Share link </button> </h3>Official Documentation: <ul> <li><a href="https://ziglang.org/documentation/master/" aria-label="Zig Language Reference – opens in new window" target="_blank" rel="noopener noreferrer" >Zig Language Reference ↗ </a> </li> <li><a href="https://ziglang.org/documentation/master/std/" aria-label="Zig Standard Library – opens in new window" target="_blank" rel="noopener noreferrer" >Zig Standard Library ↗ </a> </li> </ul> Learning Resources: <ul> <li><a href="https://ziglearn.org/" aria-label="Zig Learn – opens in new window" target="_blank" rel="noopener noreferrer" >Zig Learn ↗ </a> - Interactive tutorial</li> <li><a href="https://zig-by-example.com/" aria-label="Zig By Example – opens in new window" target="_blank" rel="noopener noreferrer" >Zig By Example ↗ </a> - Code examples</li> <li><a href="https://zig.news/" aria-label="Zig News – opens in new window" target="_blank" rel="noopener noreferrer" >Zig News ↗ </a> - Community articles</li> </ul> Community: <ul> <li>Zig Discord server</li> <li>Zig subreddit (r/zig)</li> <li>Zig forum</li> </ul> <h3 id="zig-client-library" class="position-relative d-flex align-items-center group"> Zig Client Library <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="zig-client-library" aria-haspopup="dialog" aria-label="Share link: Zig Client Library"> Share link </button> </h3>Geode provides a native Zig client library: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const std = @import("std"); const geode = @import("geode_client"); pub fn main() !void { var gpa = std.heap.GeneralPurposeAllocator(.{}){}; defer _ = gpa.deinit(); const allocator = gpa.allocator(); // Connect to Geode var client = try geode.Client.connect(allocator, .{ .host = "localhost", .port = 3141, }); defer client.deinit(); // Execute query const result = try client.execute( \\MATCH (n:Node) \\RETURN n.name \\LIMIT 10 , .{}); defer result.deinit(); // Process results while (try result.next()) |row| { const name = row.get("n.name").?.asString(); std.debug.print("Name: {s}\n", .{name}); } } </code></pre></div> <h3 id="best-practices-for-zig-in-geode" class="position-relative d-flex align-items-center group"> Best Practices for Zig in Geode <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices-for-zig-in-geode" aria-haspopup="dialog" aria-label="Share link: Best Practices for Zig in Geode"> Share link </button> </h3><ol> <li>Use explicit allocators: Pass allocators as parameters</li> <li>Leverage comptime: Generate code at compile time when possible</li> <li>Handle errors explicitly: Never ignore error returns</li> <li>Prefer defer for cleanup: Resource cleanup with defer/errdefer</li> <li>Write comprehensive tests: Test both happy and error paths</li> <li>Document public APIs: Use doc comments for public functions</li> <li>Follow Zig idioms: Study standard library for patterns</li> <li>Profile performance: Use Zig’s built-in profiling tools</li> </ol> <h3 id="related-topics" class="position-relative d-flex align-items-center group"> Related Topics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-topics" aria-haspopup="dialog" aria-label="Share link: Related Topics"> Share link </button> </h3><ul> <li><a href="/categories/development/" >Development</a> - Development workflows</li> <li><a href="/categories/contributing/" >Contributing</a> - Contribution guidelines</li> <li><a href="/docs/architecture/" >Architecture</a> - Geode’s system architecture</li> <li><a href="/docs/development/" >Development Guide</a> - Building and development instructions</li> <li><a href="/tags/testing/" >Testing</a> - Testing strategies</li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li><a href="https://ziglang.org/learn/" aria-label="Zig Language Guide – opens in new window" target="_blank" rel="noopener noreferrer" >Zig Language Guide ↗ </a> - Official learning resources</li> <li><a href="/docs/architecture/" >Geode Architecture</a> - How Geode is structured</li> <li><a href="/docs/contribute/" >Contributing Guide</a> - Detailed contribution process</li> <li><a href="/docs/development/testing-guide/" >Testing Guide</a> - Testing strategies and patterns</li> </ul>

Popular

Related Articles