A comprehensive PostgreSQL database management extension featuring interactive SQL notebooks, real-time monitoring dashboard, and advanced database operationsβall within VS Code.
π Quick Start β’ π Documentation β’ π€ Contributing β’ π¬ Support
|
|
|
|
Monitor connections, queries, and performance metrics in real-time
Manage multiple database connections with an intuitive interface
π Click to expand/collapse
|
Secure & Flexible Connections
|
{
"name": "Production DB",
"host": "db.example.com",
"port": 5432,
"username": "admin",
"database": "myapp"
} |
Note
The dashboard provides live metrics updated in real-time without manual refresh.
π Live Metrics & Monitoring (click to expand)
| Metric | Description | Actions |
|---|---|---|
| π Active Connections | Real-time connection count | View connection details |
| πΎ Database Size | Current storage usage (MB/GB) | Track growth trends |
| β‘ Active Queries | Running query count | Cancel/Kill queries |
| π― Cache Hit Ratio | Cache performance percentage | Optimize performance |
Performance Graphs:
- π Connection trends over time
- π Query activity patterns
- πΎ Memory usage monitoring
Active Query Management:
- β View all running queries with execution time
- β Cancel long-running queries safely
- π Terminate stuck connections
- π Query execution statistics
|
Hierarchical Navigation |
Supported Objects
|
π― Notebook Features (click to expand)
Create & Execute Queries
-- Cell 1: Data Analysis
SELECT
date_trunc('day', created_at) as day,
COUNT(*) as user_count
FROM users
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY day
ORDER BY day;
-- Cell 2: Performance Check
EXPLAIN ANALYZE
SELECT * FROM orders
WHERE customer_id = 123;Key Features:
- β Multi-cell execution
- β¨οΈ
Ctrl+Enterto run cell - π€ AI-Powered Assistance: GitHub Copilot & agentic support
- π Rich tabular output
- π¨ Syntax highlighting
- πΎ Export to CSV/Excel
- π Row count & execution time
- π Result sorting by column
[!TIP] AI-Powered SQL Development: The notebook interface fully supports GitHub Copilot and other agentic AI tools, providing intelligent code completion, query suggestions, and automated SQL generation directly in your notebooks!
π Table Operations
Data Management
- β View data with pagination
- β Insert new rows
- βοΈ Update existing data
- ποΈ Delete rows
- π§Ή Truncate table
- β Drop table
Structure Management
- π View table properties (columns, constraints, indexes)
- βοΈ Edit table definition
- π Show column details with data types
- π View foreign key relationships
Script Generation
-- Quick script generation
SELECT * FROM employees; -- SELECT
INSERT INTO employees (...) VALUES (...); -- INSERT
UPDATE employees SET ... WHERE ...; -- UPDATE
DELETE FROM employees WHERE ...; -- DELETE
CREATE TABLE employees (...); -- CREATEMaintenance Tools
- π§Ή VACUUM: Clean up dead rows and reclaim space
- π ANALYZE: Update table statistics for query planner
- π REINDEX: Rebuild indexes for optimal performance
ποΈ View Operations
Regular Views
- π View definition display
- βοΈ Edit view SQL
- π Query view data
- β Drop view
Materialized Views
- π Refresh cached data
- π View current data
- βοΈ Edit definition
- β Drop materialized view
βοΈ Function Management
- π View function properties (signature, parameters, return type)
- βοΈ Edit definition (CREATE OR REPLACE)
βΆοΈ Call function with parameters- π View source code
- β Drop function
Example Function Creation:
CREATE OR REPLACE FUNCTION calculate_total(
item_price DECIMAL,
quantity INTEGER
)
RETURNS DECIMAL AS $$
BEGIN
RETURN item_price * quantity;
END;
$$ LANGUAGE plpgsql;π Schema Operations
Schema Management
- π View schema properties
- β Create objects within schema
- π Generate schema scripts
- π§ Schema-level operations
Quick Object Creation
| Object Type | Shortcut |
|---|---|
| π Table | Right-click β Create Table |
| ποΈ View | Right-click β Create View |
| π Materialized View | Right-click β Create Materialized View |
| βοΈ Function | Right-click β Create Function |
| π·οΈ Type | Right-click β Create Type |
| π Foreign Table | Right-click β Create Foreign Table |
|
Option 1: VS Code Marketplace
|
Option 2: Command Line # Install from VSIX
code --install-extension postgres-explorer-*.vsix
# Or using the extension ID
ext install ric-v.postgres-explorer |
Tip
Test your connection using psql before adding it to the extension.
Step-by-Step Setup:
-
Open Extension
- Click the PostgreSQL icon in Activity Bar
- Or press
Ctrl+Shift+PβPostgreSQL: Add Connection
-
Enter Connection Details
Connection Name: My Local Database Host: localhost Port: 5432 Username: postgres Password: β’β’β’β’β’β’β’β’ Database: myapp_dev -
Save & Connect
- Click Save to store credentials securely
- Connection appears in explorer
- Click to connect and start exploring
Warning
Passwords are encrypted and stored securely using VS Code's SecretStorage API.
|
Tree Navigation
|
Keyboard Shortcuts
|
π Viewing Table Data
- Right-click table β View Table Data
- Data opens in new tab with pagination
- Click column headers to sort
- Use export buttons for CSV/Excel
Pro Tip: Double-click table for quick data view
βοΈ Editing Table Structure
- Right-click table β Show Table Properties
- Review columns, constraints, indexes
- Select Edit Table Definition to modify
- Make changes in SQL editor
- Execute to apply
Example Modification:
ALTER TABLE employees
ADD COLUMN department VARCHAR(100),
ADD COLUMN hire_date DATE DEFAULT CURRENT_DATE;π Generating Scripts
Right-click table β Scripts β Choose type:
| Script Type | Use Case |
|---|---|
| π SELECT | Query template with all columns |
| β INSERT | Insert template with column list |
| βοΈ UPDATE | Update template with WHERE clause |
| ποΈ DELETE | Delete template with conditions |
| ποΈ CREATE | Full table definition script |
Note
Notebooks support multiple cells for organizing complex queries.
1. Create Notebook
Right-click database/schema/table β New PostgreSQL Notebook
2. Write Queries
-- Cell 1: Setup
CREATE TEMP TABLE report_data AS
SELECT * FROM sales WHERE date >= '2024-01-01';
-- Cell 2: Analysis
SELECT
product_category,
SUM(amount) as total_sales,
COUNT(*) as order_count
FROM report_data
GROUP BY product_category
ORDER BY total_sales DESC;
-- Cell 3: Cleanup
DROP TABLE report_data;3. Execute & Export
- Press
Ctrl+Enteron each cell - Review results inline
- Export to CSV/Excel as needed
4. AI-Powered Assistance π€
Note
The notebook interface seamlessly integrates with GitHub Copilot and other agentic AI tools for intelligent SQL assistance.
New in v0.2.3: Enhanced AI Integration
- β¨ "Ask AI" CodeLens: Click the link directly above any SQL query to get instant help.
- π Inline Toolbar Button: Access AI assistance from the cell toolbar.
- π§ Multiple Providers: Support for Google Gemini, OpenAI, Anthropic, and GitHub Copilot.
- β‘ Pre-defined Tasks: Quickly Explain, Fix, Optimize, or Format your queries.
Copilot Features Available:
- π‘ Intelligent Code Completion: Auto-complete SQL queries as you type
- π Context-Aware Suggestions: Get relevant table/column suggestions
- β¨ Query Generation: Describe what you want in comments, let AI write the SQL
- π Error Detection: Real-time syntax and logical error detection
- π Query Optimization: Suggestions for improving query performance
- π¬ Natural Language to SQL: Convert plain English to SQL queries
Example AI-Assisted Workflow:
- Click "β¨ Ask AI" above your query.
- Select a task (e.g., "Optimize Query") or type a custom instruction.
- Watch as the AI transforms your SQL in real-time!
-- Cell 1: Ask AI to generate a query
-- Create a query to find top 10 customers by total purchase amount in the last month
-- Copilot generates:
SELECT
c.customer_id,
c.name,
SUM(o.amount) as total_spent
FROM customers c
JOIN orders o ON c.id = o.customer_id
WHERE o.created_at >= NOW() - INTERVAL '30 days'
GROUP BY c.customer_id, c.name
ORDER BY total_spent DESC
LIMIT 10;Agentic AI Support:
- π― Multi-step query planning and execution
- π Automated refactoring and optimization
- π Data analysis suggestions
- π§ͺ Test data generation
Right-click database β Show Database Dashboard
Dashboard Components:
| Section | Information | Actions |
|---|---|---|
| π Metrics Panel | Connections, Size, Queries, Cache | Real-time updates |
| π Performance Graphs | Trends over time | Visual analysis |
| π Active Queries | Running queries with details | Cancel/Kill |
Managing Active Queries:
Caution
Killing queries will terminate the client connection immediately.
- View query details (SQL, duration, client)
- Cancel - Sends cancellation request (graceful)
- Kill - Terminates connection (forceful)
- Confirm action in dialog
π― Tutorial 1: Creating a Complete Database Schema
Goal: Create a blog database with tables, views, and functions
Step 1: Create Tables
-- Users table
CREATE TABLE users (
id SERIAL PRIMARY KEY,
username VARCHAR(50) UNIQUE NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);
-- Posts table
CREATE TABLE posts (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
title VARCHAR(200) NOT NULL,
content TEXT,
published_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW()
);
-- Comments table
CREATE TABLE comments (
id SERIAL PRIMARY KEY,
post_id INTEGER REFERENCES posts(id) ON DELETE CASCADE,
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
content TEXT NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);Step 2: Create View
CREATE VIEW recent_posts AS
SELECT
p.id,
p.title,
u.username as author,
p.published_at,
COUNT(c.id) as comment_count
FROM posts p
JOIN users u ON p.user_id = u.id
LEFT JOIN comments c ON p.post_id = c.id
WHERE p.published_at IS NOT NULL
GROUP BY p.id, p.title, u.username, p.published_at
ORDER BY p.published_at DESC;Step 3: Create Function
CREATE OR REPLACE FUNCTION get_user_post_count(user_id_param INTEGER)
RETURNS INTEGER AS $$
BEGIN
RETURN (
SELECT COUNT(*)
FROM posts
WHERE user_id = user_id_param
AND published_at IS NOT NULL
);
END;
$$ LANGUAGE plpgsql;Step 4: Use the Extension
- Refresh schema in explorer
- View table data
- Query the view
- Call the function with test data
π― Tutorial 2: Database Maintenance Routine
Goal: Optimize database performance
1. Check Table Bloat
SELECT
schemaname,
tablename,
pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;2. Vacuum Large Tables
- Right-click large table β Maintenance β VACUUM
- Choose VACUUM FULL for maximum space reclamation
3. Update Statistics
- Right-click table β Maintenance β ANALYZE
- Improves query planning
4. Rebuild Indexes
- Right-click table β Maintenance β REINDEX
- Fixes index bloat and fragmentation
5. Monitor Results
- View dashboard for cache hit ratio improvement
- Check query performance
π― Tutorial 3: Data Migration Workflow
Goal: Export data from one database and import to another
1. Export Source Data
-- In source database notebook
SELECT * FROM users WHERE active = true;- Execute query
- Export to CSV
2. Backup Source Database
- Right-click database β Backup
- Choose location and format
- Save backup file
3. Create Target Schema
- Connect to target database
- Run CREATE TABLE scripts
4. Import Data
-- Use COPY command or insert from CSV
COPY users FROM '/path/to/users.csv'
WITH (FORMAT csv, HEADER true);5. Verify Migration
SELECT COUNT(*) FROM users;
SELECT * FROM users LIMIT 10;|
π Report Bugs Found a bug? Help us fix it!
|
π‘ Suggest Features Have an idea? We'd love to hear it!
|
π§ Submit Code Ready to code? Here's how!
|
π» Code Style
- β Follow TypeScript best practices
- β Use meaningful variable/function names
- β Add comments for complex logic
- β Keep functions small and focused
- β Use async/await for async operations
π§ͺ Testing
- β Test changes thoroughly
- β Include test cases for new features
- β Ensure existing tests pass
- β Test with different PostgreSQL versions
- β Test edge cases
π Documentation
- β Update README for new features
- β Add JSDoc comments to functions
- β Update CHANGELOG.md
- β Include usage examples
- β Document breaking changes
We follow Conventional Commits:
feat: add materialized view refresh functionality
fix: resolve connection timeout issue
docs: update installation instructions
refactor: simplify query execution logic
test: add tests for table operations
chore: update dependenciesTypes:
feat: New featurefix: Bug fixdocs: Documentation onlystyle: Code style changesrefactor: Code refactoringperf: Performance improvementstest: Adding/updating testschore: Maintenance tasks
| Tool | Version | Purpose |
|---|---|---|
| Node.js | β₯ 18.0.0 | Runtime environment |
| npm | β₯ 8.0.0 | Package manager |
| VS Code | β₯ 1.80.0 | Development IDE |
| PostgreSQL | Any | Testing database |
| Git | Latest | Version control |
Step-by-Step Setup
1. Clone Repository
git clone https://github.com/dev-asterix/yape-postgres-ext-vsc.git
cd yape-postgres-ext-vsc2. Install Dependencies
npm install3. Compile TypeScript
# One-time compilation
npm run compile
# Watch mode (auto-recompile)
npm run watch4. Open in VS Code
code .5. Run Extension
- Press
F5to launch Extension Development Host - Or use Run and Debug panel (
Ctrl+Shift+D) - Select "Run Extension" configuration
- Click green play button
βΆοΈ
6. Debug Extension
- Set breakpoints in
.tsfiles - Press
F5to start debugging - Use Debug Console for inspection
- Step through code with toolbar
yape-postgres-ext-vsc/
β
βββ π src/ # Source code
β βββ π extension.ts # Extension entry point
β βββ π commands/ # Command implementations
β β βββ tables.ts # Table operations
β β βββ views.ts # View operations
β β βββ functions.ts # Function operations
β β βββ ...
β βββ π services/ # Business logic
β β βββ ConnectionManager.ts # Connection handling
β β βββ QueryExecutor.ts # Query execution
β β βββ ...
β βββ π providers/ # VS Code providers
β β βββ TreeDataProvider.ts # Tree view
β β βββ NotebookProvider.ts # Notebook support
β β βββ ...
β βββ π views/ # Webview panels
β β βββ dashboard/ # Dashboard UI
β β βββ connection/ # Connection UI
β β βββ ...
β βββ π utils/ # Utility functions
β
βββ π resources/ # Static resources
β βββ π screenshots/ # Documentation images
β βββ π icons/ # Extension icons
β βββ ...
β
βββ π out/ # Compiled JavaScript
βββ π dist/ # Bundled extension
β
βββ π package.json # Extension manifest
βββ π tsconfig.json # TypeScript configuration
βββ π README.md # This file
βββ π CHANGELOG.md # Version history
| Command | Description |
|---|---|
npm install |
Install dependencies |
npm run compile |
Compile TypeScript once |
npm run watch |
Watch mode (auto-compile) |
npm run vscode:prepublish |
Build for production |
vsce package |
Create VSIX package |
vsce publish |
Publish to marketplace |
π³ Docker PostgreSQL for Testing
Quick Start:
docker run --name postgres-test \
-e POSTGRES_PASSWORD=test123 \
-e POSTGRES_DB=testdb \
-p 5432:5432 \
-d postgres:latestCreate Test Data:
CREATE TABLE test_users (
id SERIAL PRIMARY KEY,
username VARCHAR(50) NOT NULL,
email VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);
INSERT INTO test_users (username, email)
SELECT
'user' || generate_series,
'user' || generate_series || '@example.com'
FROM generate_series(1, 100);Cleanup:
docker stop postgres-test
docker rm postgres-testExtension Logging
- Open Output panel:
Ctrl+Shift+U - Select "PostgreSQL Explorer" from dropdown
- View real-time extension logs
- Look for errors and warnings
Developer Tools
In Extension Development Host:
- Press
Ctrl+Shift+Ito open DevTools - Check Console tab for errors
- Use Network tab for requests
- Inspect Elements tab for UI issues
Webview Debugging
- Right-click in webview panel
- Select "Inspect"
- Use Chrome DevTools
- Debug HTML/CSS/JavaScript
TypeScript Compilation Errors
# Clear compiled output
rm -rf out/
# Reinstall dependencies
rm -rf node_modules/ package-lock.json
npm install
# Recompile
npm run compileExtension Not Loading
Check:
- β package.json syntax is valid
- β Activation events are correct
- β Extension host output for errors
- β All dependencies are installed
Solutions:
- Reload window:
Ctrl+R - Restart VS Code
- Check Extension Host logs
β οΈ Cannot connect to database
Symptoms:
- Connection timeout
- Authentication failed
- Server not found
Solutions:
-
Verify Connection Details
# Test with psql psql -h localhost -p 5432 -U postgres -d mydb -
Check PostgreSQL Status
# Linux sudo service postgresql status sudo service postgresql start # MacOS brew services list brew services start postgresql # Windows # Check Services β PostgreSQL
-
Verify pg_hba.conf
- Allow connections from your client IP
- Check authentication method
- Reload PostgreSQL after changes
-
Firewall Settings
# Linux - allow PostgreSQL port sudo ufw allow 5432/tcp -
Test Connectivity
# Check if port is open telnet localhost 5432 nc -zv localhost 5432
[!TIP] Enable logging in PostgreSQL to see connection attempts.
β±οΈ Connection timeout
Causes:
- Network latency
- Server overload
- Firewall blocking
Solutions:
- Increase timeout in VS Code settings
- Check network connectivity
- Verify server is accepting connections
- Check max_connections setting
π Query timeout
Optimization Steps:
-
Add WHERE Clauses
-- Instead of SELECT * FROM large_table; -- Use SELECT * FROM large_table WHERE created_at >= NOW() - INTERVAL '7 days' LIMIT 1000;
-
Create Indexes
CREATE INDEX idx_users_email ON users(email); CREATE INDEX idx_orders_date ON orders(created_at);
-
Use EXPLAIN
EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 123;
-
Adjust Settings
- Increase
statement_timeoutin PostgreSQL - Increase query timeout in extension settings
- Increase
πΎ Out of memory
Solutions:
- Reduce result set size with LIMIT
- Use pagination for large datasets
- Export data in chunks
- Increase VS Code memory:
--max-memory=4096
β Cannot export data
| Problem | Solution |
|---|---|
| Permission denied | Check workspace folder permissions |
| File in use | Close file in other applications |
| Disk full | Check available disk space |
| Large dataset | Export in chunks or use LIMIT |
Access via Ctrl+, or File β Preferences β Settings
This extension is licensed under the MIT License.
MIT License - Copyright (c) 2024
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...
|
Comprehensive guides and tutorials |
Found a bug? Let us know! |
Ask questions, share ideas |
Enjoying the extension? |
- β Star the repository on GitHub
- π¦ Follow updates and announcements
- π¬ Join community discussions
- π€ Contribute to make it better!
Built by developers, for developers
β If you find this extension helpful, please consider giving it a star on GitHub and rating it on the VS Code Marketplace!


{ // Connection Management "postgresExplorer.connections": [], // Saved connections "postgresExplorer.autoConnect": true, // Auto-connect on startup // Query Settings "postgresExplorer.maxResults": 1000, // Max rows per query "postgresExplorer.queryTimeout": 30000, // Query timeout (ms) // Display Settings "postgresExplorer.dateFormat": "YYYY-MM-DD", // Date display format "postgresExplorer.numberFormat": "en-US", // Number formatting // Export Settings "postgresExplorer.exportPath": "./exports", // Default export path "postgresExplorer.csvDelimiter": ",", // CSV delimiter // Performance "postgresExplorer.cacheEnabled": true, // Enable caching "postgresExplorer.refreshInterval": 5000 // Dashboard refresh (ms) }