---
id: pgspecial
version: "2.2.1"
license: BSD
license_treatment: permissive
maintenance: aging
---

# pgspecial — Meta-commands handler for Postgres Database.

License: permissive · Maintenance: aging · Downloads: 650.5K/mo

## What it is and what it does

pgspecial is a Python library that wraps PostgreSQL's meta-commands—the backslash commands you'd normally type in psql—into a callable API. It lets you execute commands programmatically against a live database connection, returning structured results you can process in code.

The library is designed for tools that need to expose PostgreSQL introspection and administration commands without reimplementing them. It depends on click, sqlparse, and psycopg for the database connection itself. You instantiate PGSpecial, pass it a cursor and a command string, and iterate over the results. It also supports loading named queries from config files via the NamedQueries class.

Use it for:

- Building a PostgreSQL REPL or interactive shell that supports backslash commands.
- Adding database introspection to a Jupyter notebook or IPython environment.
- Implementing a web-based database management tool that needs to expose PostgreSQL admin commands.
- Automating database inspection tasks in scripts without reimplementing meta-command logic.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Executes PostgreSQL meta-commands (backslash commands) programmatically through a Python API, enabling applications to run special commands on a database connection.

Yes, if you need to execute PostgreSQL meta-commands programmatically. The library is stable, has low install friction, carries a permissive license, and is actively used by established projects. The 473-day release gap is a minor concern for a mature, narrow-scope package, but verify compatibility with your PostgreSQL and psycopg versions before production use.

## Install

pip install pgspecial
uv add pgspecial
poetry add pgspecial

## Installing pgspecial

Before you install: Low friction installation with three lightweight runtime dependencies. Maintenance status is aging—last release was 473 days ago—but the package remains in use by established projects.

License in practice: BSD permissive license allows use in commercial and proprietary projects with minimal restrictions, requiring only license attribution.

Quickstart:

pip install pgspecial

from pgspecial.main import PGSpecial

pgspecial = PGSpecial()
for result in pgspecial.execute(cur, sql):
    print(result)

Requires Python >=3.9 and an active psycopg database connection.

Verify before relying:

- Whether the 473-day gap since last release reflects stable maturity or abandonment risk for future PostgreSQL compatibility.
- Current state of the repository (archived status, recent commits) to assess ongoing maintenance.
- Compatibility with current versions of psycopg and PostgreSQL.

## Package facts

- License: BSD (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 650.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

postgres meta-commands, postgresql backslash commands, postgres special commands api, pgspecial postgres, database introspection, postgres repl commands, postgres-cli, database-introspection

[View on SkillFed](https://skillfed.io/packages/pgspecial) · [View on PyPI](https://pypi.org/project/pgspecial/)