<!-- CANARY: REQ=REQ-DOCS-001; FEATURE="Docs"; ASPECT=Documentation; STATUS=TESTED; OWNER=docs; UPDATED=2026-03-25 -->
<h2 id="geode-dsn-data-source-name-specification" class="position-relative d-flex align-items-center group">
<span>Geode DSN (Data Source Name) Specification</span>
<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="geode-dsn-data-source-name-specification"
aria-haspopup="dialog"
aria-label="Share link: Geode DSN (Data Source Name) Specification">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h2><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">
<i class="fa-solid fa-xmark"></i>
</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">
<i class="fa-duotone fa-clipboard" aria-hidden="true"></i>
</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">
<i class="fa-brands fa-twitter me-2"></i>Twitter
</a>
<a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-linkedin me-2"></i>LinkedIn
</a>
<a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-facebook me-2"></i>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><p><strong>Version</strong>: 1.1.0
<strong>Status</strong>: Official Specification
<strong>Last Updated</strong>: 2026-03-25</p>
<p>This document defines the official DSN (Data Source Name) format for Geode client libraries. All client implementations MUST conform to this specification.</p>
<h3 id="overview" class="position-relative d-flex align-items-center group">
<span>Overview</span>
<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">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><p>A DSN (Data Source Name) is a connection string that specifies how to connect to a Geode database server. It encodes the transport protocol, server address, authentication credentials, graph target, and connection options in a single URL-like string.</p>
<h3 id="dsn-format" class="position-relative d-flex align-items-center group">
<span>DSN Format</span>
<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="dsn-format"
aria-haspopup="dialog"
aria-label="Share link: DSN Format">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"><scheme>://[<username>:<password>@]<host>[:<port>][/<graph>][?<parameters>]
</span></span></code></pre></div>
<h4 id="alternative-formats" class="position-relative d-flex align-items-center group">
<span>Alternative Formats</span>
<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="alternative-formats"
aria-haspopup="dialog"
aria-label="Share link: Alternative Formats">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>For convenience, these alternative formats are also supported:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"># Scheme-less (defaults to quic://)
</span></span><span class="line"><span class="cl"><host>:<port>[/<graph>][?<parameters>]
</span></span><span class="line"><span class="cl"><host>[/<graph>][?<parameters>]
</span></span></code></pre></div>
<h3 id="supported-schemes" class="position-relative d-flex align-items-center group">
<span>Supported Schemes</span>
<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="supported-schemes"
aria-haspopup="dialog"
aria-label="Share link: Supported Schemes">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><table>
<thead>
<tr>
<th>Scheme</th>
<th>Transport</th>
<th>Default Port</th>
<th>TLS</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>quic://</code></td>
<td>QUIC</td>
<td>3141</td>
<td>Required</td>
<td>Recommended. High-performance UDP-based transport with built-in TLS 1.3</td>
</tr>
<tr>
<td><code>grpc://</code></td>
<td>gRPC</td>
<td>50051</td>
<td>Optional</td>
<td>Standard gRPC over HTTP/2</td>
</tr>
<tr>
<td>(none)</td>
<td>QUIC</td>
<td>3141</td>
<td>Required</td>
<td>Scheme-less defaults to QUIC transport</td>
</tr>
</tbody>
</table>
<h3 id="host-specification" class="position-relative d-flex align-items-center group">
<span>Host Specification</span>
<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="host-specification"
aria-haspopup="dialog"
aria-label="Share link: Host Specification">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="ipv4-addresses" class="position-relative d-flex align-items-center group">
<span>IPv4 Addresses</span>
<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="ipv4-addresses"
aria-haspopup="dialog"
aria-label="Share link: IPv4 Addresses">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://192.168.1.100:3141
</span></span><span class="line"><span class="cl">quic://127.0.0.1:3141
</span></span></code></pre></div>
<h4 id="ipv6-addresses" class="position-relative d-flex align-items-center group">
<span>IPv6 Addresses</span>
<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="ipv6-addresses"
aria-haspopup="dialog"
aria-label="Share link: IPv6 Addresses">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>IPv6 addresses MUST be enclosed in square brackets:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://[::1]:3141
</span></span><span class="line"><span class="cl">grpc://[2001:db8::1]:50051
</span></span><span class="line"><span class="cl">quic://[fe80::1%eth0]:3141
</span></span></code></pre></div>
<h4 id="hostnames" class="position-relative d-flex align-items-center group">
<span>Hostnames</span>
<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="hostnames"
aria-haspopup="dialog"
aria-label="Share link: Hostnames">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://localhost:3141
</span></span><span class="line"><span class="cl">quic://geode.example.com:3141
</span></span></code></pre></div>
<h3 id="graph-specification" class="position-relative d-flex align-items-center group">
<span>Graph Specification</span>
<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="graph-specification"
aria-haspopup="dialog"
aria-label="Share link: Graph Specification">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><p>The graph name is an optional path component in the DSN. When present, the session is bound to the named graph at connection time, before any queries are executed.</p>
<h4 id="graph-binding-behavior" class="position-relative d-flex align-items-center group">
<span>Graph Binding Behavior</span>
<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="graph-binding-behavior"
aria-haspopup="dialog"
aria-label="Share link: Graph Binding Behavior">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Scenario</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td>Graph exists</td>
<td>Session bound; <code>USE GRAPH</code> rejected for session lifetime</td>
</tr>
<tr>
<td>Graph not exists + Admin/ReadWrite role</td>
<td>Auto-created, session bound</td>
</tr>
<tr>
<td>Graph not exists + ReadOnly/User role</td>
<td><code>HELLO</code> fails with permission error</td>
</tr>
<tr>
<td>Graph not exists + auth disabled</td>
<td>Auto-created, session bound</td>
</tr>
<tr>
<td>No graph in DSN</td>
<td>Normal behavior; <code>USE GRAPH</code> allowed</td>
</tr>
</tbody>
</table>
<h4 id="graph-isolation" class="position-relative d-flex align-items-center group">
<span>Graph Isolation</span>
<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="graph-isolation"
aria-haspopup="dialog"
aria-label="Share link: Graph Isolation">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>When a session is bound to a graph via DSN, issuing <code>USE GRAPH</code> returns SQLSTATE <code>42000</code> (syntax error or access rule violation). The bound graph cannot be changed for the lifetime of the connection. Clients MUST NOT attempt <code>USE GRAPH</code> after establishing a graph-bound session.</p>
<h4 id="examples-with-graph-path" class="position-relative d-flex align-items-center group">
<span>Examples with Graph Path</span>
<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="examples-with-graph-path"
aria-haspopup="dialog"
aria-label="Share link: Examples with Graph Path">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"># Bind to graph "social" on connect
</span></span><span class="line"><span class="cl">quic://localhost:3141/social
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"># Bind to graph with authentication
</span></span><span class="line"><span class="cl">quic://admin:[email protected]:3141/social
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"># Bind to graph with parameters
</span></span><span class="line"><span class="cl">quic://localhost:3141/analytics?page_size=500
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"># Bind to graph via gRPC
</span></span><span class="line"><span class="cl">grpc://localhost:50051/my-graph
</span></span></code></pre></div>
<h3 id="authentication" class="position-relative d-flex align-items-center group">
<span>Authentication</span>
<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="authentication"
aria-haspopup="dialog"
aria-label="Share link: Authentication">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="url-embedded-credentials" class="position-relative d-flex align-items-center group">
<span>URL-Embedded Credentials</span>
<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="url-embedded-credentials"
aria-haspopup="dialog"
aria-label="Share link: URL-Embedded Credentials">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>Credentials can be embedded in the URL using standard HTTP basic auth format:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://username:password@localhost:3141
</span></span></code></pre></div><p>Special characters in credentials MUST be percent-encoded:</p>
<ul>
<li><code>@</code> → <code>%40</code></li>
<li><code>:</code> → <code>%3A</code></li>
<li><code>/</code> → <code>%2F</code></li>
<li><code>%</code> → <code>%25</code></li>
<li>space → <code>%20</code> or <code>+</code></li>
</ul>
<p>Example with special characters:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://user%40domain:p%40ss%3Dword@localhost:3141
</span></span></code></pre></div>
<h4 id="query-parameter-credentials" class="position-relative d-flex align-items-center group">
<span>Query Parameter Credentials</span>
<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-parameter-credentials"
aria-haspopup="dialog"
aria-label="Share link: Query Parameter Credentials">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>Credentials can also be specified via query parameters:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://localhost:3141?username=admin&password=secret
</span></span></code></pre></div><p><strong>Aliases</strong>:</p>
<ul>
<li><code>username</code>, <code>user</code> → authentication username</li>
<li><code>password</code>, <code>pass</code> → authentication password</li>
</ul>
<h3 id="query-parameters" class="position-relative d-flex align-items-center group">
<span>Query Parameters</span>
<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-parameters"
aria-haspopup="dialog"
aria-label="Share link: Query Parameters">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="standard-parameters" class="position-relative d-flex align-items-center group">
<span>Standard Parameters</span>
<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="standard-parameters"
aria-haspopup="dialog"
aria-label="Share link: Standard Parameters">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>page_size</code></td>
<td>integer</td>
<td>1000</td>
<td>Results page size (1-100,000)</td>
</tr>
<tr>
<td><code>hello_name</code></td>
<td>string</td>
<td>varies</td>
<td>Client name sent in HELLO handshake</td>
</tr>
<tr>
<td><code>hello_ver</code></td>
<td>string</td>
<td>varies</td>
<td>Client version sent in HELLO handshake</td>
</tr>
<tr>
<td><code>conformance</code></td>
<td>string</td>
<td><code>min</code></td>
<td>GQL conformance level (<code>min</code>, <code>full</code>)</td>
</tr>
<tr>
<td><code>graph</code></td>
<td>string</td>
<td>-</td>
<td>Reserved alternate graph parameter. The path format is primary.</td>
</tr>
</tbody>
</table>
<h4 id="authentication-parameters" class="position-relative d-flex align-items-center group">
<span>Authentication Parameters</span>
<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="authentication-parameters"
aria-haspopup="dialog"
aria-label="Share link: Authentication Parameters">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Parameter</th>
<th>Aliases</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>username</code></td>
<td><code>user</code></td>
<td>string</td>
<td>Authentication username</td>
</tr>
<tr>
<td><code>password</code></td>
<td><code>pass</code></td>
<td>string</td>
<td>Authentication password</td>
</tr>
</tbody>
</table>
<h4 id="tls-parameters" class="position-relative d-flex align-items-center group">
<span>TLS Parameters</span>
<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="tls-parameters"
aria-haspopup="dialog"
aria-label="Share link: TLS Parameters">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Parameter</th>
<th>Aliases</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>tls</code></td>
<td>-</td>
<td>boolean</td>
<td>true</td>
<td>Enable/disable TLS (gRPC only, QUIC always uses TLS)</td>
</tr>
<tr>
<td><code>insecure_tls_skip_verify</code></td>
<td>-</td>
<td>boolean</td>
<td>false</td>
<td>Skip TLS certificate verification (testing only)</td>
</tr>
<tr>
<td><code>ca</code></td>
<td><code>ca_cert</code></td>
<td>string</td>
<td>-</td>
<td>Path to CA certificate file</td>
</tr>
<tr>
<td><code>cert</code></td>
<td><code>client_cert</code></td>
<td>string</td>
<td>-</td>
<td>Path to client certificate file (for mTLS)</td>
</tr>
<tr>
<td><code>key</code></td>
<td><code>client_key</code></td>
<td>string</td>
<td>-</td>
<td>Path to client private key file (for mTLS)</td>
</tr>
<tr>
<td><code>server_name</code></td>
<td>-</td>
<td>string</td>
<td>-</td>
<td>SNI server name for TLS</td>
</tr>
</tbody>
</table>
<h4 id="timeout-parameters" class="position-relative d-flex align-items-center group">
<span>Timeout Parameters</span>
<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-parameters"
aria-haspopup="dialog"
aria-label="Share link: Timeout Parameters">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><table>
<thead>
<tr>
<th>Parameter</th>
<th>Aliases</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>connect_timeout</code></td>
<td><code>timeout</code></td>
<td>integer</td>
<td>30</td>
<td>Connection timeout in seconds</td>
</tr>
<tr>
<td><code>timeout_ms</code></td>
<td>-</td>
<td>integer</td>
<td>30000</td>
<td>Connection timeout in milliseconds</td>
</tr>
</tbody>
</table>
<p>When both <code>connect_timeout</code> and <code>timeout_ms</code> are specified, <code>timeout_ms</code> takes precedence.</p>
<h4 id="boolean-parameter-values" class="position-relative d-flex align-items-center group">
<span>Boolean Parameter Values</span>
<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="boolean-parameter-values"
aria-haspopup="dialog"
aria-label="Share link: Boolean Parameter Values">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>Boolean parameters accept:</p>
<ul>
<li><strong>true</strong>: <code>true</code>, <code>1</code>, <code>yes</code>, <code>on</code></li>
<li><strong>false</strong>: <code>false</code>, <code>0</code>, <code>no</code>, <code>off</code></li>
</ul>
<h3 id="examples" class="position-relative d-flex align-items-center group">
<span>Examples</span>
<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="examples"
aria-haspopup="dialog"
aria-label="Share link: Examples">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="basic-connection" class="position-relative d-flex align-items-center group">
<span>Basic Connection</span>
<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="basic-connection"
aria-haspopup="dialog"
aria-label="Share link: Basic Connection">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://localhost:3141
</span></span><span class="line"><span class="cl">grpc://localhost:50051
</span></span><span class="line"><span class="cl">localhost:3141
</span></span></code></pre></div>
<h4 id="with-authentication" class="position-relative d-flex align-items-center group">
<span>With Authentication</span>
<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="with-authentication"
aria-haspopup="dialog"
aria-label="Share link: With Authentication">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://admin:secret@localhost:3141
</span></span><span class="line"><span class="cl">quic://localhost:3141?username=admin&password=secret
</span></span></code></pre></div>
<h4 id="with-options" class="position-relative d-flex align-items-center group">
<span>With Options</span>
<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="with-options"
aria-haspopup="dialog"
aria-label="Share link: With Options">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://localhost:3141?page_size=500&hello_name=my-app
</span></span><span class="line"><span class="cl">grpc://localhost:50051?tls=0&insecure_tls_skip_verify=true
</span></span></code></pre></div>
<h4 id="with-graph-binding" class="position-relative d-flex align-items-center group">
<span>With Graph Binding</span>
<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="with-graph-binding"
aria-haspopup="dialog"
aria-label="Share link: With Graph Binding">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">quic://localhost:3141/social
</span></span><span class="line"><span class="cl">quic://admin:[email protected]:3141/analytics?page_size=500
</span></span><span class="line"><span class="cl">grpc://localhost:50051/my-graph?ca=/path/to/ca.crt&cert=/path/to/client.crt&key=/path/to/client.key
</span></span><span class="line"><span class="cl">quic://admin:secret@[2001:db8::1]:3141/social
</span></span></code></pre></div>
<h3 id="protocol-changes" class="position-relative d-flex align-items-center group">
<span>Protocol Changes</span>
<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="protocol-changes"
aria-haspopup="dialog"
aria-label="Share link: Protocol Changes">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><p>This section documents the protocol-level fields added to support graph-bound sessions.</p>
<h4 id="hellorequest-field-7" class="position-relative d-flex align-items-center group">
<span>HelloRequest (field 7)</span>
<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="hellorequest-field-7"
aria-haspopup="dialog"
aria-label="Share link: HelloRequest (field 7)">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">field 7: graph optional string
</span></span></code></pre></div><p>When the DSN includes a graph path component, the client MUST populate <code>HelloRequest.graph</code> with the graph name. The server processes this field during the HELLO handshake before the session is fully established.</p>
<h4 id="helloresponse-field-6" class="position-relative d-flex align-items-center group">
<span>HelloResponse (field 6)</span>
<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="helloresponse-field-6"
aria-haspopup="dialog"
aria-label="Share link: HelloResponse (field 6)">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">field 6: graph optional string
</span></span></code></pre></div><p>The server echoes the bound graph name in <code>HelloResponse.graph</code> on success. If graph binding fails, the server returns a HELLO error response instead.</p>
<h4 id="auto-create-semantics" class="position-relative d-flex align-items-center group">
<span>Auto-Create Semantics</span>
<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="auto-create-semantics"
aria-haspopup="dialog"
aria-label="Share link: Auto-Create Semantics">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p>When <code>HelloRequest.graph</code> names a graph that does not exist, the server applies the following rules:</p>
<ol>
<li>If the authenticated user has <code>Admin</code> or <code>ReadWrite</code> role, the server creates the graph and binds the session to it.</li>
<li>If the authenticated user has <code>ReadOnly</code> or <code>User</code> role, the HELLO fails with a permission error.</li>
<li>If authentication is disabled, the server creates the graph and binds the session to it.</li>
</ol>
<h3 id="environment-variables" class="position-relative d-flex align-items-center group">
<span>Environment Variables</span>
<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="environment-variables"
aria-haspopup="dialog"
aria-label="Share link: Environment Variables">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><p>Implementations MAY support the following environment variables as fallback defaults:</p>
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GEODE_HOST</code></td>
<td>Default host if DSN is empty</td>
</tr>
<tr>
<td><code>GEODE_PORT</code></td>
<td>Default port if not specified</td>
</tr>
<tr>
<td><code>GEODE_TLS_CA</code></td>
<td>Default CA certificate path</td>
</tr>
<tr>
<td><code>GEODE_USERNAME</code></td>
<td>Default username</td>
</tr>
<tr>
<td><code>GEODE_PASSWORD</code></td>
<td>Default password</td>
</tr>
<tr>
<td><code>GEODE_TRANSPORT</code></td>
<td>Default transport (<code>quic</code> or <code>grpc</code>)</td>
</tr>
<tr>
<td><code>GEODE_GRAPH</code></td>
<td>Default graph name if not specified in DSN</td>
</tr>
</tbody>
</table>
<h3 id="error-handling" class="position-relative d-flex align-items-center group">
<span>Error Handling</span>
<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"
aria-haspopup="dialog"
aria-label="Share link: Error Handling">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><p>Implementations MUST return an error for:</p>
<ul>
<li>unsupported schemes such as <code>http://</code>, <code>https://</code>, or <code>tcp://</code></li>
<li>missing host when a scheme is present</li>
<li>invalid port numbers outside <code>1-65535</code></li>
<li>invalid IPv6 address syntax</li>
</ul>
<h3 id="client-implementation-reference" class="position-relative d-flex align-items-center group">
<span>Client Implementation Reference</span>
<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-implementation-reference"
aria-haspopup="dialog"
aria-label="Share link: Client Implementation Reference">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><table>
<thead>
<tr>
<th>Client</th>
<th>File</th>
<th>Function</th>
<th>Graph Support</th>
</tr>
</thead>
<tbody>
<tr>
<td>Go</td>
<td><code>config.go</code></td>
<td><code>ParseDSN()</code></td>
<td>path component → <code>Config.Graph</code></td>
</tr>
<tr>
<td>Rust</td>
<td><code>src/dsn.rs</code></td>
<td><code>Dsn::parse()</code></td>
<td>path component → <code>Dsn.graph</code></td>
</tr>
<tr>
<td>Python</td>
<td><code>geode_client/transport.py</code></td>
<td><code>parse_dsn()</code></td>
<td>path component → <code>DsnConfig.graph</code></td>
</tr>
<tr>
<td>Zig</td>
<td><code>src/config.zig</code></td>
<td><code>parseDSN()</code>, <code>parseDSNStrict()</code></td>
<td>path component → <code>Config.graph</code></td>
</tr>
<tr>
<td>Node.js</td>
<td><code>src/config.ts</code></td>
<td><code>parseDSN()</code></td>
<td>path component → <code>DsnConfig.graph</code></td>
</tr>
</tbody>
</table>
<h3 id="version-history" class="position-relative d-flex align-items-center group">
<span>Version History</span>
<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="version-history"
aria-haspopup="dialog"
aria-label="Share link: Version History">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><table>
<thead>
<tr>
<th>Version</th>
<th>Date</th>
<th>Changes</th>
</tr>
</thead>
<tbody>
<tr>
<td>1.0.0</td>
<td>2026-02-05</td>
<td>Initial specification</td>
</tr>
<tr>
<td>1.1.0</td>
<td>2026-03-25</td>
<td>Add graph path support, graph-bound sessions, and auto-create semantics</td>
</tr>
</tbody>
</table>
DSN (Data Source Name) Specification
Official DSN format for connecting to Geode over QUIC or gRPC, including authentication, graph binding, and TLS options