cmdb-insight/docs/DATABASE-ACCESS.md

Database Access Guide

This guide shows you how to easily access and view records in the PostgreSQL database.

Quick Access

Option 1: Using the Script (Easiest)

# Connect using psql
./scripts/open-database.sh psql

# Or via Docker
./scripts/open-database.sh docker

# Or get connection string for GUI tools
./scripts/open-database.sh url

Option 2: Direct psql Command

# If PostgreSQL is running locally
PGPASSWORD=cmdb-dev psql -h localhost -p 5432 -U cmdb -d cmdb

Option 3: Via Docker

# Connect to PostgreSQL container
docker exec -it $(docker ps | grep postgres | awk '{print $1}') psql -U cmdb -d cmdb

Connection Details

From docker-compose.yml:

• Host: localhost (or postgres if connecting from Docker network)
• Port: 5432
• Database: cmdb
• User: cmdb
• Password: cmdb-dev

Connection String:

postgresql://cmdb:cmdb-dev@localhost:5432/cmdb

GUI Tools

pgAdmin (Free, Web-based)

1. Download from: https://www.pgadmin.org/download/
2. Add new server with connection details above
3. Browse tables and run queries

DBeaver (Free, Cross-platform)

1. Download from: https://dbeaver.io/download/
2. Create new PostgreSQL connection
3. Use connection string or individual fields

TablePlus (macOS, Paid but has free tier)

1. Download from: https://tableplus.com/
2. Create new PostgreSQL connection
3. Enter connection details

DataGrip (JetBrains, Paid)

1. Part of JetBrains IDEs or standalone
2. Create new PostgreSQL data source
3. Use connection string

Useful SQL Commands

Once connected, try these commands:

-- List all tables
\dt

-- Describe a table structure
\d users
\d classifications
\d cache_objects

-- View all users
SELECT * FROM users;

-- View classifications
SELECT * FROM classifications ORDER BY created_at DESC LIMIT 10;

-- View cached objects
SELECT object_key, object_type, updated_at FROM cache_objects ORDER BY updated_at DESC LIMIT 20;

-- Count records per table
SELECT 
    'users' as table_name, COUNT(*) as count FROM users
UNION ALL
SELECT 
    'classifications', COUNT(*) FROM classifications
UNION ALL
SELECT 
    'cache_objects', COUNT(*) FROM cache_objects;

-- View user settings
SELECT u.username, u.email, us.ai_provider, us.ai_enabled 
FROM users u 
LEFT JOIN user_settings us ON u.id = us.user_id;

Environment Variables

If you're using environment variables instead of Docker:

# Check your .env file for:
DATABASE_URL=postgresql://cmdb:cmdb-dev@localhost:5432/cmdb
# or
DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=cmdb
DATABASE_USER=cmdb
DATABASE_PASSWORD=cmdb-dev

Troubleshooting

Database not running

# Start PostgreSQL container
docker-compose up -d postgres

# Check if it's running
docker ps | grep postgres

Connection refused

• Make sure PostgreSQL container is running
• Check if port 5432 is already in use
• Verify connection details match docker-compose.yml

Permission denied

• Verify username and password match docker-compose.yml
• Check if user has access to the database