Chat with a private Postgres database
This example builds a chat app over a customer's private Postgres database, where rows never pass through your backend and no model-provider key exists anywhere. The app, the database, and the model all run in their cloud account.
Architecture diagram. Left: Your cloud, Releases. Right: Customer cloud containing app · Next.js chat; db (Postgres); llm (AI).
You build a streaming Next.js chat app that:
- Answers questions like "Which enterprise customers bring in the most MRR?" from a private Postgres.
- Calls the model service in the customer's cloud with the app's own identity.
- Lets the model pick one of seven questions and a few bounded filters, while the app owns the SQL that runs.
Source: examples/ai-chatbot-ts.
Why the whole loop runs there
A chat over data touches the customer's rows and the prompts that contain them. If either goes through your cloud, the customer has to approve your infrastructure and your model provider for that data.
Here both stay in their account:
- The database has no public endpoint.
- The model request goes to the model service in the same account, under the customer's terms and billing.
- The app image holds neither a database password nor a provider key. Alien resolves both while the app runs.
Three resources
import * as alien from "@alienplatform/core"
// A model-less AI resource. The customer's cloud serves the inference; the
// embedded gateway injects the workload's ambient identity, so no API keys.
const llm = new alien.AI("llm").build()
// A private Postgres, reachable only from same-stack workloads; the app resolves
// its connection at runtime from the binding, never from a checked-in secret.
const db = new alien.Postgres("db").build()
const app = new alien.Container("app")
.code({ type: "source", src: ".", toolchain: { type: "docker", dockerfile: "Dockerfile" } })
.cpu(0.5)
.memory("512Mi")
.port(3000)
// Unauthenticated on purpose, which is what makes the demo clickable; see the note
// above POST in app/api/chat/route.ts for what a real deployment owes this endpoint.
.publicEndpoint("web", 3000, "http")
// Next's standalone server reads these; HOSTNAME=0.0.0.0 binds all interfaces.
.environment({ PORT: "3000", HOSTNAME: "0.0.0.0" })
// Linking injects ALIEN_LLM_BINDING (and starts the gateway, exposed as
// ALIEN_AI_GATEWAY_URL) and ALIEN_DB_BINDING (the Postgres connection).
.link(llm)
.link(db)
.permissions("app")
.build()
export default new alien.Stack("ai-chatbot")
.platforms(["aws", "gcp", "azure"])
.add(llm, "live")
.add(db, "live")
.add(app, "live")
.permissions({
profiles: {
app: {
"*": ["ai/invoke", "postgres/data-access"],
},
},
})
.build()appis the Next.js chat UI, built from the Dockerfile as in Deploy a Next.js app. It's public because people open it in a browser.dbis private. Only workloads in the same stack can reach it.llmmeans "the model service in this deployment's cloud". It names no model.- The
appprofile grants model invocation and database access. Nothing else. "live"means Alien creates each resource and updates it on every release, without the customer's admin. See Frozen and live.
The Dockerfile uses node:22-trixie-slim, not Alpine: the SDK's native bindings need glibc 2.39 or newer.
next.config.ts keeps @alienplatform/bindings and @alienplatform/ai-gateway out of the bundle and traces their per-platform packages into the standalone output, so the native parts ship with the image.
Available models
import { ai } from "@alienplatform/sdk"
export async function GET() {
const models = await ai("llm").getAvailableModels()
return Response.json({ models: models.map(m => m.id) })
}The UI's model picker reads this route, so it only offers models the customer's cloud has enabled.
Questions, not SQL
The tool's input is a closed schema: one of seven questions, an optional plan or order status, and a row limit of at most 50.
export const QUESTIONS = [
"customer_count_by_plan",
"customer_count_by_country",
"total_mrr_by_plan",
"top_customers_by_mrr",
"orders_by_status",
"recent_orders",
"revenue_by_customer",
] as const
export const askSchema = z.object({
question: z.enum(QUESTIONS).describe("which question to answer"),
plan: z.enum(["enterprise", "pro", "starter"]).optional().describe("filter by plan"),
status: z.enum(["paid", "pending", "refunded"]).optional().describe("filter by order status"),
limit: z.number().int().min(1).max(50).default(10).describe("rows to return, at most 50"),
})plan() maps each question to SQL the app wrote, with the model's values bound as parameters:
case "top_customers_by_mrr":
return {
text: `select name, plan, country, mrr_usd from customers
where ($1::text is null or plan = $1)
order by mrr_usd desc limit $2`,
values: [planFilter ?? null, limit],
}The model can't send a table name, an expression, or a statement. It chooses which question to ask; the app decides what reaches the database.
A new kind of question is a code change: add it to QUESTIONS and write its query.
Read-only connection
export function queryPool(): Promise<Pool> {
if (!pool) {
pool = (async () => {
const conn = await postgres("db").connection()
// Field style + conn.ssl, NOT conn.connectionString: node-postgres parses the
// URL's sslmode and overrides ssl, which breaks the managed-cloud cert path.
return new Pool({
host: conn.host,
port: conn.port,
database: conn.database,
user: conn.username,
password: conn.password,
ssl: conn.ssl,
options: "-c default_transaction_read_only=on -c statement_timeout=10000",
})
})().catch(err => {
// Don't cache a failed resolution; let the next request retry.
pool = undefined
throw err
})
}
return pool
}postgres("db").connection() resolves the connection inside the running container. On the clouds, it reads the password from the cloud's secret store with the app's identity; the password is never in the binding or the image.
Every session is read-only, and every statement times out after ten seconds.
The demo seeds its tables on the first question through a separate write connection. It takes a Postgres advisory lock and uses a transaction with upserts, so several replicas can't half-seed the database. A real app uses its normal migrations instead.
The tool
const queryDatabase = tool({
description:
"Answer a question about the company's Postgres data. Pick the question that fits and " +
"narrow it with the optional filters. Data: customers (name, plan, country, monthly " +
"recurring revenue) and their orders (amount, status, date).",
inputSchema: askSchema,
execute: async (ask: Ask) => {
const ignored = unsupportedFilters(ask)
if (ignored.length > 0) {
const takes = supportedFilters(ask.question)
return {
error: `${ask.question} does not take ${ignored.join(" or ")}; it takes ${
takes.length > 0 ? takes.join(" and ") : "no filters"
}`,
}
}
await ensureSeeded()
const { text, values } = plan(ask)
const { rows } = await query(text, values)
return { question: ask.question, rows, rowCount: rows.length }
},
})A filter that doesn't apply to the chosen question is rejected with an error the model can read and correct, instead of being dropped silently. Otherwise the tool runs the planned query and returns the rows as evidence for the answer.
Streaming the answer
The route resolves the model connection per request, because the binding exists only in the running container, not at build time:
export async function POST(req: Request) {
const { messages, model }: { messages: UIMessage[]; model?: string } = await req.json()
// Model ids differ per cloud, so the fallback is the binding's first model, not a hardcoded id.
const modelId = model || (await ai("llm").getAvailableModels())[0]?.id
if (!modelId) {
return Response.json({ error: "the AI binding exposes no models" }, { status: 503 })
}
// Resolved per request: the binding env exists only in the running workload, not at build.
const connection = await getAiConnection("llm")
const result = streamText({
model: modelFor(modelId, connection),
system:
"You answer questions about the company's data. When a question needs data, call the " +
"queryDatabase tool and summarize what comes back in plain English. If no question in " +
"the tool covers what was asked, say what the data can and cannot answer.",
messages: await convertToModelMessages(messages),
// Without a stop condition the model never streams the answer after the tool result.
stopWhen: stepCountIs(6),
tools: { queryDatabase },
providerOptions: { anthropic: { toolStreaming: false } },
})
return result.toUIMessageStreamResponse()
}getAiConnection("llm")returns abaseURLand, locally, anapiKey.- The gateway behind that URL forwards each model in its own protocol, so
modelForpicks the client: the Anthropic client for Claude, the OpenAI-compatible client for everything else. - On a cloud binding there's no key, and
apiKey: ""keeps a strayANTHROPIC_API_KEYin the environment from being sent. stepCountIs(6)leaves room to call the tool and then answer, without an unbounded loop.
Run it locally
Your laptop has no cloud identity, so give alien dev a provider key:
alien init ai-chatbot-ts postgres-chat
cd postgres-chat
OPENAI_API_KEY=sk-... alien devalien dev builds the image, runs it in Docker, starts a local Postgres, and prints the app's URL. Open it and ask:
How many enterprise customers do we have, and what's their total MRR?
What happens:
- The first question creates and fills two demo tables,
customersandorders. - The model calls
queryDatabase, typically withtotal_mrr_by_planandplan: "enterprise", and summarizes the row it gets back. - See the data in the header opens the tables through the same read-only pool, so you can check the answer against the rows.
Then ask something the seven questions can't answer, such as churn by month. The model says what the data can and can't answer instead of inventing a query.
Deploy it
alien login
alien link
alien release
alien onboard customer-1 --allow admin@customer-1.comalien onboard customer-1 prints a setup link, a URL that opens the setup page Alien hosts for the customer's admin. The admin opens it and runs the initial setup (the one-time step) in their account.
Alien builds and pushes the image, then creates the database, the AI access, the machines for the Container, and the load balancer. Later releases update the app without the admin.
Read the app's URL from the dashboard or from the deployment's info under resources.app.publicEndpoints.web.url.
What gets created on each cloud
| Platform | app | db | llm |
|---|---|---|---|
| AWS | Replicas on EC2 machines, load balancer | Aurora PostgreSQL Serverless v2 | Access to Amazon Bedrock |
| Google Cloud | Replicas on Compute Engine machines, Google Cloud load balancing | Cloud SQL, reached through Private Service Connect | Vertex AI API and a prediction-only role |
| Azure | Replicas on Azure VMs, Azure load balancing | Database for PostgreSQL Flexible Server, reached through a private endpoint | Azure AI Foundry account with GPT deployments |
alien dev | Docker container | Local PostgreSQL process | Your provider key |
On AWS, Aurora scales to zero when idle. The first connection after a pause can take about 15 seconds, so the first question of the day is slow.
Claude appears in the model picker only after a one-time activation in the customer's cloud:
- Amazon Bedrock: the Anthropic use-case form.
- Vertex AI: Model Garden.
- Azure AI Foundry: Marketplace terms.
Other models work without it.
Before production
- Authenticate
/api/chatand rate-limit it per caller. - Connect to the customer's real database instead of a new one: drop
db, keep the connection in a Vault, and point the read-only pool at it. See Query a private database. - Create a read-only database role. The
dbbinding's credentials belong to the admin user (alienon the clouds);default_transaction_read_onlyis a session default, not a permission. - Remove the seeding and the advisory lock; use your migrations.
Next
GitHub integration
A full product split into a hosted Next.js dashboard and a small GitHub Worker that runs in each customer's environment, with the GitHub token kept in the customer's vault.
Webhooks and an API
Give each customer an HTTPS endpoint that stores webhooks in their own account, query the events from your backend with commands, and configure each deployment with stack inputs.