Skip to content

DATABASE.md

Latest commit

 

History

History
160 lines (105 loc) · 4.4 KB

DATABASE.md

File metadata and controls

160 lines (105 loc) · 4.4 KB

Database

GitMesh Agents uses PostgreSQL via Drizzle ORM. There are three ways to run the database, from simplest to most production-ready.

1. Embedded PostgreSQL — zero config

If you don't set DATABASE_URL, the server automatically starts an embedded PostgreSQL instance and manages a local data directory.

pnpm dev

That's it. On first start the server:

  1. Creates a ~/.gitmesh-agents/instances/default/db/ directory for storage
  2. Ensures the gitmesh-agents database exists
  3. Runs migrations automatically for empty databases
  4. Starts serving requests

Data persists across restarts in ~/.gitmesh-agents/instances/default/db/. To reset local dev data, delete that directory.

This mode is ideal for local development and one-command installs.

Docker note: the Docker quickstart image also uses embedded PostgreSQL by default. Persist /gitmesh-agents to keep DB state across container restarts (see doc/DOCKER.md).

2. Local PostgreSQL (Docker)

For a full PostgreSQL server locally, use the included Docker Compose setup:

docker compose up -d

This starts PostgreSQL 17 on localhost:5432. Then set the connection string:

cp .env.example .env
# .env already contains:
# DATABASE_URL=postgres://gitmesh:gitmesh@localhost:5433/gitmesh

Run migrations (once the migration generation issue is fixed) or use drizzle-kit push:

DATABASE_URL=postgres://gitmesh:gitmesh@localhost:5433/gitmesh \
  npx drizzle-kit push

Start the server:

pnpm dev

3. Hosted PostgreSQL (Supabase)

For production, use a hosted PostgreSQL provider. Supabase is a good option with a free tier.

Setup

  1. Create a project at database.new
  2. Go to Project Settings > Database > Connection string
  3. Copy the URI and replace the password placeholder with your database password

Connection string

Supabase offers two connection modes:

Direct connection (port 5432) — use for migrations and one-off scripts:

postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres

Connection pooling via Supavisor (port 6543) — use for the application:

postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres

Configure

Set DATABASE_URL in your .env:

DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres

If using connection pooling (port 6543), the postgres client must disable prepared statements. Update lib/data/src/client.ts:

export function createDb(url: string) {
  const sql = postgres(url, { prepare: false });
  return drizzlePg(sql, { schema });
}

Push the schema

# Use the direct connection (port 5432) for schema changes
DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@...5432/postgres \
  npx drizzle-kit push

Free tier limits

  • 500 MB database storage
  • 200 concurrent connections
  • Projects pause after 1 week of inactivity

See Supabase pricing for current details.

Switching between modes

The database mode is controlled by DATABASE_URL:

DATABASE_URL Mode
Not set Embedded PostgreSQL (~/.gitmesh-agents/instances/default/db/)
postgres://...localhost... Local Docker PostgreSQL
postgres://...supabase.com... Hosted Supabase

Your Drizzle schema (lib/data/src/schema/) stays the same regardless of mode.

Secret storage

GitMesh Agents stores secret metadata and versions in:

  • project_secrets
  • project_secret_versions

For local/default installs, the active provider is local_encrypted:

  • Secret material is encrypted at rest with a local master key.
  • Default key file: ~/.gitmesh-agents/instances/default/secrets/master.key (auto-created if missing).
  • CLI config location: ~/.gitmesh-agents/instances/default/config.json under secrets.localEncrypted.keyFilePath.

Optional overrides:

  • GITMESH_SECRETS_MASTER_KEY (32-byte key as base64, hex, or raw 32-char string)
  • GITMESH_SECRETS_MASTER_KEY_FILE (custom key file path)

Strict mode to block new inline sensitive env values:

GITMESH_SECRETS_STRICT_MODE=true

You can set strict mode and provider defaults via:

pnpm gitmesh-agents configure --section secrets

Inline secret migration command:

pnpm secrets:migrate-inline-env --apply