Postgres Plugin for Steampipe

Use SQL to query data from plain PostgreSQL databases.

This repo contains a Steampipe plugin that exposes PostgreSQL database views as queryable Steampipe tables with production-ready performance optimizations. Features N+1 query elimination, intelligent connection pooling, and multi-level caching for enterprise-scale deployments.

See below for an example that mixes data from a static DB (contact information for the teams that own Kubernetes namespaces) and data from Kubernetes (which namespaces have Failed pods). This may be part of an automated alerting system that runs periodically and sends emails.

🚀 Production-Ready Performance Features

• ⚡ Optimized Query Engine: Eliminates N+1 query problems with single JOIN operations
• 🔗 Connection Pooling: Prevents database connection exhaustion with configurable pool settings
• 📦 Multi-Level Caching: Intelligent caching of views, queries, and schema metadata
• 📊 Performance Monitoring: Built-in query timing and connection pool metrics
• 🛡️ Production Hardened: Handles high query volumes without overwhelming your database
• 🏗️ Cross-Platform Builds: Enhanced Makefile with support for Linux, macOS, Windows across multiple architectures
• 📦 Enterprise Distribution: Automated packaging and Nexus OSS integration for streamlined deployments

This plugin provides always up-to-date results by querying your PostgreSQL database directly, with enterprise-grade performance optimizations that prevent connection exhaustion and eliminate common N+1 query performance issues.

• Community: Join #steampipe on Slack →
• Get involved: Issues

Quick start

Download and install the latest Postgres plugin:

steampipe plugin install tektite-io/postgres

Installing the latest Postgres plugin will create a config file (~/.steampipe/config/postgres.spc) with a single connection named postgres:

connection "postgres" {
  plugin = "tektite-io/postgres"

  # A connection string (https://pkg.go.dev/github.com/jackc/pgx/v5#hdr-Establishing_a_Connection), in the form that is 
  # expected by the pgx package. Required. 
  # Can also be set with the `DATABASE_URL` environment variable.
  # connection_string = "postgres://username:password@localhost:5432/database_name"

  # The remote DB's schema that this plugin will expose. If you leave this unset, it'll default to `public`.
  # schema = "public"

  # OPTIONAL: List of view patterns to expose as Steampipe tables.
  # This plugin exposes PostgreSQL VIEWS (not tables) as queryable Steampipe tables.
  # If not specified, exposes ALL views in the schema (default behavior).
  # Wildcard based searches are supported.
  # For example:
  #  - "*" will expose every view in the remote DB
  #  - "aws_*" will expose views whose names start with "aws_"
  #  - "user_accounts" will only expose the specific view "user_accounts"
  # You can have several items (for example, ["aws_*", "billing_*"] will expose 
  # all the views that start with "aws_", PLUS the views that start with "billing_")
  # Defaults to all views
  # views_to_expose = ["*"]
}

Alternatively, you can also use the following environment variable to obtain credentials only if the other argument (connection_string) is not specified in the connection:

export DATABASE_URL=postgres://username:password@localhost:5432/database_name

Run Steampipe:

steampipe query

Run a query for whatever table the Postgres DB has:

select
  attr1,
  attr2
from
  postgres.some_table;

This plugin forwards all conditions that are supported by Steampipe to the remote DB. For example, a WHERE col=1 condition will be forwarded, so the remote DB can optimize its searches. More complex operators (such as JSONB operations) can't be forwarded and will thus result in a full table scan on the remote DB. In this case, the filtering will be applied by Steampipe.

Developing

Prerequisites:

• Steampipe
• Golang

Clone:

git clone https://github.com/tektite-io/steampipe-plugin-postgres.git
cd steampipe-plugin-postgres

Build, which automatically installs the new version to your ~/.steampipe/plugins directory:

make build

Or use the enhanced cross-compilation features:

# Build for your current platform
make build

# Cross-compile for different platforms
make build-linux-amd64     # Build for Linux servers
make build-darwin-arm64    # Build for Apple Silicon Macs
make build-windows-amd64   # Build for Windows
make build-all             # Build for all supported platforms

# Custom platform targeting
make build TARGET_OS=linux TARGET_ARCH=arm64

Configure the plugin:

cp config/* ~/.steampipe/config
vi ~/.steampipe/config/postgres.spc

Try it!

steampipe query
> .inspect postgres

Further reading:

• Writing plugins
• Writing your first table

🏗️ Build System & Deployment

This plugin includes a comprehensive, production-ready Makefile with cross-compilation support for easy deployment across different platforms.

Cross-Platform Building

The Makefile automatically detects your platform and supports building for multiple target platforms:

Supported Platforms:

• linux/amd64 - Intel/AMD 64-bit Linux (most common server deployment)
• linux/arm64 - ARM 64-bit Linux (AWS Graviton, cloud ARM instances)
• darwin/amd64 - Intel-based macOS
• darwin/arm64 - Apple Silicon macOS (M1, M2, M3)
• windows/amd64 - 64-bit Windows

Build Commands:

# Quick platform builds
make build-linux          # Linux amd64 (default)
make build-darwin          # macOS arm64 (Apple Silicon)
make build-windows         # Windows amd64

# Specific platform builds
make build-linux-amd64     # Traditional Linux servers
make build-linux-arm64     # ARM-based cloud instances
make build-darwin-amd64    # Intel Macs
make build-darwin-arm64    # Apple Silicon Macs
make build-windows-amd64   # Windows deployment

# Build everything
make build-all             # All supported platforms

Packaging & Distribution

Create distributable packages for deployment:

# Package for specific platforms
make package-linux-amd64   # Creates steampipe-plugin-postgres-1.0.0-linux-amd64.tar.gz
make package-darwin-arm64  # Creates steampipe-plugin-postgres-1.0.0-darwin-arm64.tar.gz
make package-all           # Package for all platforms

# Custom platform packaging
make package TARGET_OS=linux TARGET_ARCH=arm64

Each package includes:

• Pre-compiled plugin binary
• Configuration template (postgres.spc)
• Documentation (README, CHANGELOG, docs/)
• Installation instructions

Artifact Management

Upload to Nexus OSS with platform-organized paths:

# Set credentials
export NEXUS_USERNAME=your_username
export NEXUS_PASSWORD=your_password

# Upload current platform package
make upload

# Upload specific platform (cross-compile + package + upload)
make package TARGET_OS=linux TARGET_ARCH=amd64
make upload TARGET_OS=linux TARGET_ARCH=amd64
# This uploads to: .../postgres/1.0.0/linux/amd64/steampipe-plugin-postgres.tar.gz

Nexus Organization:

/steampipe/steampipe-plugins/postgres/
├── 1.0.0/
│   ├── linux/
│   │   ├── amd64/steampipe-plugin-postgres.tar.gz
│   │   └── arm64/steampipe-plugin-postgres.tar.gz
│   ├── darwin/
│   │   ├── amd64/steampipe-plugin-postgres.tar.gz
│   │   └── arm64/steampipe-plugin-postgres.tar.gz
│   └── windows/
│       └── amd64/steampipe-plugin-postgres.tar.gz

Development Workflow

# See all available targets
make help

# Development build with verbose output
make dev

# Install locally (creates version.json and versions.json)
make install

# Test the built plugin
make test

# Clean build artifacts
make clean

# View current platform configuration
make help  # Shows HOST_OS, HOST_ARCH, TARGET_OS, TARGET_ARCH

Cross-Development Example

Develop on macOS, deploy to Linux servers:

# 1. Develop and test locally on macOS
make build
make install
steampipe query "select count(*) from postgres.information_schema.tables"

# 2. Build for Linux deployment  
make build-linux-amd64

# 3. Package for distribution
make package-linux-amd64

# 4. Upload to artifact repository
make upload TARGET_OS=linux TARGET_ARCH=amd64
# Uploads to: .../postgres/1.0.0/linux/amd64/steampipe-plugin-postgres.tar.gz

Contributing

Please see the contribution guidelines and our code of conduct. All contributions are subject to the Apache 2.0 open source license.

help wanted issues:

• Steampipe
• Postgres Plugin