Files
skills/public/hip-0029.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&#x27;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>&lt;service&gt; -- e.g., iam, cloud, console, kms, platform, commerce
&lt;service&gt;_&lt;env&gt; -- 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 &#x27;&lt;from-kms&gt;&#x27;;
GRANT ALL PRIVILEGES ON DATABASE iam TO iam_user;
CREATE USER cloud_user WITH PASSWORD &#x27;&lt;from-kms&gt;&#x27;;
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 &amp;&amp; \
apt-get install -y postgresql-16-pgvector &amp;&amp; \
rm -rf /var/lib/apt/lists/*
# Install additional extensions
RUN apt-get update &amp;&amp; \
apt-get install -y postgresql-16-pg-trgm &amp;&amp; \
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 [&quot;postgres&quot;, &quot;-c&quot;, &quot;config_file=/etc/postgresql/postgresql.conf&quot;]</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: &quot;1Gi&quot;
cpu: &quot;500m&quot;
limits:
memory: &quot;2Gi&quot;
cpu: &quot;2000m&quot;
livenessProbe:
exec:
command: [&quot;pg_isready&quot;, &quot;-U&quot;, &quot;hanzo&quot;]
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
exec:
command: [&quot;pg_isready&quot;, &quot;-U&quot;, &quot;hanzo&quot;]
initialDelaySeconds: 5
periodSeconds: 5
volumeClaimTemplates:
- metadata:
name: postgres-data
spec:
accessModes: [&quot;ReadWriteOnce&quot;]
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: &quot;0 */6 * * *&quot; # 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} &gt; ${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 &#x27;{print $2}&#x27; | \
while read dir; do
dir_date=$(echo $dir | tr -d &#x27;/&#x27;)
if [ $(date -d &quot;$dir_date&quot; +%s 2&gt;/dev/null || echo 0) -lt \
$(date -d &#x27;30 days ago&#x27; +%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> | &gt; 150 | Active connection count | | <code>pg_database_size_bytes</code> | &gt; 40GB | Database size | | <code>pg_stat_bgwriter_buffers_backend</code> | Increasing | Shared buffer pressure | | <code>pg_replication_lag_seconds</code> | &gt; 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: &quot;200&quot;
- name: PGBOUNCER_DEFAULT_POOL_SIZE
value: &quot;20&quot;</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>