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

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

npx

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

npm

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"

[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 = "[e-mail]"
password = "your-password"
owner = true

[[users]]
email = "[e-mail]"

[[groups]]
id = "dev-team"
name = "Development Team"
members = ["[e-mail]", "[e-mail]"]

[[groups]]
id = "dba"
name = "Database Administrators"
members = ["[e-mail]"]

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

[[iam]]
connection = "local"
permissions = ["read", "write", "ddl", "admin"]
members = ["user:[e-mail]", "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 = "[e-mail]"
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"

Announcement Banner

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"

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 = "[e-mail]"
password = "your-password"
owner = true

[[users]]
email = "[e-mail]"
# 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 = ["[e-mail]", "[e-mail]"]

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:[e-mail]", "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 = "[e-mail]"
permissions = ["read"]
connections = ["prod"]