Download Postggresively

# Postggresively v1.0.0

**August 23, 2026**

The first stable release of Postggresively: a self-hosted web console for controlling relational databases through a friendly browser interface.

## What's New

### Authentication System
- **Dedicated credentials database**: Console now manages its own accounts separate from your database. Credentials are stored securely in a `postggresively` database with bcrypt-hashed passwords.
- **Passkey (WebAuthn) support**: Sign in with biometric or hardware passkeys for enhanced security and convenience. Password login remains available as a fallback.
- **Step-up authentication**: Destructive actions (dropping databases, terminating activities) require re-authentication within a secure 5-minute window.
- **Automatic first-run setup**: Zero-account installs redirect to an account creation wizard.
- **Legacy migration**: Existing accounts from earlier schema designs are automatically migrated to the new system.

### Multi-Database Support
Connect to any relational database by connection string—no longer limited to the local Postgres instance.

| Database | Driver | Features |
|----------|--------|----------|
| PostgreSQL (local/remote) | pgx | Full feature set including row editor |
| MySQL / MariaDB | go-sql-driver/mysql | Browse and query |
| SQLite | modernc.org/sqlite | Browse and query |
| SQL Server | go-mssqldb | Browse and query |

- **New Connections page**: Manage saved connections with engine selection, connection testing, and quick switching from a sidebar menu.
- **Encrypted storage**: Connection strings are encrypted with AES-256-GCM; only redacted versions are shown to the browser.
- **API expansion**: Browse any saved connection alongside the local instance via `?conn=<id>` query parameter.

### Deployment Options
Choose the deployment method that fits your infrastructure:

- **Development**: `scripts/dev.sh` for local development with automatic `.env` setup
- **Systemd**: User-level systemd units—no root access required
- **PM2 Release Bundle**: Static binaries for six platforms (Linux amd64/arm64/armv7, macOS amd64/arm64, Windows amd64). Pre-built for Raspberry Pi support.
- **Docker Compose**: Complete stack with Postgres, agent, backend, and web service with multi-architecture image support

All production paths use the same shared build logic for consistent behavior.

## Getting Started

### From Scratch
Choose your deployment method:
- [Local development](./scripts/dev.sh)
- [Systemd installation](./scripts/deploy.sh)
- [PM2 setup](./docker/release-bundle/)
- [Docker Compose](./docker/docker-compose.yml)

### Upgrading
If you're upgrading from earlier versions:
1. Back up your `postggresively` database
2. Back up any saved connection strings (they'll be encrypted differently after rotation)
3. Pull the latest version and rebuild/restart according to your deployment method

## Known Issues/Limitations

**Authentication**
- Session JWTs (12h expiry) aren't revocable; password changes don't immediately invalidate existing tokens
- Single account only in this release—multi-user and role support coming later
- Passkeys require HTTPS (or localhost) with `PG_WEBAUTHN_RPID` matching your domain
- Multi-process deployments need sticky routing for passkey challenge ceremonies

**Connections**
- Row editing, database creation/drop, activity monitoring, and agent pages remain PostgreSQL-only
- Rotating `PG_SECRET_KEY` invalidates saved connections; they must be re-added
- Saved connections are shared across all accounts—no per-connection permissions yet
- MySQL and SQL Server support verified by tests only; not yet tested against live production instances

**Deployment**
- Backend URL changes require rebuilding, not just restarting
- Docker Compose lacks health-check based readiness; slow-starting agents may cause initial race conditions

## Requirements

- Node.js 18+ (for web frontend)
- Go 1.21+ (for agent and backend)
- PostgreSQL 12+ (for console database) on the same server or accessible via network
- Secure context (HTTPS) recommended for passkey authentication in production

## Environment Variables

Key configuration options:
- `PG_DATABASE_URL`: Connection to your Postgres instance
- `PG_META_DATABASE`: Name of console database (default: `postggresively`)
- `PG_WEBAUTHN_RPID`: Domain for passkey authentication
- `PG_SECRET_KEY`: Encryption key for saved connection strings
- `PG_JWT_SECRET`: JWT signing key
- `PG_CORS_ORIGIN`: CORS origin for web requests

See the example `.env` files in the repository for complete configuration details.

## Reporting Issues

Found a bug? Please open an issue on GitHub with:
- Your deployment method (systemd, PM2, Docker, etc.)
- PostgreSQL version
- Steps to reproduce
- Error messages or logs

## Changelog

This is the inaugural stable release. For a complete technical reference on the implementation of authentication, connections, and deployment, see the design documentation in the project.

---

**Thank you for using Postggresively!** We'd love your feedback. Star us on GitHub if you find this useful.

**Full Changelog**: https://github.com/workvar/postgressively/commits/v1.0.0