Session Management Guide | Geode Database

<h3 id="overview" class="position-relative d-flex align-items-center group"> Overview <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="overview" aria-haspopup="dialog" aria-label="Share link: Overview"> 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 provides comprehensive session management features for maintaining stateful connections to the database. Sessions enable parameter storage, transaction management, connection pooling, and timeout configuration. <h4 id="what-youll-learn" class="position-relative d-flex align-items-center group"> What You&rsquo;ll Learn <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="what-youll-learn" aria-haspopup="dialog" aria-label="Share link: What Youll Learn"> Share link </button> </h4><ul> <li>How to use session parameters (GRAPH, VALUE, BINDING TABLE)</li> <li>Connection pooling configuration and best practices</li> <li>Session lifecycle and timeout management</li> <li>Session state persistence and restoration</li> <li>Advanced session patterns for multi-tenant applications</li> </ul> <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><ul> <li>Geode installed (see <a href="/guides/installation/" >Installation Guide</a> )</li> <li>Basic understanding of database sessions</li> <li>Familiarity with GQL query syntax</li> </ul> <h3 id="session-parameters" class="position-relative d-flex align-items-center group"> Session Parameters <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="session-parameters" aria-haspopup="dialog" aria-label="Share link: Session Parameters"> Share link </button> </h3>Session parameters allow you to store named values that persist across queries within a session. Geode supports three types of session parameters according to ISO/IEC 39075:2024. <h4 id="1-graph-parameters" class="position-relative d-flex align-items-center group"> 1. Graph Parameters <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="1-graph-parameters" aria-haspopup="dialog" aria-label="Share link: 1. Graph Parameters"> Share link </button> </h4>Graph parameters store references to graphs for use in graph pattern queries. Syntax: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">SESSION SET GRAPH [$param_name] = <graph_expression> [IF NOT EXISTS] </code></pre></div>Examples: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Set current graph as parameter SESSION SET GRAPH $my_graph = CURRENT_GRAPH -- Set specific graph SESSION SET GRAPH $social = social_network -- Conditional set (only if doesn't exist) SESSION SET GRAPH IF NOT EXISTS $default_graph = main_graph -- Reference graph parameter in queries (planned feature) USE GRAPH $my_graph MATCH (n:Person) RETURN n </code></pre></div>Use Cases: <ul> <li>Multi-graph applications</li> <li>Dynamic graph selection</li> <li>Graph isolation for testing</li> <li>Multi-tenant graph separation</li> </ul> <h4 id="2-value-parameters" class="position-relative d-flex align-items-center group"> 2. Value Parameters <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="2-value-parameters" aria-haspopup="dialog" aria-label="Share link: 2. Value Parameters"> Share link </button> </h4>Value parameters store scalar values (integers, strings, booleans, etc.) for use in queries. Syntax: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">SESSION SET VALUE [$param_name] = <expression> [IF NOT EXISTS] </code></pre></div>Examples: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Set integer value SESSION SET VALUE $counter = 42 -- Set string value SESSION SET VALUE $username = 'alice' -- Set boolean value SESSION SET VALUE $enabled = true -- Set computed value SESSION SET VALUE $max_age = 18 * 5 -- 90 -- Conditional set SESSION SET VALUE IF NOT EXISTS $default_limit = 100 </code></pre></div>Using in Queries: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Set parameter SESSION SET VALUE $min_age = 25 -- Use in query MATCH (p:Person) WHERE p.age >= $min_age RETURN p.name, p.age ORDER BY p.age DESC </code></pre></div>Use Cases: <ul> <li>Query parameterization</li> <li>Default value configuration</li> <li>User preferences</li> <li>Application state</li> </ul> <h4 id="3-binding-table-parameters" class="position-relative d-flex align-items-center group"> 3. Binding Table Parameters <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="3-binding-table-parameters" aria-haspopup="dialog" aria-label="Share link: 3. Binding Table Parameters"> Share link </button> </h4>Binding table parameters store references to binding tables (result sets) for use in queries. Syntax: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">SESSION SET [BINDING] TABLE [$param_name] = <binding_table_ref> [IF NOT EXISTS] </code></pre></div>Examples: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Set binding table SESSION SET BINDING TABLE $my_table = user_bindings -- Shorthand syntax (BINDING is optional) SESSION SET TABLE $results = query_results -- Store query results SESSION SET TABLE $active_users = ( MATCH (u:User) WHERE u.active = true RETURN u.id, u.name ) -- Reference in subsequent queries MATCH (u:User) WHERE u.id IN $active_users.id RETURN u </code></pre></div>Use Cases: <ul> <li>Temporary result storage</li> <li>Query composition</li> <li>Performance optimization (avoiding repeated queries)</li> <li>Complex multi-step analytics</li> </ul> <h3 id="session-reset" class="position-relative d-flex align-items-center group"> Session Reset <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="session-reset" aria-haspopup="dialog" aria-label="Share link: Session Reset"> Share link </button> </h3>The <code>SESSION RESET</code> command clears session state, including parameters. Syntax: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">SESSION RESET [ALL] PARAMETERS -- Reset all parameters SESSION RESET PARAMETERS -- Same as ALL PARAMETERS SESSION RESET PARAMETER $name -- Reset specific parameter SESSION RESET GRAPH -- Reset current graph SESSION RESET TIME ZONE -- Reset time zone SESSION RESET -- Reset all session state </code></pre></div>Examples: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Reset all parameters SESSION RESET ALL PARAMETERS -- Reset specific parameter SESSION SET VALUE $temp = 123 SESSION RESET PARAMETER $temp -- Reset graph setting SESSION SET GRAPH $g = my_graph SESSION RESET GRAPH -- Reset time zone SESSION SET TIME ZONE 'America/New_York' SESSION RESET TIME ZONE -- Reset everything SESSION RESET </code></pre></div>What Gets Reset: <ul> <li>All session parameters (GRAPH, VALUE, TABLE)</li> <li>Current graph selection</li> <li>Time zone setting</li> <li>Transaction state (if applicable)</li> <li>Custom session variables</li> </ul> <h3 id="connection-pooling" class="position-relative d-flex align-items-center group"> Connection Pooling <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="connection-pooling" aria-haspopup="dialog" aria-label="Share link: Connection Pooling"> Share link </button> </h3> <h4 id="client-side-pooling" class="position-relative d-flex align-items-center group"> Client-Side Pooling <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="client-side-pooling" aria-haspopup="dialog" aria-label="Share link: Client-Side Pooling"> Share link </button> </h4>All Geode clients support connection pooling for optimal resource utilization and performance. <h5 id="go-client-pooling" class="position-relative d-flex align-items-center group"> Go Client Pooling <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="go-client-pooling" aria-haspopup="dialog" aria-label="Share link: Go Client Pooling"> Share link </button> </h5><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">import "geodedb.com/geode" // Create connection pool pool, err := geode.NewConnectionPool(&geode.PoolConfig{ Address: "localhost:3141", MinConnections: 5, MaxConnections: 50, IdleTimeout: time.Minute * 10, ConnectTimeout: time.Second * 30, MaxLifetime: time.Hour, }) if err != nil { log.Fatal(err) } defer pool.Close() // Execute queries (automatically uses pooled connections) result, err := pool.Query(ctx, "MATCH (n:Person) RETURN n LIMIT 10") </code></pre></div>Configuration: <ul> <li><code>MinConnections</code>: Minimum pool size (default: 5)</li> <li><code>MaxConnections</code>: Maximum pool size (default: 100)</li> <li><code>IdleTimeout</code>: Close idle connections after this duration</li> <li><code>ConnectTimeout</code>: Connection establishment timeout</li> <li><code>MaxLifetime</code>: Maximum connection lifetime</li> </ul> <h5 id="python-client-pooling" class="position-relative d-flex align-items-center group"> Python Client Pooling <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="python-client-pooling" aria-haspopup="dialog" aria-label="Share link: Python Client Pooling"> Share link </button> </h5><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import ConnectionPool # Create connection pool (async) pool = await ConnectionPool.create( host='localhost', port=3141, min_connections=5, max_connections=50, idle_timeout=600, # 10 minutes max_lifetime=3600, # 1 hour ) # Execute queries (async) async with pool.acquire() as conn: result, _ = await conn.query("MATCH (n:Person) RETURN n LIMIT 10") # Cleanup await pool.close() </code></pre></div>Performance: Throughput depends on workload, network, and server limits; pooling reduces connection overhead <h5 id="rust-client-pooling" class="position-relative d-flex align-items-center group"> Rust Client Pooling <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="rust-client-pooling" aria-haspopup="dialog" aria-label="Share link: Rust Client Pooling"> Share link </button> </h5><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">use geode_client::ConnectionPool; let pool = ConnectionPool::new("localhost", 3141, 10).skip_verify(true); let mut conn = pool.acquire().await?; let (page, _) = conn.query("MATCH (n:Person) RETURN n LIMIT 10").await?; </code></pre></div>Performance: Throughput depends on workload, network, and server limits; pooling reduces connection overhead <h5 id="zig-client-pooling" class="position-relative d-flex align-items-center group"> Zig Client Pooling <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-pooling" aria-haspopup="dialog" aria-label="Share link: Zig Client Pooling"> Share link </button> </h5>The Zig client exposes low-level protocol primitives. Build pooling at the application layer or wrap <code>GeodeClient</code> with your own pool implementation. <h4 id="server-side-configuration" class="position-relative d-flex align-items-center group"> Server-Side 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="server-side-configuration" aria-haspopup="dialog" aria-label="Share link: Server-Side Configuration"> Share link </button> </h4>Configure server-side connection limits: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># geode.yaml network: max_connections: 5000 connection_timeout: 60s idle_timeout: 300s performance: worker_threads: 16 max_concurrent_queries: 1000 </code></pre></div>Command-Line: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">geode serve \ --max-connections 5000 \ --connection-timeout 60s \ --idle-timeout 300s \ --worker-threads 16 </code></pre></div>Environment Variables: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">export GEODE_MAX_CONNECTIONS=5000 export GEODE_CONNECTION_TIMEOUT=60s export GEODE_IDLE_TIMEOUT=300s </code></pre></div> <h3 id="timeout-configuration" class="position-relative d-flex align-items-center group"> Timeout 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="timeout-configuration" aria-haspopup="dialog" aria-label="Share link: Timeout Configuration"> Share link </button> </h3> <h4 id="connection-timeout" class="position-relative d-flex align-items-center group"> Connection Timeout <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="connection-timeout" aria-haspopup="dialog" aria-label="Share link: Connection Timeout"> Share link </button> </h4>Time limit for establishing a connection: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># Server configuration network: connection_timeout: 30s </code></pre></div>Client Configuration: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Go config := &geode.Config{ ConnectTimeout: 30 * time.Second, } </code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Python config = ConnectionConfig( connect_timeout=30.0, ) </code></pre></div> <h4 id="query-timeout" class="position-relative d-flex align-items-center group"> Query Timeout <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="query-timeout" aria-haspopup="dialog" aria-label="Share link: Query Timeout"> Share link </button> </h4>Time limit for query execution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># Server configuration performance: query_timeout: 300s # 5 minutes default_timeout: 60s # Default for queries without explicit timeout </code></pre></div>Client-Side Timeout: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Go: Context-based timeout ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second) defer cancel() result, err := conn.Query(ctx, "MATCH (n) RETURN count(n)") </code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Python: asyncio timeout result = await asyncio.wait_for( conn.query("MATCH (n) RETURN count(n)"), timeout=60.0 ) </code></pre></div> <h4 id="idle-timeout" class="position-relative d-flex align-items-center group"> Idle Timeout <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="idle-timeout" aria-haspopup="dialog" aria-label="Share link: Idle Timeout"> Share link </button> </h4>Close connections idle for this duration: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># Server configuration network: idle_timeout: 600s # 10 minutes </code></pre></div>Behavior: <ul> <li>Server monitors idle connections</li> <li>Connections inactive for <code>idle_timeout</code> are closed</li> <li>Client pools automatically reconnect as needed</li> <li>Prevents resource exhaustion from abandoned connections</li> </ul> <h4 id="transaction-timeout" class="position-relative d-flex align-items-center group"> Transaction Timeout <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="transaction-timeout" aria-haspopup="dialog" aria-label="Share link: Transaction Timeout"> Share link </button> </h4>Time limit for transaction duration: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># Server configuration transactions: timeout: 3600s # 1 hour idle_timeout: 300s # 5 minutes </code></pre></div>Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Begin transaction BEGIN TRANSACTION -- Long-running operations MATCH (n:Person) SET n.processed = true -- Must complete within transaction_timeout COMMIT </code></pre></div> <h3 id="session-lifecycle" class="position-relative d-flex align-items-center group"> Session Lifecycle <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="session-lifecycle" aria-haspopup="dialog" aria-label="Share link: Session Lifecycle"> Share link </button> </h3> <h4 id="session-creation" class="position-relative d-flex align-items-center group"> Session Creation <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="session-creation" aria-haspopup="dialog" aria-label="Share link: Session Creation"> Share link </button> </h4>Sessions are created automatically on first connection: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Go: database/sql creates sessions on first use db, err := sql.Open("geode", "localhost:3141") _ = db.Ping() // Session ID assigned automatically </code></pre></div>Session ID Format: UUID v4 (e.g., <code>550e8400-e29b-41d4-a716-446655440000</code>) <h4 id="session-state" class="position-relative d-flex align-items-center group"> Session State <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="session-state" aria-haspopup="dialog" aria-label="Share link: Session State"> Share link </button> </h4>Each session maintains: <ol> <li>Parameters: User-defined variables ($param_name)</li> <li>Transaction State: Active transaction (if any)</li> <li>Current Graph: Selected graph context</li> <li>Time Zone: Session time zone setting</li> <li>Connection Metadata: Client info, connection time</li> </ol> <h4 id="session-persistence" class="position-relative d-flex align-items-center group"> Session Persistence <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="session-persistence" aria-haspopup="dialog" aria-label="Share link: Session Persistence"> Share link </button> </h4>Session state persists until: <ul> <li>Explicit <code>SESSION RESET</code> command</li> <li>Connection closed</li> <li>Session timeout (server-side)</li> <li>Server restart (sessions not persisted across restarts)</li> </ul> <h4 id="session-cleanup" class="position-relative d-flex align-items-center group"> Session Cleanup <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="session-cleanup" aria-haspopup="dialog" aria-label="Share link: Session Cleanup"> Share link </button> </h4>Graceful Cleanup: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Go: Explicit cleanup defer db.Close() </code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Python: Context manager async with pool.acquire() as conn: # Session automatically cleaned up on exit pass </code></pre></div>Server-Side Cleanup: <ul> <li>Idle sessions cleaned up after <code>idle_timeout</code></li> <li>Abandoned transactions rolled back after <code>transaction_timeout</code></li> <li>Resources released (memory, file handles)</li> </ul> <h3 id="advanced-session-patterns" class="position-relative d-flex align-items-center group"> Advanced Session 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="advanced-session-patterns" aria-haspopup="dialog" aria-label="Share link: Advanced Session Patterns"> Share link </button> </h3> <h4 id="multi-tenant-sessions" class="position-relative d-flex align-items-center group"> Multi-Tenant Sessions <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="multi-tenant-sessions" aria-haspopup="dialog" aria-label="Share link: Multi-Tenant Sessions"> Share link </button> </h4>Isolate tenants using session parameters: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Set tenant context SESSION SET VALUE $tenant_id = 'acme-corp' -- Automatically filter by tenant MATCH (n:Customer) WHERE n.tenant_id = $tenant_id RETURN n </code></pre></div>Enforcement with Row-Level Security: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Policy automatically applied CREATE POLICY tenant_isolation FOR Customer USING (tenant_id = session_parameter('tenant_id')) </code></pre></div> <h4 id="session-based-caching" class="position-relative d-flex align-items-center group"> Session-Based Caching <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="session-based-caching" aria-haspopup="dialog" aria-label="Share link: Session-Based Caching"> Share link </button> </h4>Cache query results in session: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- First query: expensive computation SESSION SET TABLE $recent_orders = ( MATCH (o:Order) WHERE o.timestamp > datetime() - duration('P7D') RETURN o.id, o.customer_id, o.total ) -- Subsequent queries: use cached results MATCH (c:Customer) WHERE c.id IN $recent_orders.customer_id RETURN c.name, sum($recent_orders.total) AS total_spent </code></pre></div> <h4 id="session-state-snapshots" class="position-relative d-flex align-items-center group"> Session State Snapshots <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="session-state-snapshots" aria-haspopup="dialog" aria-label="Share link: Session State Snapshots"> Share link </button> </h4>Save and restore session state: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Save current state SESSION SET VALUE $saved_graph = CURRENT_GRAPH SESSION SET VALUE $saved_tz = CURRENT_TIMEZONE -- Make temporary changes USE GRAPH temp_graph SET TIME ZONE 'UTC' -- Restore state USE GRAPH $saved_graph SET TIME ZONE $saved_tz </code></pre></div> <h4 id="stateful-workflows" class="position-relative d-flex align-items-center group"> Stateful Workflows <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="stateful-workflows" aria-haspopup="dialog" aria-label="Share link: Stateful Workflows"> Share link </button> </h4>Implement multi-step workflows: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Step 1: Initialize workflow SESSION SET VALUE $workflow_id = uuid() SESSION SET VALUE $step = 1 -- Step 2: Process data MATCH (n:RawData) WHERE n.workflow_id = $workflow_id CREATE (p:ProcessedData { id: uuid(), workflow_id: $workflow_id, step: $step, data: n.data }) SESSION SET VALUE $step = $step + 1 -- Step 3: Validate MATCH (p:ProcessedData) WHERE p.workflow_id = $workflow_id AND p.step = $step - 1 -- Validation logic... -- Step 4: Finalize SESSION RESET PARAMETERS </code></pre></div> <h3 id="session-security" class="position-relative d-flex align-items-center group"> Session Security <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="session-security" aria-haspopup="dialog" aria-label="Share link: Session Security"> Share link </button> </h3> <h4 id="parameter-validation" class="position-relative d-flex align-items-center group"> Parameter Validation <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="parameter-validation" aria-haspopup="dialog" aria-label="Share link: Parameter Validation"> Share link </button> </h4>Always validate session parameters: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- ❌ Unsafe: No validation SESSION SET VALUE $user_input = $raw_input -- ✅ Safe: Validate before setting SESSION SET VALUE $validated_age = CASE WHEN $user_input >= 0 AND $user_input <= 150 THEN $user_input ELSE NULL END </code></pre></div> <h4 id="session-hijacking-prevention" class="position-relative d-flex align-items-center group"> Session Hijacking Prevention <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="session-hijacking-prevention" aria-haspopup="dialog" aria-label="Share link: Session Hijacking Prevention"> Share link </button> </h4>Server-Side Protection: <ul> <li>TLS 1.3 required (encrypted transport)</li> <li>Session IDs cryptographically random</li> <li>Session binding to client IP (optional)</li> <li>Session timeout enforcement</li> </ul> Client-Side Best Practices: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Go: Secure configuration config := &geode.Config{ TLS: true, VerifyCertificate: true, SessionTimeout: 3600, // 1 hour } </code></pre></div> <h4 id="sensitive-data-handling" class="position-relative d-flex align-items-center group"> Sensitive Data 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="sensitive-data-handling" aria-haspopup="dialog" aria-label="Share link: Sensitive Data Handling"> Share link </button> </h4>Avoid storing sensitive data in session parameters: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- ❌ Unsafe: Password in session SESSION SET VALUE $password = 'secret123' -- ✅ Safe: Use secure parameter passing MATCH (u:User) WHERE u.username = $username AND verify_password(u.password_hash, $password) RETURN u -- $password passed via prepared statement, not stored </code></pre></div> <h3 id="monitoring-and-debugging" class="position-relative d-flex align-items-center group"> Monitoring and Debugging <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="monitoring-and-debugging" aria-haspopup="dialog" aria-label="Share link: Monitoring and Debugging"> Share link </button> </h3> <h4 id="session-inspection" class="position-relative d-flex align-items-center group"> Session Inspection <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="session-inspection" aria-haspopup="dialog" aria-label="Share link: Session Inspection"> Share link </button> </h4>Query current session state: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Show current session parameters SHOW SESSION PARAMETERS -- Show current graph SHOW CURRENT_GRAPH -- Show time zone SHOW TIME ZONE -- Show session info SHOW SESSION INFO </code></pre></div> <h4 id="session-metrics" class="position-relative d-flex align-items-center group"> Session Metrics <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="session-metrics" aria-haspopup="dialog" aria-label="Share link: Session Metrics"> Share link </button> </h4>Monitor session activity (server-side): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Prometheus metrics endpoint curl http://localhost:9090/metrics | grep session # Example metrics: # geode_active_sessions{} 42 # geode_session_create_total{} 1234 # geode_session_timeout_total{} 5 # geode_avg_session_duration_seconds{} 180.5 </code></pre></div> <h4 id="session-logging" class="position-relative d-flex align-items-center group"> Session Logging <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="session-logging" aria-haspopup="dialog" aria-label="Share link: Session Logging"> Share link </button> </h4>Enable session debugging: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"># geode.yaml logging: level: debug modules: session: trace </code></pre></div>Log Output: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">[SESSION] Created session: 550e8400-e29b-41d4-a716-446655440000 [SESSION] Set parameter: $username = 'alice' [SESSION] Transaction started [SESSION] Transaction committed [SESSION] Idle timeout: closing session </code></pre></div> <h3 id="troubleshooting" class="position-relative d-flex align-items-center group"> Troubleshooting <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="troubleshooting" aria-haspopup="dialog" aria-label="Share link: Troubleshooting"> Share link </button> </h3> <h4 id="connection-pool-exhaustion" class="position-relative d-flex align-items-center group"> Connection Pool Exhaustion <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="connection-pool-exhaustion" aria-haspopup="dialog" aria-label="Share link: Connection Pool Exhaustion"> Share link </button> </h4>Symptom: “Connection pool exhausted” error Solutions: <ol> <li> Increase <code>max_connections</code>: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">config.MaxConnections = 200 </code></pre></div></li> <li> Decrease <code>idle_timeout</code> to reclaim connections faster: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">config.IdleTimeout = 5 * time.Minute </code></pre></div></li> <li> Check for connection leaks: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Always close connections defer conn.Close() </code></pre></div></li> </ol> <h4 id="session-timeout" class="position-relative d-flex align-items-center group"> Session Timeout <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="session-timeout" aria-haspopup="dialog" aria-label="Share link: Session Timeout"> Share link </button> </h4>Symptom: “Session expired” or “Session not found” error Solutions: <ol> <li> Increase session timeout: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml">network: idle_timeout: 1800s # 30 minutes </code></pre></div></li> <li> Use keep-alive queries: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">ticker := time.NewTicker(5 * time.Minute) go func() { for range ticker.C { _, _ = db.QueryContext(ctx, "RETURN 1") // Keep-alive } }() </code></pre></div></li> <li> Re-establish connection on timeout: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">if errors.Is(err, geode.ErrBadConn) { db, err = sql.Open("geode", address) _ = db.Ping() } </code></pre></div></li> </ol> <h4 id="parameter-not-found" class="position-relative d-flex align-items-center group"> Parameter Not Found <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="parameter-not-found" aria-haspopup="dialog" aria-label="Share link: Parameter Not Found"> Share link </button> </h4>Symptom: “Parameter $name not found” error Solutions: <ol> <li> Set parameter before use: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">SESSION SET VALUE $name = 'Alice' MATCH (n:Person) WHERE n.name = $name RETURN n </code></pre></div></li> <li> Use <code>IF NOT EXISTS</code> for default values: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">SESSION SET VALUE IF NOT EXISTS $limit = 100 </code></pre></div></li> <li> Check parameter scope (session-local): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Different sessions have different parameters SESSION RESET PARAMETERS -- Clears all </code></pre></div></li> </ol> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <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" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3> <h4 id="connection-lifecycle" class="position-relative d-flex align-items-center group"> Connection Lifecycle <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="connection-lifecycle" aria-haspopup="dialog" aria-label="Share link: Connection Lifecycle"> Share link </button> </h4><ol> <li>Use connection pooling for multi-user applications</li> <li>Always close connections explicitly (defer in Go, context managers in Python)</li> <li>Set appropriate timeouts based on workload</li> <li>Monitor pool metrics (active connections, wait time, etc.)</li> </ol> <h4 id="parameter-management" class="position-relative d-flex align-items-center group"> Parameter Management <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="parameter-management" aria-haspopup="dialog" aria-label="Share link: Parameter Management"> Share link </button> </h4><ol> <li>Name parameters clearly: <code>$user_id</code> not <code>$x</code></li> <li>Validate inputs before setting parameters</li> <li>Use IF NOT EXISTS for default values</li> <li>Reset parameters after workflows complete</li> <li>Document parameter contracts for team consistency</li> </ol> <h4 id="performance-optimization" class="position-relative d-flex align-items-center group"> Performance Optimization <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-optimization" aria-haspopup="dialog" aria-label="Share link: Performance Optimization"> Share link </button> </h4><ol> <li>Reuse connections via pooling (significantly faster than creating new connections)</li> <li>Batch queries when possible to reduce round-trips</li> <li>Use prepared statements for repeated queries</li> <li>Set realistic timeouts (too short = failures, too long = resource waste)</li> <li>Monitor session duration and optimize long-running sessions</li> </ol> <h4 id="security-hardening" class="position-relative d-flex align-items-center group"> Security Hardening <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="security-hardening" aria-haspopup="dialog" aria-label="Share link: Security Hardening"> Share link </button> </h4><ol> <li>Always use TLS for production</li> <li>Validate all session parameters from user input</li> <li>Implement session timeout to limit exposure</li> <li>Audit session creation/destruction for compliance</li> <li>Use row-level security with session parameters for multi-tenancy</li> </ol> <h3 id="next-steps" class="position-relative d-flex align-items-center group"> Next Steps <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="next-steps" aria-haspopup="dialog" aria-label="Share link: Next Steps"> Share link </button> </h3>Explore More: <ul> <li><a href="/docs/transactions/overview/" >Transaction Management</a> - ACID transactions</li> <li><a href="/docs/client-libraries/" >Connection Pooling</a> - Client-specific pooling</li> <li><a href="/docs/security/overview/" >Security Overview</a> - Authentication and authorization</li> </ul> Related Topics: <ul> <li><a href="/docs/security/overview/#row-level-security" >Row-Level Security</a> - Policy-based access control</li> <li><a href="/docs/ops/observability/" >Monitoring</a> - Session metrics and monitoring</li> <li><a href="/docs/query/performance-tuning/" >Performance Tuning</a> - Optimize query and session performance</li> </ul> Client Libraries: <ul> <li><a href="/docs/client-libraries/go-client/" >Go Client</a> - Go connection pooling</li> <li><a href="/docs/client-libraries/python-client/" >Python Client</a> - Python async pooling</li> <li><a href="/docs/client-libraries/rust-client/" >Rust Client</a> - Rust tokio pooling</li> </ul> <hr> ISO Standard: ISO/IEC 39075:2024 §15.3-15.4 Session Types: GRAPH, VALUE, BINDING TABLE parameters Pooling: All 5 client libraries (Go, Python, Rust, Node.js, Zig) Status: Production-ready