How to Configure Agent-Native Deployment with Postgres, Turso, SQLite, and PGlite

Agent-Native uses Drizzle ORM to abstract database persistence, allowing you to configure any SQL-compatible provider by setting specific environment variables that the createDrizzleConfig function automatically detects.

The open-source BuilderIO/agent-native repository centralizes all database provider logic in a single configuration helper. By inspecting connection strings and authentication tokens at runtime, the framework eliminates vendor-specific code changes when switching between SQLite, PostgreSQL, Turso, or PGlite backends.

How Database Detection Works

The core configuration logic lives in packages/core/src/db/drizzle-config.ts. The createDrizzleConfig function implements a cascading resolution strategy to determine which database dialect to use.

Environment Variable Resolution

The system searches for connection strings in a specific priority order. First, it checks for an app-specific variable using the pattern <APP_NAME>_DATABASE_URL. If undefined, it falls back to the generic DATABASE_URL. When neither variable is present, the runtime defaults to a local SQLite file at file:./data/app.db—perfect for development environments without external infrastructure.

Provider Detection Logic

Once a URL is resolved, the code performs string prefix matching to determine the dialect:

• Postgres: URLs starting with postgres:// or postgresql://
• PGlite: URLs beginning with pglite:
• Turso / libSQL: URLs starting with libsql://
• SQLite: Any other string pattern (treated as a local file path)

This detection occurs in the dialect resolution section of drizzle-config.ts, where the function maps these patterns to Drizzle's internal driver configuration.

Authentication and Safety Guards

For Turso/libSQL deployments, the code requires an additional DATABASE_AUTH_TOKEN environment variable (or <APP_NAME>_DATABASE_AUTH_TOKEN for app-scoped overrides). The configuration throws a clear error if the token is missing when a libsql:// URL is detected.

The system also includes a protective guard against destructive operations: if drizzle-kit push targets a Neon database URL, the process aborts unless ALLOW_DRIZZLE_PUSH_ON_NEON=1 is explicitly set. This prevents accidental schema drops in production environments managed by Neon.

Supported Database Providers

Agent-Native officially supports five deployment patterns through Drizzle ORM's driver ecosystem.

SQLite (Development Fallback)

Best for: Serverless edge functions and local development without Docker.

Use file:./data/app.db as your DATABASE_URL. No additional tokens or drivers are required. Note that data persists only for the lifetime of the serverless process; data is wiped on cold starts unless you configure a persistent volume mount.

PostgreSQL (Neon, Supabase, Self-Hosted)

Best for: Production workloads requiring complex queries and concurrent connections.

Set DATABASE_URL to a standard PostgreSQL connection string: postgres://user:password@host:port/database. This works with Neon, Supabase, AWS RDS, or any Postgres-compatible provider. The dialect detection automatically configures the pg driver.

Turso / libSQL

Best for: Edge-deployed SQLite with global replication.

Configure DATABASE_URL=libsql://your-instance.tursodatabase.com and provide DATABASE_AUTH_TOKEN with your Turso platform token. The createDrizzleConfig function automatically includes the @libsql/client driver credentials in the generated configuration.

PGlite (Embedded PostgreSQL)

Best for: Development environments requiring Postgres features without installing PostgreSQL.

Install @electric-sql/pglite as a dependency, then set DATABASE_URL=pglite:./data/pglite. This embeds a WASM PostgreSQL instance in your Node.js process, enabling full Postgres compatibility locally while maintaining the ability to deploy to managed Postgres in production.

Cloud-Native SQLite (D1, LiteFS)

Best for: Cloudflare Workers and Netlify Edge Functions.

While detected as standard SQLite (file: protocol), you can integrate with Cloudflare D1 or LiteFS by adjusting the file path to match your platform's storage bindings. The underlying SQL layer remains identical across providers.

Implementation Examples

Basic Database Instance Setup

Create a typed Drizzle client in your server code:

// server/db/index.ts
import { createDrizzleConfig } from "@agent-native/core/db/drizzle-config";
import { drizzle } from "drizzle-orm";
import * as schema from "./schema";

export const db = drizzle(createDrizzleConfig(), { schema });

The createDrizzleConfig() call returns a defineConfig object containing the detected dialect, optional driver (for PGlite), and sanitized dbCredentials. Actions throughout the codebase import db from this file, making the underlying provider transparent to business logic.

Environment Configuration Template

Document required variables in .env.example:

# Development fallback (SQLite)

DATABASE_URL=file:./data/app.db

# Production Turso configuration

# DATABASE_URL=libsql://your-db.tursodatabase.com

# DATABASE_AUTH_TOKEN=your-turso-token

# Production Postgres configuration

# DATABASE_URL=postgresql://user:pass@host:5432/dbname

# Allow drizzle-kit push on Neon (use with caution)

# ALLOW_DRIZZLE_PUSH_ON_NEON=1

Platform-Specific Deployment

Netlify with Neon Postgres:

netlify env:set DATABASE_URL postgresql://user:pass@host:5432/db

Local Development with PGlite:

pnpm add @electric-sql/pglite
DATABASE_URL=pglite:./data/pglite pnpm dev

Running Migrations Safely:

// migration-script.ts
import { runMigrations } from "@agent-native/core/db/migrations";

// Executes additive-only SQL changes safe for any provider
await runMigrations();

Deployment Checklist

Before deploying Agent-Native to production, verify these configuration steps:

1. Select your provider and obtain a persistent connection string from your database host.
2. Set the environment variable: Configure DATABASE_URL (or <APP_NAME>_DATABASE_URL for multi-app deployments) in your hosting platform.
3. Configure Turso tokens: If using Turso/libSQL, add DATABASE_AUTH_TOKEN to your secrets.
4. Commit .env.example: Document required keys for teammates without exposing real credentials.
5. Verify locally: Run pnpm dev with production-like environment variables to confirm the dialect detection works.
6. Review safety guards: Ensure ALLOW_DRIZZLE_PUSH_ON_NEON is only set in CI/CD pipelines where destructive schema changes are intentional.

Summary

• Agent-Native abstracts database details through Drizzle ORM, using createDrizzleConfig in packages/core/src/db/drizzle-config.ts to auto-detect providers.
• Environment variable resolution follows this priority: <APP>_DATABASE_URL → DATABASE_URL → local SQLite fallback.
• Supported providers include SQLite (file), PostgreSQL (Neon/Supabase/self-hosted), Turso/libSQL (edge SQLite), and PGlite (embedded Postgres).
• Turso requires DATABASE_AUTH_TOKEN in addition to the connection URL.
• Neon protection prevents accidental drizzle-kit push operations unless explicitly enabled via ALLOW_DRIZZLE_PUSH_ON_NEON=1.
• All templates include documentation in their respective DEVELOPING.md files (e.g., templates/videos/DEVELOPING.md).

Frequently Asked Questions

Does Agent-Native support MySQL or MongoDB?

No. Agent-Native is architected specifically for SQL-compatible databases accessed through Drizzle ORM. The createDrizzleConfig function only recognizes PostgreSQL and SQLite dialects (including libSQL/Turso variants). For document storage or other NoSQL requirements, you would need to implement a separate persistence layer outside the core database configuration.

Why does my Turso deployment fail with an authentication error?

The Agent-Native configuration strictly requires a DATABASE_AUTH_TOKEN environment variable when the DATABASE_URL starts with libsql://. The code in drizzle-config.ts explicitly checks for this token and throws a configuration error if missing. Ensure you have copied the token from the Turso CLI or dashboard and that the variable name matches exactly (case-sensitive).

Can I use different databases for development and production?

Yes. The environment-based configuration makes this seamless. Use file:./data/app.db or pglite:./data/pglite locally, then override with postgresql:// or libsql:// URLs in production. The server/db/index.ts file exports the same Drizzle-typed interface regardless of the underlying driver, ensuring your actions and queries work identically across environments.

How do I prevent accidental schema drops in production?

The framework includes a runtime guard that intercepts drizzle-kit push commands targeting Neon databases. If your DATABASE_URL contains neon.tech and you attempt to push schema changes, the process exits with an error unless you set ALLOW_DRIZZLE_PUSH_ON_NEON=1. Additionally, the CI pipeline includes scripts/guard-no-drizzle-push.mjs to block destructive operations in automated environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}