pgconsole.toml Reference

pgconsole uses a TOML configuration file for all settings. Pass the config file with the --config flag. Without --config, pgconsole starts in demo mode.

Docker
npx
npm

docker run -p 9876:9876 -v /path/to/pgconsole.toml:/etc/pgconsole.toml pgplex/pgconsole

npx @pgplex/pgconsole --config /path/to/pgconsole.toml

pgconsole --config /path/to/pgconsole.toml

Complete Example

pgconsole.toml

[general]
external_url = "https://pgconsole.example.com"

[general.banner]
text = "System maintenance scheduled for Sunday 2am UTC"
link = "https://status.example.com"
color = "#7c3aed"

[general.audit]
retention_days = 30

[branding]
logo = "https://example.com/your-logo.svg"
logo_link = "https://internal.example.com"

[[labels]]
id = "prod"
name = "Production"
color = "#ef4444"

[[labels]]
id = "staging"
name = "Staging"
color = "#f59e0b"

[[connections]]
id = "local"
name = "Local Dev"
host = "localhost"
port = 5432
database = "postgres"
username = "postgres"
password = "postgres"
ssl_mode = "prefer"

[[connections]]
id = "production"
name = "Production DB"
host = "db.example.com"
port = 5432
database = "app"
username = "readonly"
password = "secret"
ssl_mode = "verify-full"
ssl_ca = "/path/to/ca.crt"
ssl_cert = "/path/to/client.crt"
ssl_key = "/path/to/client.key"
labels = ["prod"]
lock_timeout = "5s"
statement_timeout = "30s"

[auth]
jwt_secret = "your-secret-key-at-least-32-characters-long"
signin_expiry = "7d"

[[auth.providers]]
type = "google"
client_id = "your-client-id"
client_secret = "your-client-secret"

[[auth.providers]]
type = "keycloak"
client_id = "pgconsole"
client_secret = "your-client-secret"
issuer_url = "https://keycloak.example.com/realms/your-realm"

[[auth.providers]]
type = "okta"
client_id = "0oaXXXXXXXXXXXXXX"
client_secret = "your-okta-client-secret"
issuer_url = "https://your-org.okta.com/oauth2/default"

[[users]]
email = "admin@example.com"
password = "your-password"
owner = true

[[users]]
email = "alice@example.com"

[[groups]]
id = "dev-team"
name = "Development Team"
members = ["admin@example.com", "alice@example.com"]

[[groups]]
id = "dba"
name = "Database Administrators"
members = ["admin@example.com"]

[[iam]]
connection = "*"
permissions = ["read"]
members = ["*"]

[[iam]]
connection = "local"
permissions = ["read", "write", "ddl", "admin"]
members = ["user:admin@example.com", "group:dba"]

[[ai.providers]]
id = "gpt4"
name = "GPT-4o"
vendor = "openai"
model = "gpt-4o"
api_key = "sk-..."

[[agents]]
id = "alice-claude"
token = "pgc_mcp_xxxxxxxxxxxxxxxx"
on_behalf_of = "alice@example.com"
permissions = ["read"]

General

Field	Description	Required
`external_url`	Public URL of the application. See Configure External Access.	Required for SSO

pgconsole.toml

[general]
external_url = "https://pgconsole.example.com"

Optional banner displayed at the top of the page. The banner cannot be dismissed by users.

Field	Description	Required
`text`	Banner message text	Yes
`link`	URL that makes the banner clickable (opens in new tab)
`color`	Hex color code for the banner background

pgconsole.toml

[general.banner]
text = "System maintenance scheduled for Sunday 2am UTC"
link = "https://status.example.com"
color = "#7c3aed"

Audit Log

Controls in-memory retention for the Audit Log page. Audit events are always emitted to stdout; this section only controls how long entries stay available in the running pgconsole process.

Field	Description	Required
`retention_days`	Positive integer number of days to keep audit entries in memory. When omitted, entries are retained indefinitely until server restart.

pgconsole.toml

[general.audit]
retention_days = 30

Branding

Replace the pgconsole logo with your own.

Field	Description	Required
`logo`	URL to your logo image	Yes
`logo_link`	Where the logo links to (absolute path or `http(s)` URL)

When logo_link is omitted, the logo links to /.

pgconsole.toml

[branding]
logo = "https://example.com/your-logo.svg"
logo_link = "https://internal.example.com"

Labels

Labels for tagging connections (e.g. Production, Staging). Referenced by the labels field in [[connections]]. Repeat for multiple labels.

Field	Description	Required
`id`	Unique identifier	Yes
`name`	Display name	Yes
`color`	Hex color code	Yes

pgconsole.toml

[[labels]]
id = "prod"
name = "Production"
color = "#ef4444"

Connections

Database connections. Repeat for multiple connections.

If connecting to a database on your host machine from Docker, use host.docker.internal instead of localhost.

Field	Description	Required	Default
`id`	Unique identifier	Yes
`name`	Display name	Yes
`host`	PostgreSQL host	Yes
`port`	PostgreSQL port		`5432`
`database`	Database name	Yes
`username`	Database user	Yes
`password`	Database password
`ssl_mode`	`disable`, `prefer`, `require`, or `verify-full`		`prefer`
`ssl_ca`	Path to CA certificate
`ssl_cert`	Path to client certificate
`ssl_key`	Path to client private key
`labels`	Array of label IDs		`[]`
`color`	Hex color (e.g. `#dc2626`) that tints the header to flag the environment (e.g. red for production)
`lock_timeout`	`lock_timeout`, e.g. `"5s"`		System default
`statement_timeout`	`statement_timeout`, e.g. `"30s"`		System default
`lazy`	Skip connection test on startup		`false`

pgconsole.toml

[[connections]]
id = "production"
name = "Production DB"
host = "db.example.com"
port = 5432
database = "app"
username = "readonly"
password = "secret"
ssl_mode = "verify-full"
ssl_ca = "/path/to/ca.crt"
ssl_cert = "/path/to/client.crt"
ssl_key = "/path/to/client.key"
labels = ["prod"]
color = "#dc2626"
lock_timeout = "5s"
statement_timeout = "30s"

Authentication

To run without authentication, omit the [auth] section entirely.

Field	Description	Required
`jwt_secret`	Secret key for JWT tokens (min 32 chars)	Yes
`signin_expiry`	Session duration (`h`/`d`/`w`)	Yes

pgconsole.toml

[auth]
jwt_secret = "your-secret-key-at-least-32-characters-long"
signin_expiry = "7d"

OAuth Providers

OAuth providers are configured as an array of [[auth.providers]] entries. Each entry requires a type field. Repeat for multiple providers.

Field	Description	Required
`type`	Provider type: `google`, `keycloak`, or `okta`	Yes
`client_id`	OAuth client ID	Yes
`client_secret`	OAuth client secret	Yes
`issuer_url`	Issuer URL (required for `keycloak` and `okta`)

pgconsole.toml

# Google
[[auth.providers]]
type = "google"
client_id = "your-client-id.apps.googleusercontent.com"
client_secret = "your-client-secret"

# Keycloak
[[auth.providers]]
type = "keycloak"
client_id = "pgconsole"
client_secret = "your-client-secret"
issuer_url = "https://keycloak.example.com/realms/your-realm"

# Okta
[[auth.providers]]
type = "okta"
client_id = "0oaXXXXXXXXXXXXXX"
client_secret = "your-okta-client-secret"
issuer_url = "https://your-org.okta.com/oauth2/default"

Users

User entries. Repeat for multiple users. Users with a password can sign in with basic auth. Users without a password are SSO-only.

Field	Description	Required
`email`	User email or identifier	Yes
`password`	Login password (omit for SSO-only users)
`owner`	Marks the user as an owner (shown with an Owner badge)

pgconsole.toml

[[users]]
email = "admin@example.com"
password = "your-password"
owner = true

[[users]]
email = "alice@example.com"
# SSO-only user - no password

Owner Role

Users with owner = true are marked with an Owner badge in the UI. If no user has owner = true, the first user entry automatically becomes the owner.

Groups

User groups for organizing users. Repeat for multiple groups.

Field	Description	Required
`id`	Unique identifier	Yes
`name`	Display name	Yes
`members`	Array of user emails	Yes

Members are user emails matching [[users]] entries.

pgconsole.toml

[[groups]]
id = "dev-team"
name = "Development Team"
members = ["admin@example.com", "alice@example.com"]

Access Control (IAM)

Rules for controlling access to connections. IAM is opt-in: with no [[iam]] rules defined, all authenticated users have full access, and enforcement begins once you define the first rule. See Database Access Control for a full guide on permissions, patterns, and examples.

Field	Description	Required
`connection`	Connection ID or `*` for all	Yes
`permissions`	Array: `read`, `write`, `ddl`, `admin`, `explain`, `execute`, `export`, or `*` for all	Yes
`members`	Array: `user:<email>`, `group:<id>`, or `*` for all users	Yes

pgconsole.toml

[[iam]]
connection = "*"
permissions = ["read"]
members = ["*"]

[[iam]]
connection = "production"
permissions = ["read", "write"]
members = ["user:admin@example.com", "group:dev-team"]

Validation

IAM rules are validated when the configuration is loaded:

connection must be * or reference a valid connection ID
permissions must only contain valid values: read, write, ddl, admin, explain, execute, export, or *
members must use valid formats: user:<email>, group:<id>, or *
group:<id> must reference a defined group

Invalid rules will cause the server to fail at startup with an error message.

AI Providers

Configure providers for the AI Assistant. Repeat for multiple providers.

Field	Description	Required
`id`	Unique identifier	Yes
`name`	Display name (defaults to `id`)
`vendor`	AI vendor: `openai`, `anthropic`, `google`, `openai-compatible`	Yes
`model`	Model identifier	Yes
`api_key`	API key for the vendor	Yes (optional for `openai-compatible`)
`base_url`	Base URL of an OpenAI-compatible API (e.g. `https://api.groq.com/openai/v1`)	Required for `openai-compatible`

Use vendor = "openai-compatible" with base_url for any provider that implements the OpenAI API (Groq, OpenRouter, Together, Ollama, vLLM, LiteLLM, and most self-hosted gateways). api_key may be omitted for local providers that run without authentication (e.g. Ollama, self-hosted vLLM).

pgconsole.toml

[[ai.providers]]
id = "gpt4"
name = "GPT-4o"
vendor = "openai"
model = "gpt-4o"
api_key = "sk-..."

[[ai.providers]]
id = "groq"
name = "Llama 3.3 70B"
vendor = "openai-compatible"
model = "llama-3.3-70b-versatile"
api_key = "gsk_..."
base_url = "https://api.groq.com/openai/v1"

Agents

Non-human principals that authenticate to the MCP Server with a bearer token. An agent is not a user — it can’t log into the UI. Repeat for multiple agents.

Field	Description	Required
`id`	Unique identifier, referenced in IAM rules as `agent:<id>`	Yes
`token`	Secret bearer token the agent sends as `Authorization: Bearer <token>` (globally unique)	Yes
`name`	Display name (defaults to `id`)
`on_behalf_of`	A `[[users]]` email. Its presence makes the agent delegated — see below
`permissions`	Cap intersected with the user’s grant; delegated agents only
`connections`	Connection IDs the agent may touch; delegated agents only

There are two kinds of agent:

Pure agent (no on_behalf_of) — a standalone service account, e.g. a CI bot. Authorize it with normal IAM rules whose members include agent:<id>. It is granted only what those rules say (*/group:/user: rules never apply to agents).
Delegated agent (on_behalf_of set) — acts on behalf of a user and inherits that user’s permissions, optionally narrowed by the permissions/connections caps. It can never exceed the user, and automatically loses access when the user does.

An agent only sees the MCP tools its effective permissions unlock — a read-only agent sees the discovery and query tools; write_data/run_ddl appear only with those permissions. Give each agent the narrowest grant it needs.

pgconsole.toml

# Pure agent — granted by an agent: IAM rule
[[agents]]
id = "migration-bot"
name = "Nightly Migration Bot"
token = "pgc_mcp_xxxxxxxxxxxxxxxx"

[[iam]]
connection = "staging"
permissions = ["read", "ddl"]
members = ["agent:migration-bot"]

# Delegated agent — bounded by alice, capped to read-only on prod
[[agents]]
id = "alice-claude"
name = "Alice's Claude Code"
token = "pgc_mcp_yyyyyyyyyyyyyyyy"
on_behalf_of = "alice@example.com"
permissions = ["read"]
connections = ["prod"]

Getting Started

Features

Authentication

Configuration

pgconsole.toml Reference

Complete Example

General

Announcement Banner

Audit Log

Branding

Labels

Connections

Authentication

OAuth Providers

Users

Owner Role

Groups

Access Control (IAM)

Validation

AI Providers

Agents

​Complete Example

​General

​Announcement Banner

​Audit Log

​Branding

​Labels

​Connections

​Authentication

​OAuth Providers

​Users

​Owner Role

​Groups

​Access Control (IAM)

​Validation

​AI Providers

​Agents

Complete Example

General

Announcement Banner

Audit Log

Branding

Labels

Connections

Authentication

OAuth Providers

Users

Owner Role

Groups

Access Control (IAM)

Validation

AI Providers

Agents