mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
505 lines
25 KiB
HTML
505 lines
25 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0029</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant โ
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0029.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0029">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0029.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0029</h1><p class="lede">HIP-29: Relational Database Standard. Status Active. Hanzo's own standard โ read this before implementing against it.</p><h1>HIP-0029: Relational Database Standard</h1>
|
|
<h2>Abstract</h2>
|
|
<p>This proposal defines the relational database standard for all Hanzo services. Hanzo SQL provides relational data storage via SQL, deployed as in-cluster StatefulSets on each Kubernetes Kubernetes cluster. Every Hanzo service that requires persistent relational storage MUST connect to the cluster-local SQL instance following this specification.</p>
|
|
<p><strong>Repository</strong>: <a href="https://github.com/hanzoai/postgres">github.com/hanzoai/postgres</a> <strong>Image</strong>: <code>ghcr.io/hanzoai/sql:latest</code></p>
|
|
<h2>Specification</h2>
|
|
<p> npx prisma migrate dev # Development npx prisma migrate deploy # Production ```</p>
|
|
<ol><li><strong>Beego ORM auto-sync</strong> (IAM only, legacy)</li></ol>
|
|
<ul><li>Controlled by <code>autoMigrate</code> in <code>conf/app.conf</code></li><li>MUST be <code>false</code> in production after initial setup</li></ul>
|
|
<ol><li><strong>Raw SQL migrations</strong> (Go services, shell scripts)</li></ol>
|
|
<ul><li>Stored in <code>migrations/</code> directory</li><li>Numbered sequentially: <code>001_initial.sql</code>, <code>002_add_vectors.sql</code></li><li>Applied via <code>psql</code> or a lightweight migration tool</li></ul>
|
|
<p>All migrations MUST be:</p>
|
|
<ul><li><strong>Idempotent</strong>: Safe to run multiple times (<code>IF NOT EXISTS</code>, <code>IF NOT EXISTS</code>)</li><li><strong>Forward-only</strong>: No down migrations in production</li><li><strong>Reviewed</strong>: Schema changes require PR review from infrastructure team</li><li><strong>Tested</strong>: Run against a test database before production</li></ul>
|
|
<h3>Database Naming Convention</h3>
|
|
<pre><code><service> -- e.g., iam, cloud, console, kms, platform, commerce
|
|
<service>_<env> -- only if running multiple environments in one cluster</code></pre>
|
|
<p>Database names MUST be lowercase, use underscores (not hyphens), and match the service name exactly. The exception is <code>hanzo_cloud</code> which is a legacy name retained for backward compatibility.</p>
|
|
<h3>User and Role Standard</h3>
|
|
<p>Each database MUST have a dedicated user:</p>
|
|
<pre><code class="lang-sql">-- Per-database user (created by KMS bootstrap)
|
|
CREATE USER iam_user WITH PASSWORD '<from-kms>';
|
|
GRANT ALL PRIVILEGES ON DATABASE iam TO iam_user;
|
|
|
|
CREATE USER cloud_user WITH PASSWORD '<from-kms>';
|
|
GRANT ALL PRIVILEGES ON DATABASE cloud TO cloud_user;</code></pre>
|
|
<p>A superuser <code>hanzo</code> exists for administrative operations (backups, extension installation, new database creation). Service applications MUST NOT use the superuser account.</p>
|
|
<h2>Implementation</h2>
|
|
<h3>Container Image</h3>
|
|
<p>The Hanzo SQL image is built from the official SQL 16 image with extensions pre-installed:</p>
|
|
<pre><code class="lang-dockerfile">FROM postgres:16-bookworm
|
|
|
|
# Install pgvector
|
|
RUN apt-get update && \
|
|
apt-get install -y postgresql-16-pgvector && \
|
|
rm -rf /var/lib/apt/lists/*
|
|
|
|
# Install additional extensions
|
|
RUN apt-get update && \
|
|
apt-get install -y postgresql-16-pg-trgm && \
|
|
rm -rf /var/lib/apt/lists/*
|
|
|
|
# Custom entrypoint for extension initialization
|
|
COPY init-extensions.sh /docker-entrypoint-initdb.d/
|
|
|
|
# Custom postgresql.conf
|
|
COPY postgresql.conf /etc/postgresql/postgresql.conf
|
|
|
|
CMD ["postgres", "-c", "config_file=/etc/postgresql/postgresql.conf"]</code></pre>
|
|
<p><strong>Image</strong>: <code>ghcr.io/hanzoai/sql:latest</code> <strong>Base</strong>: <code>postgres:16-bookworm</code> <strong>Architectures</strong>: <code>linux/amd64</code>, <code>linux/arm64</code></p>
|
|
<h3>Kubernetes StatefulSet</h3>
|
|
<pre><code class="lang-yaml">apiVersion: apps/v1
|
|
kind: StatefulSet
|
|
metadata:
|
|
name: postgres
|
|
namespace: hanzo
|
|
spec:
|
|
serviceName: postgres
|
|
replicas: 1
|
|
selector:
|
|
matchLabels:
|
|
app: postgres
|
|
template:
|
|
metadata:
|
|
labels:
|
|
app: postgres
|
|
spec:
|
|
containers:
|
|
- name: postgres
|
|
image: ghcr.io/hanzoai/sql:latest
|
|
ports:
|
|
- containerPort: 5432
|
|
env:
|
|
- name: POSTGRES_USER
|
|
valueFrom:
|
|
secretKeyRef:
|
|
name: postgres-credentials
|
|
key: username
|
|
- name: POSTGRES_PASSWORD
|
|
valueFrom:
|
|
secretKeyRef:
|
|
name: postgres-credentials
|
|
key: password
|
|
volumeMounts:
|
|
- name: postgres-data
|
|
mountPath: /var/lib/postgresql/data
|
|
resources:
|
|
requests:
|
|
memory: "1Gi"
|
|
cpu: "500m"
|
|
limits:
|
|
memory: "2Gi"
|
|
cpu: "2000m"
|
|
livenessProbe:
|
|
exec:
|
|
command: ["pg_isready", "-U", "hanzo"]
|
|
initialDelaySeconds: 30
|
|
periodSeconds: 10
|
|
readinessProbe:
|
|
exec:
|
|
command: ["pg_isready", "-U", "hanzo"]
|
|
initialDelaySeconds: 5
|
|
periodSeconds: 5
|
|
volumeClaimTemplates:
|
|
- metadata:
|
|
name: postgres-data
|
|
spec:
|
|
accessModes: ["ReadWriteOnce"]
|
|
storageClassName: do-block-storage
|
|
resources:
|
|
requests:
|
|
storage: 50Gi
|
|
---
|
|
apiVersion: v1
|
|
kind: Service
|
|
metadata:
|
|
name: postgres
|
|
namespace: hanzo
|
|
spec:
|
|
selector:
|
|
app: postgres
|
|
ports:
|
|
- port: 5432
|
|
targetPort: 5432
|
|
clusterIP: None # Headless for StatefulSet</code></pre>
|
|
<h3>Backup Strategy</h3>
|
|
<p>Backups run via a Kubernetes CronJob:</p>
|
|
<pre><code class="lang-yaml">apiVersion: batch/v1
|
|
kind: CronJob
|
|
metadata:
|
|
name: postgres-backup
|
|
namespace: hanzo
|
|
spec:
|
|
schedule: "0 */6 * * *" # Every 6 hours
|
|
jobTemplate:
|
|
spec:
|
|
template:
|
|
spec:
|
|
containers:
|
|
- name: backup
|
|
image: ghcr.io/hanzoai/sql:latest
|
|
command:
|
|
- /bin/sh
|
|
- -c
|
|
- |
|
|
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
|
|
BACKUP_DIR=/backups/${TIMESTAMP}
|
|
mkdir -p ${BACKUP_DIR}
|
|
|
|
# Dump each database separately
|
|
for db in iam cloud console hanzo_cloud kms platform; do
|
|
pg_dump -h localhost -U hanzo \
|
|
-Fc --no-owner --no-acl \
|
|
${db} > ${BACKUP_DIR}/${db}.dump
|
|
done
|
|
|
|
# Upload to S3-compatible storage
|
|
aws s3 sync ${BACKUP_DIR} \
|
|
s3://hanzo-backups/postgres/${TIMESTAMP}/ \
|
|
--endpoint-url ${S3_ENDPOINT}
|
|
|
|
# Clean up local
|
|
rm -rf ${BACKUP_DIR}
|
|
|
|
# Prune backups older than 30 days
|
|
aws s3 ls s3://hanzo-backups/postgres/ \
|
|
--endpoint-url ${S3_ENDPOINT} | \
|
|
awk '{print $2}' | \
|
|
while read dir; do
|
|
dir_date=$(echo $dir | tr -d '/')
|
|
if [ $(date -d "$dir_date" +%s 2>/dev/null || echo 0) -lt \
|
|
$(date -d '30 days ago' +%s) ]; then
|
|
aws s3 rm --recursive \
|
|
s3://hanzo-backups/postgres/${dir} \
|
|
--endpoint-url ${S3_ENDPOINT}
|
|
fi
|
|
done
|
|
envFrom:
|
|
- secretRef:
|
|
name: postgres-credentials
|
|
- secretRef:
|
|
name: s3-backup-credentials
|
|
restartPolicy: OnFailure</code></pre>
|
|
<p><strong>Backup schedule</strong>: Every 6 hours <strong>Retention</strong>: 30 days <strong>Storage</strong>: S3-compatible (MinIO in-cluster or DO Spaces) <strong>Format</strong>: pg_dump custom format (<code>-Fc</code>) for selective restore</p>
|
|
<h3>Restore Procedure</h3>
|
|
<pre><code class="lang-bash"># Download backup
|
|
aws s3 cp s3://hanzo-backups/postgres/20260215_060000/iam.dump ./iam.dump \
|
|
--endpoint-url ${S3_ENDPOINT}
|
|
|
|
# Restore to database
|
|
pg_restore -h localhost -U hanzo \
|
|
-d iam --clean --if-exists --no-owner \
|
|
./iam.dump</code></pre>
|
|
<h3>Monitoring</h3>
|
|
<p>PostgreSQL metrics are exposed via <code>postgres_exporter</code> sidecar to Prometheus:</p>
|
|
<p>| Metric | Alert Threshold | Description | |--------|----------------|-------------| | <code>pg_stat_activity_count</code> | > 150 | Active connection count | | <code>pg_database_size_bytes</code> | > 40GB | Database size | | <code>pg_stat_bgwriter_buffers_backend</code> | Increasing | Shared buffer pressure | | <code>pg_replication_lag_seconds</code> | > 60s | Replication lag (when enabled) | | <code>pg_up</code> | 0 | SQL is down |</p>
|
|
<h2>Security</h2>
|
|
<h3>Network Isolation</h3>
|
|
<pre><code class="lang-yaml">apiVersion: networking.k8s.io/v1
|
|
kind: NetworkPolicy
|
|
metadata:
|
|
name: postgres-network-policy
|
|
namespace: hanzo
|
|
spec:
|
|
podSelector:
|
|
matchLabels:
|
|
app: postgres
|
|
policyTypes:
|
|
- Ingress
|
|
ingress:
|
|
- from:
|
|
- namespaceSelector:
|
|
matchLabels:
|
|
name: hanzo
|
|
ports:
|
|
- protocol: TCP
|
|
port: 5432</code></pre>
|
|
<p>Only pods in the <code>hanzo</code> namespace can connect. All other traffic is denied.</p>
|
|
<h3>pg_hba.conf</h3>
|
|
<pre><code># TYPE DATABASE USER ADDRESS METHOD
|
|
local all all trust
|
|
host all all 127.0.0.1/8 md5
|
|
host all all 0.0.0.0/0 reject</code></pre>
|
|
<ul><li>Local socket connections (within the pod): trusted</li><li>Pod network (127.0.0.1/8): password authentication</li><li>Everything else: rejected</li></ul>
|
|
<h3>Credential Management</h3>
|
|
<p>All database passwords are managed by Hanzo KMS (kms.hanzo.ai):</p>
|
|
<ol><li>KMS stores <code>DATABASE_URL</code> for each service</li><li><code>KMSSecret</code> CRDs sync secrets into Kubernetes</li><li>Pods mount secrets as environment variables</li><li>Password rotation: update in KMS, restart affected pods</li></ol>
|
|
<pre><code class="lang-yaml"># KMSSecret resource for IAM database credentials
|
|
apiVersion: secrets.lux.network/v1alpha1
|
|
kind: KMSSecret
|
|
metadata:
|
|
name: iam-database
|
|
namespace: hanzo
|
|
spec:
|
|
hostAPI: https://kms.hanzo.ai/api
|
|
authentication:
|
|
universalAuth:
|
|
secretsScope:
|
|
envSlug: prod
|
|
secretsPath: /iam
|
|
credentialsRef:
|
|
secretName: kms-universal-auth
|
|
secretNamespace: hanzo
|
|
managedSecretReference:
|
|
secretName: iam-database-url
|
|
secretNamespace: hanzo
|
|
secretType: Opaque</code></pre>
|
|
<h3>Encryption</h3>
|
|
<ul><li><strong>In transit</strong>: Not required within cluster (pod-to-pod traffic is encrypted</li></ul>
|
|
<p> at the CNI level on Kubernetes). If cross-cluster replication is ever added, TLS MUST be enabled on the replication connection.</p>
|
|
<ul><li><strong>At rest</strong>: DigitalOcean block storage volumes are encrypted at the</li></ul>
|
|
<p> infrastructure level. PVC data inherits this encryption.</p>
|
|
<h2>Compatibility</h2>
|
|
<h3>IAM Dual-Engine Support</h3>
|
|
<p>Hanzo IAM supports both MySQL and SQL. For local development convenience, MySQL is available:</p>
|
|
<pre><code class="lang-bash"># Local dev with MySQL
|
|
docker compose -f compose.mysql.yml up -d
|
|
cp conf/app.mysql.conf conf/app.conf
|
|
|
|
# Staging/Production MUST use SQL
|
|
cp conf/app.dev.conf conf/app.conf # SQL config</code></pre>
|
|
<p>The <code>driverName</code> in <code>conf/app.conf</code> determines the engine:</p>
|
|
<pre><code class="lang-ini">driverName = postgres # Production (REQUIRED)
|
|
driverName = mysql # Local development only</code></pre>
|
|
<h3>Connection Pooling</h3>
|
|
<p>For services with high connection churn (API gateways, serverless functions), connection pooling via PgBouncer MAY be deployed as a sidecar:</p>
|
|
<pre><code class="lang-yaml"># PgBouncer sidecar (optional, per-service)
|
|
- name: pgbouncer
|
|
image: bitnami/pgbouncer:latest
|
|
env:
|
|
- name: POSTGRESQL_HOST
|
|
value: localhost
|
|
- name: PGBOUNCER_POOL_MODE
|
|
value: transaction
|
|
- name: PGBOUNCER_MAX_CLIENT_CONN
|
|
value: "200"
|
|
- name: PGBOUNCER_DEFAULT_POOL_SIZE
|
|
value: "20"</code></pre>
|
|
<p>This is optional. Most services maintain persistent connections and do not require pooling.</p>
|
|
<h2>Future Work</h2>
|
|
<h3>Phase 3: Logical Replication for Cross-Cluster Sync</h3>
|
|
<p>If the cluster and lux-k8s need shared data (e.g., unified user directory):</p>
|
|
<pre><code>the cluster postgres โ Logical Replication โ lux-k8s postgres
|
|
(publisher) (subscriber)</code></pre>
|
|
<h2>References</h2>
|
|
<ol><li><a href="./hip-0000-hanzo-ai-architecture-framework.md">HIP-0: Architecture</a></li><li><a href="./hip-0014-application-deployment-standard.md">HIP-14: Application Deployment Standard</a></li><li><a href="https://www.postgresql.org/docs/16/">PostgreSQL 16 Documentation</a></li><li><a href="https://github.com/pgvector/pgvector">pgvector</a></li><li><a href="https://infisical.com/docs">Infisical KMS</a></li></ol>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0029.md">This page as plain text</a> ยท <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div>
|
|
</body></html> |