Database and local development

Bahama Cloud can attach a native SQL database directly to a hosted Hono application. Production code receives it as env.DB; there is no host, password, or connection string to copy.

The bahama-runtime package gives your local server code the same database interface through project-scoped development access. Your agent can prepare all of this from the manifest.

Ask your agent to add the database

Add a Bahama Cloud SQL database to this application. Make the same server-side
database code work locally and after deployment. Handle the manifest, runtime
package, and setup for me, and show me the plan before creating anything.

Your agent adds a native database resource and three local-development bindings:

resources:
  database:
    provider: bahama-cloud
    environment: production
 
bindings:
  BAHAMA_API_BASE_URL:
    from: environments.production.developmentApiBaseUrl
    to: environments.local.variables
  BAHAMA_PROJECT_SLUG:
    from: environments.production.developmentProjectSlug
    to: environments.local.variables
  BAHAMA_DEV_TOKEN:
    from: environments.production.developmentToken
    to: environments.local.variables

After you approve and apply the infrastructure plan, the local provider writes these values to the protected, gitignored environment file. No application code is deployed yet.

Use one server-side interface

Your agent installs the runtime package:

npm install bahama-runtime

Database code imports the server entry only:

import { getDb, type BahamaDatabase } from "bahama-runtime/server";
 
type Note = {
  id: number;
  body: string;
};
 
export async function listNotes(env: { DB?: BahamaDatabase }) {
  const result = await getDb(env)
    .prepare("select id, body from notes order by id desc")
    .all<Note>();
 
  return result.results ?? [];
}

In Cloud, getDb(env) returns the native env.DB binding. Locally, it reads the three protected environment values and sends the operation through the project-scoped development API. Production database traffic does not pass through that development API.

Never import bahama-runtime/server into browser code. The browser calls a server route; the server route calls getDb.

Create schema deliberately

Bahama Cloud does not currently turn a migrations directory into planned database migrations. Your application must create or update schema explicitly. Keep setup idempotent:

const db = getDb(env);
 
await db.prepare(`
  create table if not exists notes (
    id integer primary key autoincrement,
    body text not null
  )
`).run();

Use bound parameters for application values. Ask before dropping tables, deleting broad data, or performing a large backfill.

Understand the local boundary

Local access reaches the real Cloud project database. Treat it as live data, not as a disposable local copy.

The local bridge supports ordinary prepared statements, reads, and writes. It does not support binary SQL parameters or dump(). Local batch() calls are not atomic, session bookmarks are not preserved, and result metadata can differ from the native runtime.

Run code that depends on those native-only behaviors in a dedicated deployed test project.