npx claudepluginhub intersystems-community/iris-devThis skill uses the workspace's default tool permissions.
**IRIS connection syntax is unique. Every other database pattern is wrong.**
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
IRIS connection syntax is unique. Every other database pattern is wrong.
intersystems-irispython → always import iris (both DBAPI and Native API) — NOT pyodbc, iris-python, intersystems_iriscursor.execute("SELECT MyProc(?)") — NOT cursor.callproc() or EXECjdbc:IRIS://host:1972/NAMESPACE — NOT jdbc:Cache:// (old Caché) or jdbc:intersystems:iris://com.intersystems.jdbc.IRISDriver — NOT com.intersystems.jdbc.CacheDriverLENGTH() fails with SQLCODE -37 on stream fields# Install: pip install intersystems-irispython
import iris.dbapi as iris_dbapi
conn = iris_dbapi.connect(
hostname="localhost",
port=1972, # superserver port — NOT 52773
namespace="USER",
username="_SYSTEM",
password="SYS"
)
cur = conn.cursor()
cur.execute("SELECT Name FROM Sample.Person WHERE Age > ?", [30])
rows = cur.fetchall()
# Stored procedures — use SELECT not CALL or EXEC:
cur.execute("SELECT MyPackage.MyProc(?, ?)", [arg1, arg2])
result = cur.fetchone()[0] # read BEFORE cur.close()!
import iris
conn = iris.connect(
hostname="localhost",
port=1972,
namespace="USER",
username="_SYSTEM",
password="SYS"
)
# Call a ClassMethod:
result = conn.classMethodValue("MyPackage.MyClass", "MyMethod", arg1, arg2)
# Read/write globals:
gref = conn.createGlobal("MyGlobal")
gref.set("value", "subscript1", "subscript2")
// Correct driver JAR: intersystems-jdbc-3.x.x.jar
// Maven: com.intersystems:intersystems-jdbc:3.8.4
String url = "jdbc:IRIS://localhost:1972/USER"; // uppercase IRIS, port 1972
Properties props = new Properties();
props.setProperty("user", "_SYSTEM");
props.setProperty("password", "SYS");
Connection conn = DriverManager.getConnection(url, props);
// Driver class: com.intersystems.jdbc.IRISDriver
// WRONG — legacy Caché driver (deprecated):
// "jdbc:Cache://localhost:1972/USER"
// "jdbc:intersystems:iris://localhost:1972/USER"
| Port | Protocol | Use for |
|---|---|---|
| 1972 | SuperServer (TCP) | DBAPI, JDBC, ODBC, Native API |
| 52773 | HTTP/WebSocket | REST, Atelier, MCP, IRIS web apps |
| 1972 | pgwire | PostgreSQL wire protocol (if enabled) |
Docker:
docker port <container> 1972/tcpfor DBAPI port,docker port <container> 52773/tcpfor web port. These are different.
# pgwire (psycopg2) + IRIS: TEXT/LONGVARCHAR columns are %Stream objects
# WRONG — will return garbled binary or error:
cur.execute("SELECT description FROM MyTable")
desc = cur.fetchone()[0] # might be stream object, not string
length = len(desc) # SQLCODE -37: function not supported on stream
# CORRECT — cast to VARCHAR in the query:
cur.execute("SELECT CAST(description AS VARCHAR(4000)) FROM MyTable")
desc = cur.fetchone()[0] # now a real Python string
| Task | Use |
|---|---|
| SQL queries from Python | iris.dbapi |
| ObjectScript ClassMethods from Python | iris Native API |
| Java/JVM applications | JDBC (jdbc:IRIS://) |
| AI agent tools (Claude, GPT) | IRIS MCP (%AI.MCP.Service) |
| REST APIs | IRIS Web Gateway port 52773 |
| Legacy Caché apps (migrate) | Update from jdbc:Cache:// → jdbc:IRIS:// |
When using iris-devtester (PyPI: pip install iris-devtester) for spinning up IRIS test containers:
# Start container — with exact port or auto-assign
idt container up --port 11972 # maps 1972→11972
idt container up --auto-port # auto-assigns free port from 1972-2000
# Password change required? (common on fresh community containers)
idt test-connection --auto-fix # detects "Unexpected error: 1", auto-remediates
idt container reset-password <name> --timeout 10 # manual with timeout
# Run ObjectScript from CLI
idt container exec <name> --objectscript "Write \$ZVERSION"
idt container exec <name> --namespace MYAPP --objectscript "Do MyMethod()"
# Check connectivity (shows host, port, namespace, masked password)
idt test-connection --container <name>
idt test-connection -v # verbose: shows full password
Python API:
from iris_devtester import IRISContainer
with IRISContainer.community() as iris:
conn = iris.get_connection() # CallIn + password reset auto-handled
cur = conn.cursor()
cur.execute("SELECT $ZVERSION")
print(cur.fetchone()[0])
# Specific port:
with IRISContainer.community().with_name("mydb") as iris:
pass # port auto-mapped, use iris.get_exposed_port(1972)
# Get credentials:
password = iris.get_password() # public accessor (v1.15.0+)
username = iris.get_username()