# How to Configure PostgreSQL Push Sync for Team Dashboards in agentsview

> Learn how to configure PostgreSQL push sync for team dashboards in agentsview. Easily sync local SQLite data to PostgreSQL and serve it via an HTTP API for your dashboards.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-06-12

---

**To configure PostgreSQL push sync for team dashboards in agentsview, define the connection parameters in [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 58-66), the configuration supports TLS control, schema naming, and project filtering:

```go
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:

```toml
[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`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 98-106) expands environment variables with precedence over file values. Set these variables for containerized or CI environments:

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg.go) (lines 32-38) handles initialization and watermark tracking:

```bash

# 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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_watch.go) (lines 42-68) handles debouncing:

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg.go) (lines 162-188) initializes a `postgres.Store` in read-only mode and passes it to `server.New`:

```bash
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`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg.go) (lines 41-60) validates mutual exclusivity between these lists:

```toml
[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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (configuration), [`internal/postgres/push.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/push.go) (sync logic), and [`cmd/agentsview/pg.go`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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.