页面 中等
Wiki — Docs Page (dev-docs layout + code)
A polished developer-docs page in the Stripe and Tailwind docs vein, built as a self-contained three-column shell for a fictional Aurora DB knowledge base. A collapsible doc-tree sidebar sits left, the readable serif article column runs down the center with breadcrumbs, callouts, tables, and syntax-highlighted-looking code blocks, and a scrollspy table of contents tracks the right rail. Code blocks carry a copy button and a curl/JavaScript/Python tab switcher, and a header light or dark toggle persists across reloads.
在 Lab 開啟
MCP
html css vanilla-js
目標: JS HTML
程式碼
:root {
--bg: #ffffff;
--bg-2: #f7f8fa;
--panel: #ffffff;
--ink: #1a1a1f;
--ink-2: #3a3a42;
--muted: #6b7280;
--line: rgba(20, 20, 30, 0.1);
--line-2: rgba(20, 20, 30, 0.18);
--link: #2563eb;
--link-hover: #1d4ed8;
--accent: #2563eb;
--note: #2563eb;
--tip: #16a34a;
--warn: #d97706;
--danger: #dc2626;
--code-bg: #f4f4f6;
--kbd-bg: #eceef2;
--r-sm: 6px;
--r-md: 10px;
--r-lg: 14px;
--sb-w: 264px;
--toc-w: 224px;
--top-h: 56px;
--shadow-sm: 0 1px 2px rgba(20, 20, 30, 0.05);
--shadow-md: 0 8px 28px rgba(20, 20, 30, 0.1);
--sans: "Inter", system-ui, -apple-system, sans-serif;
--serif: "Source Serif 4", Georgia, serif;
--mono: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace;
}
html[data-theme="dark"] {
--bg: #0e1014;
--bg-2: #15181e;
--panel: #14171d;
--ink: #e9eaee;
--ink-2: #c1c4cc;
--muted: #8b909c;
--line: rgba(255, 255, 255, 0.09);
--line-2: rgba(255, 255, 255, 0.16);
--link: #6ea8fe;
--link-hover: #93bbff;
--accent: #6ea8fe;
--note: #6ea8fe;
--tip: #4ade80;
--warn: #fbbf24;
--danger: #f87171;
--code-bg: #1a1e26;
--kbd-bg: #232833;
--shadow-md: 0 8px 28px rgba(0, 0, 0, 0.5);
}
* {
box-sizing: border-box;
}
html {
scroll-behavior: smooth;
scroll-padding-top: calc(var(--top-h) + 16px);
}
body {
margin: 0;
font-family: var(--sans);
background: var(--bg);
color: var(--ink);
-webkit-font-smoothing: antialiased;
text-rendering: optimizeLegibility;
line-height: 1.5;
}
a {
color: var(--link);
text-decoration: none;
}
a:hover {
color: var(--link-hover);
}
:focus-visible {
outline: 2px solid var(--accent);
outline-offset: 2px;
border-radius: 3px;
}
.skip-link {
position: fixed;
top: -60px;
left: 12px;
z-index: 100;
background: var(--accent);
color: #fff;
padding: 8px 14px;
border-radius: var(--r-sm);
font-weight: 600;
font-size: 13px;
transition: top 0.15s;
}
.skip-link:focus {
top: 10px;
color: #fff;
}
/* ---------- topbar ---------- */
.topbar {
position: sticky;
top: 0;
z-index: 40;
height: var(--top-h);
display: flex;
align-items: center;
gap: 12px;
padding: 0 16px;
background: color-mix(in srgb, var(--bg) 88%, transparent);
backdrop-filter: saturate(1.4) blur(10px);
border-bottom: 1px solid var(--line);
}
.topbar-left,
.topbar-right {
display: flex;
align-items: center;
gap: 10px;
}
.topbar-mid {
flex: 1;
display: flex;
justify-content: center;
min-width: 0;
}
.icon-btn {
display: inline-flex;
align-items: center;
justify-content: center;
width: 36px;
height: 36px;
border: 1px solid transparent;
border-radius: var(--r-sm);
background: transparent;
color: var(--ink-2);
cursor: pointer;
transition: background 0.12s, border-color 0.12s, color 0.12s;
}
.icon-btn:hover {
background: var(--bg-2);
border-color: var(--line);
color: var(--ink);
}
.nav-toggle {
display: none;
}
.brand {
display: inline-flex;
align-items: baseline;
gap: 7px;
font-weight: 800;
font-size: 16px;
color: var(--ink);
letter-spacing: -0.01em;
}
.brand:hover {
color: var(--ink);
}
.brand-mark {
color: var(--accent);
font-size: 18px;
}
.brand-db {
color: var(--accent);
}
.brand-tag {
font-family: var(--mono);
font-size: 11px;
font-weight: 500;
color: var(--muted);
align-self: center;
padding: 2px 6px;
border: 1px solid var(--line);
border-radius: 5px;
}
.ver-pill {
font-family: var(--mono);
font-size: 11px;
font-weight: 600;
color: var(--accent);
background: color-mix(in srgb, var(--accent) 12%, transparent);
padding: 2px 7px;
border-radius: 20px;
}
.search {
display: flex;
align-items: center;
gap: 8px;
width: min(420px, 100%);
padding: 0 10px;
height: 36px;
background: var(--bg-2);
border: 1px solid var(--line);
border-radius: 9px;
color: var(--muted);
transition: border-color 0.12s, box-shadow 0.12s;
}
.search:focus-within {
border-color: var(--accent);
box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 18%, transparent);
}
.search input {
flex: 1;
border: 0;
background: transparent;
font: inherit;
font-size: 14px;
color: var(--ink);
min-width: 0;
}
.search input:focus {
outline: none;
}
.search input::placeholder {
color: var(--muted);
}
kbd,
.search kbd {
font-family: var(--mono);
font-size: 11px;
color: var(--ink-2);
background: var(--kbd-bg);
border: 1px solid var(--line-2);
border-bottom-width: 2px;
border-radius: 5px;
padding: 1px 6px;
line-height: 1.4;
}
.ghost-link {
font-size: 13.5px;
font-weight: 500;
color: var(--ink-2);
padding: 6px 8px;
border-radius: var(--r-sm);
}
.ghost-link:hover {
color: var(--ink);
background: var(--bg-2);
}
.ghost-link.gh {
padding: 6px;
}
.theme-toggle .i-moon {
display: none;
}
html[data-theme="dark"] .theme-toggle .i-sun {
display: none;
}
html[data-theme="dark"] .theme-toggle .i-moon {
display: inline;
}
/* ---------- layout ---------- */
.layout {
display: grid;
grid-template-columns: var(--sb-w) minmax(0, 1fr) var(--toc-w);
max-width: 1400px;
margin: 0 auto;
align-items: start;
}
/* ---------- sidebar ---------- */
.sidebar {
position: sticky;
top: var(--top-h);
height: calc(100vh - var(--top-h));
overflow-y: auto;
border-right: 1px solid var(--line);
background: var(--bg);
}
.sidebar-inner {
padding: 22px 16px 40px;
}
.nav-group-label {
margin: 18px 0 6px;
padding: 0 8px;
font-size: 11px;
font-weight: 700;
letter-spacing: 0.07em;
text-transform: uppercase;
color: var(--muted);
}
.nav-group-label:first-child {
margin-top: 0;
}
.nav-list {
list-style: none;
margin: 0;
padding: 0;
}
.nav-link {
display: block;
padding: 6px 10px;
font-size: 13.5px;
font-weight: 500;
color: var(--ink-2);
border-radius: var(--r-sm);
transition: background 0.1s, color 0.1s;
}
.nav-link:hover {
background: var(--bg-2);
color: var(--ink);
}
.nav-link.active {
color: var(--accent);
background: color-mix(in srgb, var(--accent) 10%, transparent);
font-weight: 600;
}
.nav-tree {
margin-top: 2px;
}
.nav-branch {
display: flex;
align-items: center;
gap: 6px;
width: 100%;
padding: 6px 8px;
background: transparent;
border: 0;
font: inherit;
font-size: 13.5px;
font-weight: 600;
color: var(--ink);
cursor: pointer;
border-radius: var(--r-sm);
text-align: left;
}
.nav-branch:hover {
background: var(--bg-2);
}
.nav-branch .chev {
flex: none;
color: var(--muted);
transition: transform 0.16s ease;
}
.nav-tree[data-open="true"] .nav-branch .chev {
transform: rotate(90deg);
}
.nav-children {
overflow: hidden;
margin-left: 9px;
padding-left: 9px;
border-left: 1px solid var(--line);
display: grid;
grid-template-rows: 1fr;
transition: grid-template-rows 0.2s ease, opacity 0.18s ease;
}
.nav-tree[data-open="false"] .nav-children {
grid-template-rows: 0fr;
opacity: 0;
margin-top: 0;
}
.nav-children > li {
min-height: 0;
}
/* ---------- content ---------- */
.content {
min-width: 0;
padding: 30px clamp(20px, 4vw, 56px) 80px;
}
.content:focus {
outline: none;
}
.breadcrumbs {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 6px;
font-size: 12.5px;
color: var(--muted);
margin-bottom: 14px;
}
.breadcrumbs a {
color: var(--muted);
}
.breadcrumbs a:hover {
color: var(--link);
}
.breadcrumbs .sep {
color: var(--line-2);
}
.breadcrumbs [aria-current] {
color: var(--ink-2);
font-weight: 600;
}
.article {
max-width: 760px;
}
.eyebrow {
font-size: 12px;
font-weight: 700;
letter-spacing: 0.06em;
text-transform: uppercase;
color: var(--accent);
margin-bottom: 8px;
}
.article h1 {
font-family: var(--sans);
font-size: clamp(28px, 4vw, 38px);
font-weight: 800;
letter-spacing: -0.02em;
line-height: 1.15;
margin: 0 0 14px;
}
.lede {
font-family: var(--serif);
font-size: 18px;
line-height: 1.6;
color: var(--ink-2);
margin: 0 0 18px;
}
.article-meta {
display: flex;
flex-wrap: wrap;
gap: 8px;
margin-bottom: 8px;
}
.meta-chip {
font-size: 11.5px;
font-weight: 600;
color: var(--muted);
background: var(--bg-2);
border: 1px solid var(--line);
padding: 3px 9px;
border-radius: 20px;
}
.meta-chip.stable {
color: var(--tip);
border-color: color-mix(in srgb, var(--tip) 35%, transparent);
background: color-mix(in srgb, var(--tip) 10%, transparent);
}
.article h2 {
font-family: var(--sans);
font-size: 22px;
font-weight: 700;
letter-spacing: -0.01em;
margin: 38px 0 12px;
padding-top: 6px;
scroll-margin-top: calc(var(--top-h) + 16px);
}
.article p,
.article li {
font-family: var(--serif);
font-size: 16.5px;
line-height: 1.7;
color: var(--ink-2);
}
.article > p {
margin: 0 0 16px;
}
.article strong {
color: var(--ink);
font-weight: 600;
}
.doc-list {
margin: 0 0 16px;
padding-left: 22px;
}
.doc-list li {
margin: 5px 0;
}
code {
font-family: var(--mono);
font-size: 0.86em;
background: var(--code-bg);
border: 1px solid var(--line);
padding: 1px 5px;
border-radius: 5px;
color: var(--ink);
}
/* ---------- callouts ---------- */
.callout {
display: flex;
gap: 12px;
margin: 18px 0 22px;
padding: 14px 16px;
border: 1px solid var(--line);
border-left-width: 4px;
border-radius: var(--r-md);
background: var(--bg-2);
}
.callout-ic {
flex: none;
margin-top: 1px;
}
.callout-title {
font-family: var(--sans) !important;
font-size: 13px !important;
font-weight: 700;
margin: 0 0 3px;
letter-spacing: 0.01em;
}
.callout p {
margin: 0;
font-size: 15px !important;
line-height: 1.6 !important;
}
.callout.note {
border-left-color: var(--note);
background: color-mix(in srgb, var(--note) 7%, var(--bg));
}
.callout.note .callout-ic,
.callout.note .callout-title {
color: var(--note);
}
.callout.tip {
border-left-color: var(--tip);
background: color-mix(in srgb, var(--tip) 8%, var(--bg));
}
.callout.tip .callout-ic,
.callout.tip .callout-title {
color: var(--tip);
}
.callout.warn {
border-left-color: var(--warn);
background: color-mix(in srgb, var(--warn) 9%, var(--bg));
}
.callout.warn .callout-ic,
.callout.warn .callout-title {
color: var(--warn);
}
/* ---------- code blocks ---------- */
.codeblock {
margin: 18px 0 24px;
border: 1px solid var(--line-2);
border-radius: var(--r-md);
overflow: hidden;
background: var(--code-bg);
box-shadow: var(--shadow-sm);
}
.code-tabs {
display: flex;
align-items: center;
gap: 2px;
padding: 4px 6px;
background: color-mix(in srgb, var(--code-bg) 70%, var(--bg-2));
border-bottom: 1px solid var(--line);
}
.code-tab {
font-family: var(--mono);
font-size: 12px;
font-weight: 500;
color: var(--muted);
background: transparent;
border: 0;
padding: 5px 11px;
border-radius: var(--r-sm);
cursor: pointer;
transition: background 0.1s, color 0.1s;
}
.code-tab:hover {
color: var(--ink);
background: var(--bg);
}
.code-tab.active {
color: var(--ink);
background: var(--bg);
box-shadow: var(--shadow-sm);
}
.copy-btn {
margin-left: auto;
display: inline-flex;
align-items: center;
gap: 6px;
font-family: var(--sans);
font-size: 12px;
font-weight: 600;
color: var(--ink-2);
background: var(--bg);
border: 1px solid var(--line);
padding: 5px 10px;
border-radius: var(--r-sm);
cursor: pointer;
transition: border-color 0.12s, color 0.12s;
}
.copy-btn:hover {
border-color: var(--line-2);
color: var(--ink);
}
.copy-btn.copied {
color: var(--tip);
border-color: color-mix(in srgb, var(--tip) 40%, transparent);
}
.code {
margin: 0;
padding: 16px 18px;
overflow-x: auto;
font-family: var(--mono);
font-size: 13px;
line-height: 1.65;
color: var(--ink);
tab-size: 2;
}
.code code {
background: transparent;
border: 0;
padding: 0;
font-size: inherit;
color: inherit;
}
/* faux syntax tokens */
.c-cm {
color: var(--muted);
font-style: italic;
}
.c-st {
color: #16a34a;
}
.c-kw {
color: #7c3aed;
font-weight: 600;
}
.c-fn {
color: #2563eb;
}
.c-nm {
color: #d97706;
}
.c-fl {
color: #0891b2;
}
.c-pr {
color: #be185d;
}
html[data-theme="dark"] .c-st {
color: #7ee787;
}
html[data-theme="dark"] .c-kw {
color: #c4a7ff;
}
html[data-theme="dark"] .c-fn {
color: #79c0ff;
}
html[data-theme="dark"] .c-nm {
color: #ffa657;
}
html[data-theme="dark"] .c-fl {
color: #56d4dd;
}
html[data-theme="dark"] .c-pr {
color: #ff9bce;
}
/* ---------- table ---------- */
.doc-table {
width: 100%;
border-collapse: collapse;
margin: 8px 0 22px;
font-family: var(--sans);
font-size: 14px;
border: 1px solid var(--line);
border-radius: var(--r-md);
overflow: hidden;
}
.doc-table th,
.doc-table td {
text-align: left;
padding: 10px 14px;
border-bottom: 1px solid var(--line);
color: var(--ink-2);
}
.doc-table th {
font-weight: 700;
font-size: 12.5px;
letter-spacing: 0.02em;
text-transform: uppercase;
color: var(--muted);
background: var(--bg-2);
}
.doc-table tr:last-child td {
border-bottom: 0;
}
.doc-table tr:hover td {
background: var(--bg-2);
}
/* ---------- quote ---------- */
.doc-quote {
margin: 20px 0;
padding: 12px 18px;
border-left: 3px solid var(--accent);
background: var(--bg-2);
border-radius: 0 var(--r-md) var(--r-md) 0;
}
.doc-quote p {
font-family: var(--serif);
font-style: italic;
font-size: 16px !important;
color: var(--ink-2);
margin: 0;
}
.doc-quote cite {
font-style: normal;
font-weight: 600;
color: var(--muted);
}
/* ---------- page nav ---------- */
.page-nav {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 14px;
margin: 44px 0 32px;
}
.page-nav-link {
display: flex;
flex-direction: column;
gap: 3px;
padding: 14px 16px;
border: 1px solid var(--line);
border-radius: var(--r-md);
transition: border-color 0.12s, box-shadow 0.12s, transform 0.12s;
}
.page-nav-link:hover {
border-color: var(--accent);
box-shadow: var(--shadow-sm);
transform: translateY(-1px);
}
.page-nav-link.next {
text-align: right;
}
.pn-dir {
font-size: 12px;
color: var(--muted);
font-weight: 500;
}
.pn-title {
font-size: 15px;
font-weight: 600;
color: var(--ink);
}
.article-foot {
border-top: 1px solid var(--line);
padding-top: 18px;
}
.edit-link {
font-size: 14px;
font-weight: 600;
}
.foot-note {
margin: 14px 0 0;
font-family: var(--sans) !important;
font-size: 14px !important;
color: var(--muted);
display: flex;
align-items: center;
gap: 8px;
flex-wrap: wrap;
}
.vote {
font: inherit;
font-size: 13px;
font-weight: 600;
color: var(--ink-2);
background: var(--bg);
border: 1px solid var(--line);
padding: 5px 12px;
border-radius: 20px;
cursor: pointer;
transition: border-color 0.12s, color 0.12s, background 0.12s;
}
.vote:hover {
border-color: var(--line-2);
color: var(--ink);
}
.vote.picked {
color: var(--accent);
border-color: var(--accent);
background: color-mix(in srgb, var(--accent) 10%, transparent);
}
/* ---------- toc ---------- */
.toc {
position: sticky;
top: var(--top-h);
height: calc(100vh - var(--top-h));
overflow-y: auto;
padding: 30px 18px 40px;
font-family: var(--sans);
}
.toc-label {
font-size: 11px;
font-weight: 700;
letter-spacing: 0.07em;
text-transform: uppercase;
color: var(--muted);
margin: 0 0 10px;
}
.toc-list {
list-style: none;
margin: 0 0 22px;
padding: 0;
border-left: 1px solid var(--line);
}
.toc-list a {
display: block;
padding: 5px 0 5px 14px;
margin-left: -1px;
border-left: 2px solid transparent;
font-size: 13px;
color: var(--muted);
transition: color 0.1s, border-color 0.1s;
}
.toc-list a:hover {
color: var(--ink);
}
.toc-list a.active {
color: var(--accent);
font-weight: 600;
border-left-color: var(--accent);
}
.toc-card {
padding: 14px;
border: 1px solid var(--line);
border-radius: var(--r-md);
background: var(--bg-2);
}
.toc-card-title {
font-size: 13px;
font-weight: 700;
color: var(--ink);
margin: 0 0 5px;
}
.toc-card p {
font-size: 13px;
color: var(--muted);
margin: 0;
line-height: 1.55;
}
/* ---------- scrim ---------- */
.scrim {
position: fixed;
inset: var(--top-h) 0 0 0;
background: rgba(10, 12, 16, 0.42);
z-index: 30;
opacity: 0;
animation: scrim-in 0.18s ease forwards;
}
@keyframes scrim-in {
to {
opacity: 1;
}
}
/* ---------- toast ---------- */
.toast {
position: fixed;
left: 50%;
bottom: 24px;
transform: translate(-50%, 16px);
background: var(--ink);
color: var(--bg);
font-size: 13.5px;
font-weight: 600;
padding: 10px 18px;
border-radius: 22px;
box-shadow: var(--shadow-md);
opacity: 0;
pointer-events: none;
transition: opacity 0.2s, transform 0.2s;
z-index: 80;
}
.toast.show {
opacity: 1;
transform: translate(-50%, 0);
}
/* ---------- responsive ---------- */
@media (max-width: 1080px) {
:root {
--toc-w: 0px;
}
.layout {
grid-template-columns: var(--sb-w) minmax(0, 1fr);
}
.toc {
display: none;
}
}
@media (max-width: 820px) {
.nav-toggle {
display: inline-flex;
}
.layout {
grid-template-columns: minmax(0, 1fr);
}
.sidebar {
position: fixed;
top: var(--top-h);
left: 0;
z-index: 35;
width: var(--sb-w);
max-width: 86vw;
height: calc(100vh - var(--top-h));
transform: translateX(-102%);
transition: transform 0.22s ease;
background: var(--panel);
box-shadow: var(--shadow-md);
}
.sidebar.open {
transform: translateX(0);
}
.topbar-mid {
display: none;
}
.ghost-link:not(.gh) {
display: none;
}
}
@media (max-width: 520px) {
.ver-pill,
.brand-tag {
display: none;
}
.content {
padding: 22px 18px 64px;
}
.article h1 {
font-size: 26px;
}
.lede {
font-size: 16.5px;
}
.page-nav {
grid-template-columns: 1fr;
}
.code {
font-size: 12px;
}
}
@media (prefers-reduced-motion: reduce) {
* {
scroll-behavior: auto;
transition: none !important;
animation: none !important;
}
}(function () {
"use strict";
/* ---------- toast helper ---------- */
var toastEl = document.getElementById("toast");
var toastTimer;
function toast(msg) {
if (!toastEl) return;
toastEl.textContent = msg;
toastEl.classList.add("show");
clearTimeout(toastTimer);
toastTimer = setTimeout(function () {
toastEl.classList.remove("show");
}, 1800);
}
/* ---------- theme toggle (persists) ---------- */
var root = document.documentElement;
var themeBtn = document.getElementById("themeToggle");
var STORE_KEY = "auroradb-docs-theme";
function applyTheme(theme) {
root.setAttribute("data-theme", theme);
if (themeBtn) themeBtn.setAttribute("aria-pressed", String(theme === "dark"));
}
try {
var saved = localStorage.getItem(STORE_KEY);
if (saved === "dark" || saved === "light") {
applyTheme(saved);
} else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) {
applyTheme("dark");
}
} catch (e) {
/* ignore */
}
if (themeBtn) {
themeBtn.addEventListener("click", function () {
var next = root.getAttribute("data-theme") === "dark" ? "light" : "dark";
applyTheme(next);
try {
localStorage.setItem(STORE_KEY, next);
} catch (e) {}
toast(next === "dark" ? "Dark theme on" : "Light theme on");
});
}
/* ---------- language tabs ---------- */
document.querySelectorAll("[data-lang-block]").forEach(function (block) {
var tabs = block.querySelectorAll(".code-tab");
var panes = block.querySelectorAll(".code");
function select(lang) {
tabs.forEach(function (t) {
var on = t.getAttribute("data-lang") === lang;
t.classList.toggle("active", on);
t.setAttribute("aria-selected", String(on));
});
panes.forEach(function (p) {
p.hidden = p.getAttribute("data-lang") !== lang;
});
}
tabs.forEach(function (tab) {
tab.addEventListener("click", function () {
select(tab.getAttribute("data-lang"));
});
});
});
/* ---------- copy buttons ---------- */
document.querySelectorAll(".copy-btn").forEach(function (btn) {
btn.addEventListener("click", function () {
var block = btn.closest("[data-lang-block]");
if (!block) return;
var active = block.querySelector(".code:not([hidden])");
if (!active) return;
var text = active.innerText.replace(/\n+$/, "");
var done = function () {
btn.classList.add("copied");
var label = btn.querySelector(".copy-label");
var orig = label ? label.textContent : "";
if (label) label.textContent = "Copied!";
toast("Copied to clipboard");
setTimeout(function () {
btn.classList.remove("copied");
if (label) label.textContent = orig;
}, 1500);
};
if (navigator.clipboard && navigator.clipboard.writeText) {
navigator.clipboard.writeText(text).then(done, fallback);
} else {
fallback();
}
function fallback() {
var ta = document.createElement("textarea");
ta.value = text;
ta.style.position = "fixed";
ta.style.opacity = "0";
document.body.appendChild(ta);
ta.select();
try {
document.execCommand("copy");
done();
} catch (e) {
toast("Copy failed");
}
document.body.removeChild(ta);
}
});
});
/* ---------- nav tree collapse ---------- */
document.querySelectorAll(".nav-tree .nav-branch").forEach(function (branch) {
branch.addEventListener("click", function () {
var tree = branch.closest(".nav-tree");
var open = tree.getAttribute("data-open") === "true";
tree.setAttribute("data-open", String(!open));
branch.setAttribute("aria-expanded", String(!open));
});
});
/* ---------- mobile sidebar drawer ---------- */
var sidebar = document.getElementById("sidebar");
var navToggle = document.getElementById("navToggle");
var scrim = document.getElementById("scrim");
function openNav() {
sidebar.classList.add("open");
navToggle.setAttribute("aria-expanded", "true");
if (scrim) scrim.hidden = false;
}
function closeNav() {
sidebar.classList.remove("open");
navToggle.setAttribute("aria-expanded", "false");
if (scrim) scrim.hidden = true;
}
if (navToggle) {
navToggle.addEventListener("click", function () {
sidebar.classList.contains("open") ? closeNav() : openNav();
});
}
if (scrim) scrim.addEventListener("click", closeNav);
document.addEventListener("keydown", function (e) {
if (e.key === "Escape" && sidebar.classList.contains("open")) closeNav();
});
// close drawer when a nav link is chosen on mobile
sidebar &&
sidebar.querySelectorAll(".nav-link").forEach(function (a) {
a.addEventListener("click", function () {
if (window.matchMedia("(max-width: 820px)").matches) closeNav();
});
});
/* ---------- search shortcut "/" ---------- */
var searchInput = document.querySelector(".search input");
document.addEventListener("keydown", function (e) {
if (e.key === "/" && document.activeElement !== searchInput) {
var tag = (document.activeElement && document.activeElement.tagName) || "";
if (tag !== "INPUT" && tag !== "TEXTAREA") {
e.preventDefault();
searchInput && searchInput.focus();
}
}
});
/* ---------- vote buttons ---------- */
document.querySelectorAll(".vote").forEach(function (btn) {
btn.addEventListener("click", function () {
document.querySelectorAll(".vote").forEach(function (b) {
b.classList.remove("picked");
});
btn.classList.add("picked");
toast(btn.getAttribute("data-vote") === "up" ? "Thanks for the feedback!" : "Sorry to hear that — we'll improve it");
});
});
/* ---------- TOC scrollspy ---------- */
var tocLinks = Array.prototype.slice.call(document.querySelectorAll("[data-toc]"));
var sections = tocLinks
.map(function (l) {
return document.getElementById(l.getAttribute("href").slice(1));
})
.filter(Boolean);
function setActive(id) {
tocLinks.forEach(function (l) {
l.classList.toggle("active", l.getAttribute("href") === "#" + id);
});
}
if ("IntersectionObserver" in window && sections.length) {
var visible = new Set();
var io = new IntersectionObserver(
function (entries) {
entries.forEach(function (en) {
if (en.isIntersecting) visible.add(en.target.id);
else visible.delete(en.target.id);
});
// pick the first section in document order that is visible
for (var i = 0; i < sections.length; i++) {
if (visible.has(sections[i].id)) {
setActive(sections[i].id);
break;
}
}
},
{ rootMargin: "-72px 0px -65% 0px", threshold: 0 }
);
sections.forEach(function (s) {
io.observe(s);
});
setActive(sections[0].id);
}
// smooth-update active state on direct TOC click
tocLinks.forEach(function (l) {
l.addEventListener("click", function () {
setActive(l.getAttribute("href").slice(1));
});
});
})();<!doctype html>
<html lang="en" data-theme="light">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Aurora DB Docs — Querying with the SDK</title>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=Source+Serif+4:opsz,[email protected],400;8..60,500;8..60,600&family=JetBrains+Mono:wght@400;500;600&display=swap"
rel="stylesheet"
/>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<a class="skip-link" href="#main">Skip to content</a>
<header class="topbar">
<div class="topbar-left">
<button
class="icon-btn nav-toggle"
id="navToggle"
aria-label="Toggle navigation"
aria-expanded="false"
aria-controls="sidebar"
>
<svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true">
<path d="M3 6h18M3 12h18M3 18h18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
</svg>
</button>
<a class="brand" href="#main" aria-label="Aurora DB documentation home">
<span class="brand-mark" aria-hidden="true">◈</span>
<span class="brand-name">Aurora<span class="brand-db">DB</span></span>
<span class="brand-tag">docs</span>
</a>
<span class="ver-pill">v4.2</span>
</div>
<div class="topbar-mid">
<label class="search" aria-label="Search documentation">
<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<circle cx="11" cy="11" r="7" fill="none" stroke="currentColor" stroke-width="2" />
<path d="m20 20-3.2-3.2" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
</svg>
<input type="search" placeholder="Search docs…" aria-label="Search docs" />
<kbd>/</kbd>
</label>
</div>
<div class="topbar-right">
<a class="ghost-link" href="#main">Guides</a>
<a class="ghost-link" href="#main">API</a>
<a class="ghost-link gh" href="#main" aria-label="GitHub repository">
<svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">
<path
fill="currentColor"
d="M12 2a10 10 0 0 0-3.16 19.49c.5.09.68-.22.68-.48v-1.7c-2.78.6-3.37-1.34-3.37-1.34-.45-1.16-1.11-1.47-1.11-1.47-.91-.62.07-.6.07-.6 1 .07 1.53 1.03 1.53 1.03.9 1.53 2.36 1.09 2.94.83.09-.65.35-1.1.63-1.35-2.22-.25-4.55-1.11-4.55-4.94 0-1.09.39-1.98 1.03-2.68-.1-.25-.45-1.27.1-2.65 0 0 .84-.27 2.75 1.02a9.5 9.5 0 0 1 5 0c1.91-1.29 2.75-1.02 2.75-1.02.55 1.38.2 2.4.1 2.65.64.7 1.03 1.59 1.03 2.68 0 3.84-2.34 4.69-4.57 4.94.36.31.68.92.68 1.85v2.74c0 .27.18.58.69.48A10 10 0 0 0 12 2Z"
/>
</svg>
</a>
<button class="icon-btn theme-toggle" id="themeToggle" aria-label="Toggle dark mode" aria-pressed="false">
<svg class="i-sun" viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">
<circle cx="12" cy="12" r="4.5" fill="none" stroke="currentColor" stroke-width="2" />
<path d="M12 2v2.5M12 19.5V22M2 12h2.5M19.5 12H22M4.6 4.6l1.8 1.8M17.6 17.6l1.8 1.8M19.4 4.6l-1.8 1.8M6.4 17.6l-1.8 1.8" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
</svg>
<svg class="i-moon" viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">
<path d="M21 12.8A8.5 8.5 0 1 1 11.2 3a6.6 6.6 0 0 0 9.8 9.8Z" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round" />
</svg>
</button>
</div>
</header>
<div class="scrim" id="scrim" hidden></div>
<div class="layout">
<!-- LEFT: doc tree -->
<nav class="sidebar" id="sidebar" aria-label="Documentation navigation">
<div class="sidebar-inner">
<p class="nav-group-label">Getting started</p>
<ul class="nav-list">
<li><a class="nav-link" href="#main">Introduction</a></li>
<li><a class="nav-link" href="#main">Quickstart</a></li>
<li><a class="nav-link" href="#main">Install the CLI</a></li>
</ul>
<div class="nav-tree" data-open="true">
<button class="nav-branch" aria-expanded="true">
<svg class="chev" viewBox="0 0 24 24" width="14" height="14" aria-hidden="true">
<path d="m9 6 6 6-6 6" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
</svg>
<span>SDK reference</span>
</button>
<ul class="nav-list nav-children">
<li><a class="nav-link" href="#main">Connections</a></li>
<li><a class="nav-link active" href="#main" aria-current="page">Querying</a></li>
<li><a class="nav-link" href="#main">Transactions</a></li>
<li><a class="nav-link" href="#main">Streaming reads</a></li>
<li><a class="nav-link" href="#main">Migrations</a></li>
</ul>
</div>
<div class="nav-tree" data-open="false">
<button class="nav-branch" aria-expanded="false">
<svg class="chev" viewBox="0 0 24 24" width="14" height="14" aria-hidden="true">
<path d="m9 6 6 6-6 6" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
</svg>
<span>Edge & replication</span>
</button>
<ul class="nav-list nav-children">
<li><a class="nav-link" href="#main">Read replicas</a></li>
<li><a class="nav-link" href="#main">Region pinning</a></li>
<li><a class="nav-link" href="#main">Conflict policy</a></li>
</ul>
</div>
<div class="nav-tree" data-open="false">
<button class="nav-branch" aria-expanded="false">
<svg class="chev" viewBox="0 0 24 24" width="14" height="14" aria-hidden="true">
<path d="m9 6 6 6-6 6" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
</svg>
<span>Security</span>
</button>
<ul class="nav-list nav-children">
<li><a class="nav-link" href="#main">API keys</a></li>
<li><a class="nav-link" href="#main">Row policies</a></li>
<li><a class="nav-link" href="#main">Audit log</a></li>
</ul>
</div>
<p class="nav-group-label">Reference</p>
<ul class="nav-list">
<li><a class="nav-link" href="#main">REST API</a></li>
<li><a class="nav-link" href="#main">Error codes</a></li>
<li><a class="nav-link" href="#main">Changelog</a></li>
</ul>
</div>
</nav>
<!-- CENTER: content -->
<main class="content" id="main" tabindex="-1">
<nav class="breadcrumbs" aria-label="Breadcrumb">
<a href="#main">Docs</a>
<span class="sep" aria-hidden="true">/</span>
<a href="#main">SDK reference</a>
<span class="sep" aria-hidden="true">/</span>
<span aria-current="page">Querying</span>
</nav>
<article class="article">
<header class="article-head">
<div class="eyebrow">SDK Reference</div>
<h1 id="querying">Querying with the SDK</h1>
<p class="lede">
Run reads against an <strong>Aurora DB</strong> cluster from the official client. This
page covers single-statement queries, parameter binding, typed result rows, and the
cursor API used by <code>Project Nimbus</code> for large exports.
</p>
<div class="article-meta">
<span class="meta-chip">Updated Jun 8, 2026</span>
<span class="meta-chip">5 min read</span>
<span class="meta-chip stable">Stable</span>
</div>
</header>
<h2 id="overview">Overview</h2>
<p>
The <code>query()</code> method sends a statement to the primary node and returns a typed
result set. Statements are parsed once and cached per connection, so repeating a query
with different parameters reuses the prepared plan. For workloads that read more than a
few thousand rows, prefer the <a href="#cursors">cursor API</a> so results stream instead
of buffering in memory.
</p>
<div class="callout note" role="note">
<div class="callout-ic" aria-hidden="true">
<svg viewBox="0 0 24 24" width="18" height="18"><circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2"/><path d="M12 11v5M12 7.5v.5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>
</div>
<div class="callout-body">
<p class="callout-title">Note</p>
<p>All queries run against the nearest healthy replica unless you set <code>{ consistency: "strong" }</code>, which routes to the primary.</p>
</div>
</div>
<h2 id="install">Install</h2>
<p>Add the client to your project. The SDK ships ESM and CJS builds and has zero runtime dependencies.</p>
<div class="codeblock" data-lang-block>
<div class="code-tabs" role="tablist" aria-label="Install command">
<button class="code-tab active" role="tab" aria-selected="true" data-lang="curl">Shell</button>
<button class="code-tab" role="tab" aria-selected="false" data-lang="js">JavaScript</button>
<button class="code-tab" role="tab" aria-selected="false" data-lang="python">Python</button>
<button class="copy-btn" type="button" aria-label="Copy code">
<svg class="i-copy" viewBox="0 0 24 24" width="15" height="15" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10" fill="none" stroke="currentColor" stroke-width="2"/></svg>
<span class="copy-label">Copy</span>
</button>
</div>
<pre class="code" data-lang="curl"><code><span class="c-cm"># install the CLI + client</span>
npm install <span class="c-st">@auroradb/client</span>
aurora login <span class="c-fl">--profile</span> prod</code></pre>
<pre class="code" data-lang="js" hidden><code>npm install <span class="c-st">@auroradb/client</span>
<span class="c-cm">// or with bun</span>
bun add <span class="c-st">@auroradb/client</span></code></pre>
<pre class="code" data-lang="python" hidden><code>pip install <span class="c-st">auroradb</span>
<span class="c-cm"># optional: async extras</span>
pip install <span class="c-st">"auroradb[async]"</span></code></pre>
</div>
<h2 id="basic-query">A basic query</h2>
<p>
Connect, then call <code>query()</code> with a parameterized statement. Positional
parameters (<code>$1</code>, <code>$2</code>) are bound server-side, so user input is
never concatenated into SQL. The example below fetches active members of the
<em>Verdant Empire</em> tenant.
</p>
<div class="codeblock" data-lang-block>
<div class="code-tabs" role="tablist" aria-label="Query example">
<button class="code-tab active" role="tab" aria-selected="true" data-lang="curl">cURL</button>
<button class="code-tab" role="tab" aria-selected="false" data-lang="js">JavaScript</button>
<button class="code-tab" role="tab" aria-selected="false" data-lang="python">Python</button>
<button class="copy-btn" type="button" aria-label="Copy code">
<svg class="i-copy" viewBox="0 0 24 24" width="15" height="15" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10" fill="none" stroke="currentColor" stroke-width="2"/></svg>
<span class="copy-label">Copy</span>
</button>
</div>
<pre class="code" data-lang="curl"><code>curl https://api.auroradb.dev/v4/query <span class="c-fl">\</span>
<span class="c-fl">-H</span> <span class="c-st">"Authorization: Bearer $AURORA_KEY"</span> <span class="c-fl">\</span>
<span class="c-fl">-H</span> <span class="c-st">"Content-Type: application/json"</span> <span class="c-fl">\</span>
<span class="c-fl">-d</span> <span class="c-st">'{"sql":"select id, name from member where tenant = $1 and active","params":["verdant"]}'</span></code></pre>
<pre class="code" data-lang="js" hidden><code><span class="c-kw">import</span> { connect } <span class="c-kw">from</span> <span class="c-st">"@auroradb/client"</span>;
<span class="c-kw">const</span> db = <span class="c-kw">await</span> <span class="c-fn">connect</span>(process.env.<span class="c-pr">AURORA_URL</span>);
<span class="c-kw">const</span> { rows } = <span class="c-kw">await</span> db.<span class="c-fn">query</span>(
<span class="c-st">"select id, name from member where tenant = $1 and active"</span>,
[<span class="c-st">"verdant"</span>],
);
<span class="c-kw">for</span> (<span class="c-kw">const</span> m <span class="c-kw">of</span> rows) console.<span class="c-fn">log</span>(m.id, m.name);</code></pre>
<pre class="code" data-lang="python" hidden><code><span class="c-kw">import</span> auroradb
db = auroradb.<span class="c-fn">connect</span>(os.environ[<span class="c-st">"AURORA_URL"</span>])
rows = db.<span class="c-fn">query</span>(
<span class="c-st">"select id, name from member where tenant = $1 and active"</span>,
[<span class="c-st">"verdant"</span>],
)
<span class="c-kw">for</span> m <span class="c-kw">in</span> rows:
<span class="c-fn">print</span>(m[<span class="c-st">"id"</span>], m[<span class="c-st">"name"</span>])</code></pre>
</div>
<div class="callout warn" role="note">
<div class="callout-ic" aria-hidden="true">
<svg viewBox="0 0 24 24" width="18" height="18"><path d="M12 3 2.5 20h19L12 3Z" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/><path d="M12 10v4M12 17v.5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>
</div>
<div class="callout-body">
<p class="callout-title">Avoid string interpolation</p>
<p>Never build SQL with template strings. Always pass values through the <code>params</code> array — the planner binds them as typed literals and rejects injection attempts.</p>
</div>
</div>
<h2 id="typed-rows">Typed rows</h2>
<p>
Each row is a plain object keyed by column name. Pass a type parameter to get full
editor autocomplete on the returned shape. Columns map to their nearest host type —
<code>timestamptz</code> becomes a <code>Date</code>, <code>jsonb</code> is parsed, and
<code>numeric</code> stays a string to preserve precision.
</p>
<table class="doc-table">
<thead>
<tr><th>Aurora type</th><th>JS type</th><th>Notes</th></tr>
</thead>
<tbody>
<tr><td><code>int8</code></td><td><code>number</code> / <code>bigint</code></td><td>bigint past 2⁵³</td></tr>
<tr><td><code>numeric</code></td><td><code>string</code></td><td>lossless decimal</td></tr>
<tr><td><code>timestamptz</code></td><td><code>Date</code></td><td>always UTC</td></tr>
<tr><td><code>jsonb</code></td><td><code>object</code></td><td>parsed eagerly</td></tr>
<tr><td><code>uuid</code></td><td><code>string</code></td><td>lowercased</td></tr>
</tbody>
</table>
<h2 id="cursors">Streaming with cursors</h2>
<p>
For large result sets, open a cursor and iterate. Rows arrive in batches of
<code>fetchSize</code> (default 500) and the connection stays pinned until the cursor is
drained or closed. This keeps memory flat regardless of how many rows match.
</p>
<blockquote class="doc-quote">
<p>“Cursors are the difference between exporting a million rows and crashing a pod. Use them.” — <cite>Aurora DB field guide</cite></p>
</blockquote>
<div class="codeblock" data-lang-block>
<div class="code-tabs" role="tablist" aria-label="Cursor example">
<button class="code-tab active" role="tab" aria-selected="true" data-lang="js">JavaScript</button>
<button class="code-tab" role="tab" aria-selected="false" data-lang="python">Python</button>
<button class="copy-btn" type="button" aria-label="Copy code">
<svg class="i-copy" viewBox="0 0 24 24" width="15" height="15" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10" fill="none" stroke="currentColor" stroke-width="2"/></svg>
<span class="copy-label">Copy</span>
</button>
</div>
<pre class="code" data-lang="js"><code><span class="c-kw">const</span> cur = db.<span class="c-fn">cursor</span>(<span class="c-st">"select * from event order by ts"</span>, [], {
fetchSize: <span class="c-nm">500</span>,
});
<span class="c-kw">for await</span> (<span class="c-kw">const</span> row <span class="c-kw">of</span> cur) {
<span class="c-kw">await</span> <span class="c-fn">sink</span>(row); <span class="c-cm">// backpressure-aware</span>
}</code></pre>
<pre class="code" data-lang="python" hidden><code><span class="c-kw">with</span> db.<span class="c-fn">cursor</span>(<span class="c-st">"select * from event order by ts"</span>, fetch_size=<span class="c-nm">500</span>) <span class="c-kw">as</span> cur:
<span class="c-kw">for</span> row <span class="c-kw">in</span> cur:
<span class="c-fn">sink</span>(row) <span class="c-cm"># streamed batch by batch</span></code></pre>
</div>
<div class="callout tip" role="note">
<div class="callout-ic" aria-hidden="true">
<svg viewBox="0 0 24 24" width="18" height="18"><path d="M9 18h6M10 21h4" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><path d="M12 3a6 6 0 0 0-3.5 10.9c.6.5 1 1.2 1 2.1h5c0-.9.4-1.6 1-2.1A6 6 0 0 0 12 3Z" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/></svg>
</div>
<div class="callout-body">
<p class="callout-title">Tip</p>
<p>Wrap a cursor in a transaction with <code>{ isolation: "repeatable read" }</code> to get a stable snapshot across the whole export.</p>
</div>
</div>
<h2 id="errors">Error handling</h2>
<p>
Failed queries throw an <code>AuroraError</code> with a stable <code>code</code> you can
switch on. Network faults are retried automatically up to <code>maxRetries</code>; only
logical errors surface to your code.
</p>
<ul class="doc-list">
<li><code>23505</code> — unique violation</li>
<li><code>40001</code> — serialization failure (safe to retry)</li>
<li><code>57014</code> — statement timeout</li>
<li><code>53300</code> — too many connections</li>
</ul>
<nav class="page-nav" aria-label="Page navigation">
<a class="page-nav-link prev" href="#main">
<span class="pn-dir">Previous</span>
<span class="pn-title">Connections</span>
</a>
<a class="page-nav-link next" href="#main">
<span class="pn-dir">Next</span>
<span class="pn-title">Transactions</span>
</a>
</nav>
<footer class="article-foot">
<a class="edit-link" href="#main">Edit this page on GitHub →</a>
<p class="foot-note">Was this page helpful?
<button class="vote" type="button" data-vote="up">👍 Yes</button>
<button class="vote" type="button" data-vote="down">👎 No</button>
</p>
</footer>
</article>
</main>
<!-- RIGHT: TOC -->
<aside class="toc" aria-label="On this page">
<p class="toc-label">On this page</p>
<ul class="toc-list" id="tocList">
<li><a href="#overview" data-toc>Overview</a></li>
<li><a href="#install" data-toc>Install</a></li>
<li><a href="#basic-query" data-toc>A basic query</a></li>
<li><a href="#typed-rows" data-toc>Typed rows</a></li>
<li><a href="#cursors" data-toc>Streaming with cursors</a></li>
<li><a href="#errors" data-toc>Error handling</a></li>
</ul>
<div class="toc-card">
<p class="toc-card-title">Need help?</p>
<p>Join the <a href="#main">community Discord</a> or open an issue on the tracker.</p>
</div>
</aside>
</div>
<div class="toast" id="toast" role="status" aria-live="polite"></div>
<script src="script.js"></script>
</body>
</html>Docs Page (dev-docs layout + code)
A full developer-documentation page modeled on the Stripe and Tailwind docs feel and rendered for a fictional Aurora DB SDK reference. The shell is a three-column grid: a collapsible doc-tree navigation on the left with expandable branches, a centered article column capped near 760px that mixes an Inter UI chrome with a Source Serif 4 reading body, and a right-rail table of contents. The article carries breadcrumbs, an eyebrow and lede, Note / Tip / Warning callouts, a typed-columns reference table, a pull quote, and prev/next page links.
The code blocks are the centerpiece: each one is wrapped in a tabbed panel that swaps between cURL, JavaScript, and Python samples, with faux syntax-token coloring in JetBrains Mono and a copy button that writes the active snippet to the clipboard and confirms with a toast. A header theme toggle flips the whole page between a clean white and a dark palette and remembers the choice in localStorage, falling back to the OS preference on first load.
Interactions are pure vanilla JS: language tabs, clipboard copy with a graceful execCommand fallback, doc-tree collapse, an IntersectionObserver scrollspy that highlights the current TOC entry, a / shortcut that focuses search, page-helpfulness voting, and a mobile drawer with a scrim that collapses the sidebar below 820px down to 360px.
Illustrative UI only — fictional articles, products, and data.