Skip to main content

PostgreSQL Tools in Cursor - Quick Reference

Last Updated: 2025-10-26

Installed Extensions​

Primary Database Tools​

  1. SQLTools (mtxr.sqltools)

    • Multi-database SQL client
    • IntelliSense and autocomplete
    • Query history and bookmarks
    • Export to CSV/JSON

  2. SQLTools PostgreSQL Driver (mtxr.sqltools-driver-pg)

    • Native PostgreSQL support
    • Connection pooling
    • Transaction support

  3. PostgreSQL Explorer (ckolkman.vscode-postgres)

    • Database tree view in sidebar
    • Schema browser
    • Table data preview
    • JSONB field pretty-printing

  4. Database Client (cweijan.vscode-database-client2)

    • Universal database manager
    • ERD diagram generation
    • Import/export utilities
    • SSH tunnel support

  5. pgFormatter (bradymholt.pgformatter)

    • Auto-format SQL files
    • Consistent code style
    • Format on save enabled

Pre-configured Connections​

Two connections are configured in .vscode/settings.json:

1. TVL Local (postgres) - Admin Access​

  • User: postgres
  • Password: postgres
  • Use for: Schema management, migrations, admin tasks
  • Auto-connects: Opens automatically when Cursor starts

2. TVL Local (tvl_user) - Application Access​

  • User: tvl_user
  • Password: tvl_password
  • Use for: Testing RLS policies, simulating app queries

Quick Start​

1. Open SQLTools Panel​

Cmd/Ctrl + Shift + P → SQLTools: Focus on SQLTools View

Or click the database icon in the Activity Bar (left sidebar).

2. Run a Query​

Method A: SQL File

  1. Create/open a .sql file
  2. Write your query
  3. Right-click → Run on Active Connection
  4. Or use shortcut: Cmd/Ctrl + E, E

Method B: SQLTools Scratchpad

  1. Open SQLTools panel
  2. Click "New SQL File" icon
  3. Select connection: TVL Local (postgres)
  4. Write and run query

Method C: PostgreSQL Explorer

  1. Open PostgreSQL Explorer in sidebar
  2. Browse to a table
  3. Right-click → New Query
  4. Query editor opens pre-filled

3. Browse Database Schema​

SQLTools:

  • Expand connection → tvl_dev → public → Tables
  • Right-click table → Show Table Records (preview data)
  • Right-click table → Describe Table (show schema)

PostgreSQL Explorer:

  • Expand connection → Schemas → public → Tables
  • Click table name to see columns
  • Click "Play" icon next to table to query

Common Tasks​

View All Tables​

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

Check RLS Policies​

SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE schemaname = 'public'
ORDER BY tablename, policyname;

Test RLS as tvl_user​

  1. Switch to TVL Local (tvl_user) connection
  2. Run query with tenant context:
-- Set tenant context (simulates application login)
SELECT set_config('app.current_org_id', '123e4567-e89b-12d3-a456-426614174000', false);
SELECT set_config('app.current_account_id', '123e4567-e89b-12d3-a456-426614174001', false);

-- Now query will respect RLS
SELECT * FROM properties;

View Query Execution Plan​

EXPLAIN ANALYZE
SELECT p.*
FROM properties p
INNER JOIN accounts a ON p.account_id = a.id
WHERE p.org_id = '123e4567-e89b-12d3-a456-426614174000';

Export Query Results​

  1. Run your query
  2. In results panel, click Export icon
  3. Choose format: CSV, JSON, or SQL INSERT

Format SQL File​

Auto-format on save: Already enabled Manual format:

  • Right-click in SQL file → Format Document
  • Or: Cmd/Ctrl + Shift + F

View Table Data​

SQLTools:

  1. Right-click table → Show Table Records
  2. Results appear in panel (default: 50 rows)

PostgreSQL Explorer:

  1. Click table name
  2. Click "Show Data" button

Generate ERD (Entity Relationship Diagram)​

Database Client Extension:

  1. Open Database Client panel
  2. Connect to TVL Local (postgres)
  3. Right-click database → Generate ERD
  4. Interactive diagram shows all relationships

Keyboard Shortcuts​

ActionShortcut
Run SQL queryCmd/Ctrl + E, E
Run selected SQLCmd/Ctrl + E, E (with selection)
Format SQL documentCmd/Ctrl + Shift + F
Open SQLToolsCmd/Ctrl + Shift + P → "SQLTools"
New SQL fileCmd/Ctrl + N → Save as .sql

Tips & Tricks​

1. Query Snippets​

Create reusable SQL snippets in SQLTools:

  1. Write query in scratchpad
  2. Click bookmark icon
  3. Name your snippet
  4. Access from "Bookmarks" tab

2. Multiple Connections​

Switch between postgres and tvl_user to test:

  • Admin operations (create tables, migrations)
  • User-level access (RLS policy enforcement)

3. Transaction Support​

BEGIN;
  INSERT INTO properties (org_id, account_id, name) VALUES (...);
  -- Test the insert
  SELECT * FROM properties WHERE name = 'Test Property';
ROLLBACK; -- or COMMIT;

4. Connection Pooling​

SQLTools maintains persistent connections:

  • Faster query execution
  • No repeated authentication
  • Configurable timeout (30s in settings)

5. IntelliSense​

As you type SQL:

  • Table names autocomplete
  • Column names suggested after SELECT
  • Function signatures shown
  • PostgreSQL keywords highlighted

Alternative Tools​

Command Line (psql)​

# From terminal in Cursor
pnpm psql:connect

# Or directly
docker exec -it the-villa-life-postgres-1 psql -U postgres -d tvl_dev

pgAdmin (Web UI)​

Open in browser: http://localhost:5050

Best for:

  • Visual query builder
  • Performance tuning (EXPLAIN ANALYZE visualizations)
  • Backup/restore operations

Supabase CLI​

# Check local instance
supabase status

# View functions
supabase functions list

# Test RLS policies
supabase test db

Troubleshooting​

Connection Refused​

Issue: connect ECONNREFUSED 127.0.0.1:5432

Fix:

  1. Ensure PostgreSQL container is running: 
    docker ps | grep postgres
  2. Check health: 
    pnpm psql:debug
  3. Restart if needed: 
    docker-compose -f .devcontainer/docker-compose.yml restart postgres

Authentication Failed​

Issue: password authentication failed for user "tvl_user"

Fix:

  1. Verify credentials in .devcontainer/docker-compose.yml
  2. Check if user exists: 
    -- Connect as postgres
    SELECT usename FROM pg_user WHERE usename = 'tvl_user';
  3. Re-run init script if needed: 
    pnpm db:reset

Query Timeout​

Issue: Query runs forever

Fix:

  1. Kill query in PostgreSQL: 
    SELECT pg_cancel_backend(pid)
    FROM pg_stat_activity
    WHERE state = 'active' AND pid <> pg_backend_pid();
  2. Increase timeout in settings (currently 30s)

Extension Not Working​

Issue: Extension features not showing

Fix:

  1. Reload Cursor window: 
    Cmd/Ctrl + Shift + P → Developer: Reload Window
  2. Check extension is enabled: 
    Cmd/Ctrl + Shift + X → Search for extension
  3. Reinstall extension if needed

Configuration Files​

.vscode/extensions.json​

Recommended extensions for the team. Cursor prompts to install on first open.

.vscode/settings.json​

  • SQLTools connections (postgres + tvl_user)
  • pgFormatter settings (2 spaces, comma breaks)
  • File associations (*.sql → postgres syntax)
  • Auto-format on save for SQL files

References​

Questions? Check the database troubleshooting guide: /docs/guides/database-troubleshooting.md