Docs

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).

The chat app, the database, and the model all run in the customer's account. Only releases come from your side.

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

alien.ts
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()
  • app is 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.
  • db is private. Only workloads in the same stack can reach it.
  • llm means "the model service in this deployment's cloud". It names no model.
  • The app profile 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

app/api/models/route.ts
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.

app/queries.ts
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:

app/queries.ts
    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

app/db.ts
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

app/api/chat/route.ts
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:

app/api/chat/route.ts
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 a baseURL and, locally, an apiKey.
  • The gateway behind that URL forwards each model in its own protocol, so modelFor picks 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 stray ANTHROPIC_API_KEY in 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 dev

alien 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:

  1. The first question creates and fills two demo tables, customers and orders.
  2. The model calls queryDatabase, typically with total_mrr_by_plan and plan: "enterprise", and summarizes the row it gets back.
  3. 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.com

alien 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

Platformappdbllm
AWSReplicas on EC2 machines, load balancerAurora PostgreSQL Serverless v2Access to Amazon Bedrock
Google CloudReplicas on Compute Engine machines, Google Cloud load balancingCloud SQL, reached through Private Service ConnectVertex AI API and a prediction-only role
AzureReplicas on Azure VMs, Azure load balancingDatabase for PostgreSQL Flexible Server, reached through a private endpointAzure AI Foundry account with GPT deployments
alien devDocker containerLocal PostgreSQL processYour 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/chat and 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 db binding's credentials belong to the admin user (alien on the clouds); default_transaction_read_only is a session default, not a permission.
  • Remove the seeding and the advisory lock; use your migrations.

Next

On this page