How to Configure PostgreSQL Push Sync for Team Dashboards in agentsview

To configure PostgreSQL push sync for team dashboards in agentsview, define the connection parameters in config.toml or via AGENTSVIEW_PG_* environment variables, run agentsview pg push to synchronize local SQLite data to PostgreSQL, and deploy agentsview pg serve to expose a read-only HTTP API for dashboard clients.

The agentsview repository enables teams to replicate local session archives from SQLite to a shared PostgreSQL schema, allowing multiple users and CI dashboards to query centralized observability data. This configuration eliminates direct filesystem dependencies by transforming the tool into a distributed, read-only data service. The implementation spans three core phases: connection configuration, data push synchronization, and read-only API serving.

Configure PostgreSQL Connection Settings

The connection logic resides in internal/config/config.go, where the PGConfig struct defines all available parameters for the replication target.

The PGConfig Struct

According to the source code at internal/config/config.go (lines 58-66), the configuration supports TLS control, schema naming, and project filtering:

type PGConfig struct {
    URL             string   `toml:"url" json:"url"`
    Schema          string   `toml:"schema" json:"schema"`
    MachineName     string   `toml:"machine_name" json:"machine_name"`
    AllowInsecure   bool     `toml:"allow_insecure" json:"allow_insecure"`
    Projects        []string `toml:"projects" json:"projects,omitempty"`
    ExcludeProjects []string `toml:"exclude_projects" json:"exclude_projects,omitempty"`
}

File-Based Configuration (TOML)

Create or edit ~/.agentsview/config.toml to specify the database endpoint and authentication credentials:

[pg]
url            = "postgres://av_user:secret@pg.example.com:5432/agentsdb"
schema         = "agentsview"
machine_name   = "team-dashboard-01"
allow_insecure = false

# Optional filtering: include only specific projects

projects = ["my-app", "another-service"]

Environment Variable Overrides

The Config.LoadEnv routine in internal/config/config.go (lines 98-106) expands environment variables with precedence over file values. Set these variables for containerized or CI environments:

export AGENTSVIEW_PG_URL="postgres://av_user:secret@pg.example.com:5432/agentsdb"
export AGENTSVIEW_PG_SCHEMA="agentsview"
export AGENTSVIEW_PG_MACHINE="team-dashboard-01"
export AGENTSVIEW_PG_PROJECTS="frontend,backend"

Synchronize Data with Push Commands

The push logic in internal/postgres/push.go implements the Sync.Push method, which iterates over local sessions, compares fingerprints, and issues batched INSERT/UPDATE statements to PostgreSQL.

One-Off Full Push

Execute agentsview pg push to perform a manual synchronization. The runPGPush function in cmd/agentsview/pg.go (lines 32-38) handles initialization and watermark tracking:

# Force a complete resync, clearing the local watermark

agentsview pg push --full

• The --full flag resets the last_push_at watermark, forcing every session to be re-evaluated and sent.
• This command is essential after initial database provisioning or schema migrations.

Continuous Watch Mode

For real-time dashboards, use agentsview pg watch to run a background loop that triggers Sync.Push after file-system events and on regular intervals. The pgPusher implementation in cmd/agentsview/pg_watch.go (lines 42-68) handles debouncing:

agentsview pg watch \
    --debounce=10s \
    --interval=5m

• The --debounce parameter prevents excessive pushes during rapid file changes.
• The --interval parameter ensures periodic synchronization even when the filesystem is idle.

Expose a Read-Only Dashboard API

Team dashboards typically consume the HTTP API rather than raw SQL. The runPGServe function in cmd/agentsview/pg.go (lines 162-188) initializes a postgres.Store in read-only mode and passes it to server.New:

agentsview pg serve \
    --host=0.0.0.0 \
    --port=8080 \
    --public-url=https://dashboard.example.com

Dashboard clients can now query standard endpoints such as /api/v1/sessions and /api/v1/search against the shared PostgreSQL backend, receiving the same JSON responses as the local SQLite instance but from a centralized data store.

Scope Sync to Specific Projects

To prevent noise in team dashboards, filter the replication scope using the projects or exclude_projects fields. The resolvePushProjects helper in cmd/agentsview/pg.go (lines 41-60) validates mutual exclusivity between these lists:

[pg]
url      = "postgres://user:pass@host:5432/db"
projects = ["frontend", "backend"]

When the push executes, only sessions whose project column matches the whitelist are inserted into the PostgreSQL schema, keeping the dashboard focused on relevant domains.

End-to-End Deployment Steps

Follow this sequence to deploy a production-ready team dashboard:

1. Initialize the PostgreSQL schema by running agentsview pg push --full once to populate the remote database with existing SQLite archives.
2. Enable continuous sync by running agentsview pg watch --debounce=30s --interval=10m as a systemd or launchd service (service files are auto-generated via cmd/agentsview/pg_service.go).
3. Start the read-only API with agentsview pg serve --host=0.0.0.0 --port=8080 to expose the HTTP interface.
4. Configure dashboard clients to point at https://dashboard.example.com/api/v1/sessions instead of local SQLite paths.

Summary

• Configuration: Define PostgreSQL connection parameters via PGConfig in config.toml or AGENTSVIEW_PG_* environment variables.
• Push Sync: Use agentsview pg push for one-off replication or agentsview pg watch for continuous, debounced synchronization.
• Read-Only Serving: Deploy agentsview pg serve to expose a centralized HTTP API backed by PostgreSQL.
• Project Filtering: Limit data scope using projects or exclude_projects to keep team dashboards relevant.
• Key Files: internal/config/config.go (configuration), internal/postgres/push.go (sync logic), and cmd/agentsview/pg.go (CLI commands).

Frequently Asked Questions

How do I force a complete resync of all sessions to PostgreSQL?

Run the command agentsview pg push --full. This clears the local last_push_at watermark and forces the Sync.Push method in internal/postgres/push.go to re-evaluate and re-send every session, which is useful after schema changes or data corruption.

Can I use environment variables instead of a config.toml file?

Yes. The Config.LoadEnv function in internal/config/config.go expands variables like AGENTSVIEW_PG_URL, AGENTSVIEW_PG_SCHEMA, and AGENTSVIEW_PG_MACHINE, merging them with file settings and giving precedence to environment values for containerized deployments.

What is the difference between pg push and pg watch?

agentsview pg push performs a single, immediate synchronization and exits, while agentsview pg watch runs a daemon that monitors the local filesystem for changes and pushes updates based on debounce timers and fixed intervals, suitable for long-running production dashboards.

How does project filtering work in PostgreSQL push sync?

The projects and exclude_projects fields in the PGConfig struct allow whitelist or blacklist filtering. The resolvePushProjects function in cmd/agentsview/pg.go validates that these lists are mutually exclusive, and only sessions matching the filter criteria are inserted into the remote PostgreSQL schema.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}