/wrds

name: wrds
description: Connect to and query WRDS (Wharton Research Data Services) from any research project. Use this skill whenever the user needs to download, query, or explore data from WRDS — including Compustat, CRSP, FactSet, I/B/E/S, or any other WRDS-hosted database. Also trigger when the user mentions WRDS tables, WRDS libraries, or wants to look up variable definitions or coverage in WRDS datasets. Do NOT trigger for general SQL or database questions unrelated to WRDS.

WRDS (Wharton Research Data Services)

Reusable patterns for connecting to WRDS and querying its databases from Python.

Prerequisites

1. Install the client library:

   pip install wrds

2. Credentials live in a libpq `.pgpass` file with the line format:

   wrds-pgdata.wharton.upenn.edu:9737:wrds:your_wrds_username:PASSWORD

Point the environment variable `PGPASSFILE` at that file, or place it at the OS-default libpq location (`%APPDATA%\postgresql\pgpass.conf` on Windows, `~/.pgpass` elsewhere). Set `$WRDS_USERNAME` (or `$PGUSER`) to your account.

3. **Never hardcode passwords** in scripts, CLAUDE.md, or any version-controlled file. The `.pgpass` mechanism handles authentication automatically.

Authentication: fail fast, never retry

WRDS locks an account after a few consecutive failed logins, and unlocking it requires a request to WRDS support. The `wrds` package makes this easy to trigger by accident. `wrds.Connection()` authenticates through the `.pgpass` file, and when that file is missing or its password has expired, the package silently falls back to an interactive `input()`/`getpass()` prompt and then retries. In an unattended agent session the prompt has no human to answer it, so the run either hangs on stdin or the attempt fails and gets repeated, where each repeat is another failed login against the account.

To prevent that, **always connect through the bundled guard `scripts/wrds_connect.py`, and never call `wrds.Connection()` directly.** The guard validates `.pgpass` offline before touching the network, suppresses the interactive prompt, makes at most one connection attempt, and on any authentication problem raises `WRDSAuthError` carrying an explanatory message rather than prompting or retrying.

When a connection raises `WRDSAuthError`, stop. Surface the message to the user and wait for them to refresh the credentials. Do not re-run the script, do not call `wrds.Connection()` as a fallback, and do not enter a password, because every retry moves the account closer to a lockout. Recovery is the user's to perform: they update the password in the file `PGPASSFILE` points to, whose single line has the form `wrds-pgdata.wharton.upenn.edu:9737:wrds:your_wrds_username:PASSWORD`.

An offline credential check, which costs zero login attempts, is worth running before a batch of WRDS work:

python ~/.claude/skills/wrds/scripts/wrds_connect.py --check

Connection Pattern

import os
import sys
sys.path.insert(0, os.path.expanduser("~/.claude/skills/wrds/scripts"))
from wrds_connect import connect, WRDSAuthError

try:
    db = connect()                 # one guarded attempt; account from $WRDS_USERNAME/$PGUSER
except WRDSAuthError as e:
    print(e)                       # STOP — surface to the user, do not retry
    raise
try:
    df = db.raw_sql("SELECT * FROM comp.funda LIMIT 10")
finally:
    db.close()

`connect()` resolves the account and the credentials file at call time, so a different login needs no code change. The account is taken from `username=`, then `$WRDS_USERNAME`, then `$PGUSER` — with none of those set the guard raises `WRDSAuthError` instead of guessing an account; the credentials file is taken from `pgpass=`, then `$PGPASSFILE`, then the OS-default libpq location. A file named explicitly, by the argument or `$PGPASSFILE`, is authoritative, so a missing path fails fast rather than silently falling back to the default account. When a password is supplied through `password=` or `$WRDS_PASSWORD`, `connect()` authenticates with the username and that password directly and the `.pgpass` file is bypassed. The function returns the ordinary `wrds.Connection` object that the rest of this skill documents.

To work as another account or against another credentials file, set the variables in the shell before invoking any WRDS script — no edit to the skill or your analysis code is required:

$env:WRDS_USERNAME = "alice"
$env:PGPASSFILE    = "D:\creds\alice.pgpass"
python "$env:USERPROFILE\.claude\skills\wrds\scripts\wrds_connect.py" --check

Using credentials supplied in chat

By default the account comes from `$WRDS_USERNAME`/`$PGUSER` with the `.pgpass` file, and a bare request such as "use the wrds skill" should use that environment unchanged. When the user instead supplies a userid and password in the request — for example, "use the wrds skill with userid `jdoe` and password `…`" — authenticate as that account for the session by passing the credentials through the environment, scoped to the command that runs the WRDS work. Shell state does not persist between separate commands here, so setting the variables inline in the same invocation keeps the password out of any file and confined to that one run:

$env:WRDS_USERNAME = "jdoe"; $env:WRDS_PASSWORD = "<the password the user gave>"; python your_wrds_script.py

A username on its own, with no password, is looked up in the `.pgpass` file as usual; a supplied password switches `connect()` to direct authentication and the `.pgpass` file is bypassed. The fail-fast contract is unchanged: a wrong password counts as one failed login, and WRDS locks the account after a few, so when `connect()` raises `WRDSAuthError` here, stop and ask the user to confirm the userid and password instead of retrying. Never write the password into a script or any other file, and do not echo it back.

Schema-peek helper

Before writing a real query against an u