Instances

The console supports connecting to multiple better-auth databases simultaneously. Manage development, staging, and production environments - or multiple applications - from one interface.

Multi-Instance Setup

Add multiple instances to the exported array in instances.config.ts:

instances.config.ts

import { betterAuth } from 'better-auth';
import { drizzleAdapter } from 'better-auth/adapters/drizzle';
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './apps/web/lib/schema';

// Create connections for each environment
const prodClient = postgres(process.env.PROD_DATABASE_URL!);
const stagingClient = postgres(process.env.STAGING_DATABASE_URL!);
const devClient = postgres(process.env.DEV_DATABASE_URL!);

// Production instance
const productionAuth = betterAuth({
  secret: 'console-only',
  database: drizzleAdapter(drizzle(prodClient, { schema }), {
    provider: 'pg',
    schema,
  }),
  plugins: [organization(), admin(), apiKey()],
});

// Staging instance
const stagingAuth = betterAuth({
  secret: 'console-only',
  database: drizzleAdapter(drizzle(stagingClient, { schema }), {
    provider: 'pg',
    schema,
  }),
  plugins: [organization(), admin()],
});

// Development instance
const devAuth = betterAuth({
  secret: 'console-only',
  database: drizzleAdapter(drizzle(devClient, { schema }), {
    provider: 'pg',
    schema,
  }),
  plugins: [organization()],
});

export default [
  {
    id: 'production',
    name: 'Production',
    env: 'production',
    auth: productionAuth,
  },
  {
    id: 'staging',
    name: 'Staging',
    env: 'staging',
    auth: stagingAuth,
  },
  {
    id: 'development',
    name: 'Development',
    env: 'development',
    auth: devAuth,
  },
];

export const shutdownHandlers = {
  production: () => prodClient.end(),
  staging: () => stagingClient.end(),
  development: () => devClient.end(),
};

Environment Labels

The env property adds a visual label to each instance in the sidebar:

Value	Color
`production`	Red
`staging`	Yellow
`development`	Green
Custom	Default

Switching Instances

Use the instance picker dropdown in the sidebar to switch between instances. The current instance is persisted in your session.

Multiple Applications

You can also connect different applications using separate better-auth databases:

export default [
  {
    id: 'app-a-prod',
    name: 'App A',
    env: 'production',
    auth: appAAuth,
  },
  {
    id: 'app-b-prod',
    name: 'App B',
    env: 'production',
    auth: appBAuth,
  },
];

Version Compatibility

Each instance can run a different version of better-auth. The console auto-detects the version from the database schema and adjusts:

Column visibility in data tables
Available actions and features
API call parameters

The console works with better-auth v0.x and v1.x. Schema differences are handled automatically.

Conditional Instances

Only include instances that have valid database connections:

const instances = [
  process.env.PROD_DATABASE_URL && {
    id: 'production',
    name: 'Production',
    env: 'production',
    auth: productionAuth,
  },
  process.env.STAGING_DATABASE_URL && {
    id: 'staging',
    name: 'Staging',
    env: 'staging',
    auth: stagingAuth,
  },
].filter(Boolean);

export default instances;

This allows you to use the same config file across different environments.

Next Steps

Configuration - Full configuration reference
Dashboard - View instance analytics
Self-Host - Deploy with multiple instances