Audit Log

pgconsole emits audit logs as JSON lines to stdout, allowing you to capture and process them with your existing log infrastructure.

Events

Event	Description
`auth.login`	User login attempt (success or failure)
`auth.logout`	User logout
`sql.execute`	SQL query execution
`data.export`	Data exported (e.g., CSV download)

Log Format

All audit events are JSON objects with a common structure:

{
  "type": "audit",
  "ts": "2024-01-15T10:30:45.123Z",
  "action": "...",
  "actor": "alice@example.com"
}

Common Fields

Field	Description
`type`	Always `"audit"`
`ts`	ISO 8601 timestamp
`action`	Event type
`actor`	Username or email

{
  "type": "audit",
  "ts": "2024-01-15T10:30:45.123Z",
  "action": "auth.login",
  "actor": "alice@example.com",
  "provider": "google",
  "ip": "192.168.1.100",
  "success": true
}

Field	Description
`provider`	Auth provider (`basic`, `google`, `keycloak`)
`ip`	Client IP address
`success`	Whether login succeeded
`error`	Error message (if failed)

auth.logout

{
  "type": "audit",
  "ts": "2024-01-15T10:35:00.000Z",
  "action": "auth.logout",
  "actor": "alice@example.com"
}

sql.execute

{
  "type": "audit",
  "ts": "2024-01-15T10:32:15.456Z",
  "action": "sql.execute",
  "actor": "alice@example.com",
  "connection": "prod-db",
  "database": "postgres",
  "sql": "SELECT * FROM users WHERE active = true",
  "success": true,
  "duration_ms": 45,
  "row_count": 150
}

Field	Description
`connection`	Connection ID
`database`	Database name
`sql`	Full SQL query text
`success`	Whether query succeeded
`duration_ms`	Execution time in milliseconds
`row_count`	Number of rows returned (optional)
`error`	Error message (if failed)
`source`	`"mcp"` when the query came from the MCP Server (omitted otherwise)
`tool`	MCP tool name that ran the query (only when `source` is `"mcp"`)
`agent`	The agent id that ran the query (only when `source` is `"mcp"`). For a delegated agent the `actor` is the user it acts for; for a pure agent the `actor` is `agent:<id>`

data.export

{
  "type": "audit",
  "ts": "2024-01-15T10:33:00.000Z",
  "action": "data.export",
  "actor": "alice@example.com",
  "connection": "prod-db",
  "database": "postgres",
  "sql": "SELECT * FROM users WHERE active = true",
  "row_count": 150,
  "format": "csv"
}

Field	Description
`connection`	Connection ID
`database`	Database name
`sql`	SQL query that produced the exported data
`row_count`	Number of rows exported
`format`	Export format (`csv`)

Capturing Logs

Audit logs are written to stdout alongside other server output. Filter by "type":"audit" to capture audit events only:

# Filter and write to file
# --line-buffered: flush output after each line for real-time logging
pgconsole | grep --line-buffered '"type":"audit"' >> audit.log

# Parse and forward to log aggregator
# --unbuffered: disable jq's output buffering for real-time streaming
pgconsole | jq --unbuffered -c 'select(.type == "audit")' | nc logserver 5000

Getting Started

Features

Authentication

Configuration

Events

Log Format

Common Fields

auth.logout

sql.execute

data.export

Capturing Logs

​Events

​Log Format

​Common Fields

​auth.login

​auth.logout

​sql.execute

​data.export

​Capturing Logs

Events

Log Format

Common Fields

auth.login

auth.logout

sql.execute

data.export

Capturing Logs