Skip to content
Skills Library
Programming · Tool integration

iris-pgwire

/iris-pgwire

Use when connecting to IRIS via the PostgreSQL wire protocol, using psycopg3 or any Postgres-compatible client

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when connecting to IRIS via the PostgreSQL wire protocol, using psycopg3 or any Postgres-compatible client

Original author description

Use when connecting to IRIS via the PostgreSQL wire protocol, using psycopg3 or any Postgres-compatible client

How it works

  1. What it does
  2. When to use this vs the alternatives
  3. Install
  4. Connection string
  5. psycopg3 usage pattern
  6. Key gotchas
  7. Reference
Original SKILL.md headings · 172 lines, 612 words
SKILL.md preview
---
name: iris-pgwire
tier: extra
description: Use when connecting to IRIS via the PostgreSQL wire protocol, using psycopg3 or any Postgres-compatible client
managed_by: "iris-agentic-dev"
---

# iris-pgwire

**Project**: [iris-pgwire](https://github.com/intersystems-community/iris-pgwire)
**Status**: community preview
**Requires**: IRIS 2024.1+; `iris-pgwire` package installed via ZPM

## What it does

`iris-pgwire` exposes IRIS SQL over the PostgreSQL wire protocol. Any
`psycopg3`, `psycopg2`, `asyncpg`, or JDBC/Postgres-compatible client can
connect to IRIS without the `intersystems-irispython` package.

Useful when:

- You're deploying to an environment where the IRIS Python gateway isn't
  available (AWS Lambda, Docker minimal images, etc.)
- You want to use standard Postgres tooling (`psql`, `pgAdmin`, `dbt`)
- Your library requires a Postgres connection and you can't swap drivers

## When to use this vs the alternatives

| Scenario                               | Preferred driver                          |
| -------------------------------------- | ----------------------------------------- |
| Python inside IRIS (Embedded Python)   | `iris` native module                      |
| Python outside IRIS, full IRIS API     | `intersystems-irispython`                 |
| Python outside IRIS, SQL only, no deps | **iris-pgwire + psycopg3**                |
| Java / Spring                          | JDBC (`com.intersystems.jdbc.IRISDriver`) |
| Standard Postgres tooling              | **iris-pgwire**                           |

See the [iris-connectivity skill](../iris-connectivity/SKILL.md) for the full
connection-options table.

## Install

```bash
# On the IRIS instance
zpm "install iris-pgwire"
```

The package starts a listener on port 5432 (configurable via CPF). No IRIS
restart required.

## Connection string

```text
postgresql://username:password@host:5432/NAMESPACE
```

The database name in the connection string maps to the IRIS namespace
(case-insensitive, uppercased internally).

```python
import psycopg

conn = psycopg.connect(
    "postgresql://_SYSTEM:SYS@localhost:5432/USER"
)
```

Or with keyword arguments:

```python
conn = psycopg.connect(
    host="localhost",
    port=5432,
    dbname="USER",        # IRIS namespace
    user="_SYSTEM",
    password="SYS",
)
```

## psycopg3 usage pattern

```python
import psycopg

with psycopg.connect("postgresql://_SYSTEM:SYS@localhost:5432/USER") as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT Name, DOB FROM Sample.Person WHERE Age > %s", (30,))
        rows = cur.fetchall()
        for name, dob in rows:
            print(name, dob)
```

Async variant:

```python
import psycopg

async with await psycopg.AsyncConnection.connect(
    "postgresql://_SYSTEM:SYS@localhost:5432/USER"
) as conn:
    async with conn.cursor() as cur:
        await cur.execute("SELECT Name FROM Sample.Person")
        rows = await cur.fetchall()
```

## Key gotchas

### Parameter style: `%s` only

iris-pgwire speaks the PostgreSQL extended query protocol. Use `%s`
placeholders, not `?` (ODBC style) or `:name` (named style).

```python
# Correct
cur.execute("SELECT * FROM Foo WHERE ID = %s", (42,))

# Wrong — do not use
cur.execute("SELECT * FROM Foo WHERE ID = ?", (42,))
```

### Type mapping

| IRIS type     | Python type returned                  |
| ------------- | ------------------------------------- |
| `%String`     | `str`                                 |
| `%Integer`    | `int`                                 |
| `%Double`     | `float`                               |
| `%Date`       | `datetime.date`                       |
| `%TimeStamp`  | `datetime.datetime`                   |
| `%Boolean`    | `bool`                                |
| `%List`       | `str` (encoded form)                  |
| Stream / clob | `str` (truncated at 64 KB by default) |

IRIS `%List` returns the internal `$LISTBUILD` encoding, not a Python list.
Use `iris_list_to_python()` helper from `intersystems-irispython` if you need
decoded list values, or store lists as JSON strings.

### Transaction semantics

iris-pgwire exposes IRIS SQL transactions via the standard Postgres
autocommit/explicit-transaction model:

- **autocommit off** (psycopg3 default): each statement runs inside a
  transaction; call `conn.commit()` or `conn.rollback()` explicitly.
- **autocommit on**: each statement commits immediately (matches IRIS default
  SQL behavior).

IRIS does not support `SAVEPOINT` — nested transactions will error. Use flat
transactions only.

```python
conn.autocommit = False
try:
    cur.execute("INSERT INTO MyTable (Name) VALUES (%s)", ("Alice",))
    conn.commit()
except Exception:
    conn.rollback()
    raise
```

### Namespace isolation

Each psycopg3 connection is bound to one namespace (the `dbname` in the
connection string). To query multiple namespaces, open separate connections.
`SET SCHEMA` is not supported.

### DDL support

DDL (`CREATE TABLE`, `ALTER TABLE`, `DROP`) is available if the connected user
has `%DB_<namespace>:Write` privilege. DDL runs outside IRIS class compilation
— changes are visible immediately in SQL but not as compiled classes.

## Reference

- [iris-connectivity skill](../iris-connectivity/SKILL.md) — full connection
  options table (JDBC, ODBC, irispython DBAPI, native API)
- [iris-pgwire repo](https://github.com/intersystems-community/iris-pgwire)
- [psycopg3 docs](https://www.psycopg.org/psycopg3/docs/)

Versions

The database has no other skills named iris-pgwire.

Database snapshot: 13.11.2026 · package version 534a82bb79fb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100iris-connectivity
    Use when connecting to IRIS from Python, Java, JDBC, ODBC, or any external language. IRIS connection APIs have specific package names, port numbers, and syntax that differ from every other database.
  • 100iris-embedded-python
    Use when the user wants to run Python code inside IRIS, call Python libraries from ObjectScript, or use the IRIS Python native API
  • 100add-redis-iris
    Add Redis Iris to an existing AI agent in any framework (LangGraph, LangChain, OpenAI Agents SDK, Google ADK, Pydantic AI, CrewAI, or a plain loop). Use when the user asks to add Iris, Redis Agent Memory, Agent Playbooks, Context Gateway, Intent Router, or Lens to their agent,…
  • 100iris-ecs
    Designs, writes, debugs, and tests applications built on iris-ecs, the Entity Component System for TypeScript. Use when code imports iris-ecs, or when the user plans or changes an Iris ECS feature: choosing its domain, modeling data with defineComponent and Type schemas, tags,…
  • 100iris-development
    Iris is Redis's umbrella for AI-focused products. Use this skill when integrating with the Iris Redis Agent Memory (RAM) data plane on Redis Cloud — recording session events for an AI agent, creating or searching long-term memories, configuring a memory store, or tuning…
  • 100azure-postgres-ts
    |" Connect to Azure Database for PostgreSQL Flexible Server from Node.js/TypeScript using the pg (node-postgres) package. Use for PostgreSQL queries, connection pooling, transactions, and Microsoft Entra ID (passwordless) authentication. Triggers: "PostgreSQL", "postgres", "pg…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.