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

> Learn how to configure Agent-Native deployment with Postgres, Turso, SQLite, and PGlite. Easily integrate your preferred SQL provider using Drizzle ORM and environment variables.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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:

```typescript
// 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`:

```env

# 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:**

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

```

**Local Development with PGlite:**

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

```

**Running Migrations Safely:**

```typescript
// 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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPING.md) files (e.g., [`templates/videos/DEVELOPING.md`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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`](https://github.com/BuilderIO/agent-native/blob/main/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.