---
title: "Database Setup"
description: "Set up PostgreSQL database for TraceRTM"
keywords: [database, postgresql, setup, configuration]
---

# Database Setup

Set up and configure PostgreSQL database for TraceRTM.

## PostgreSQL Installation

### macOS

```bash
brew install postgresql@14
brew services start postgresql@14
```

### Linux (Ubuntu/Debian)

```bash
sudo apt-get update
sudo apt-get install postgresql-14 postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

### Windows

Download and install from [postgresql.org](https://www.postgresql.org/download/windows/)

## Create Database

### Using psql

```bash
# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE tracertm_dev;

# Create user
CREATE USER tracertm_user WITH PASSWORD 'your_password';

# Grant privileges
GRANT ALL PRIVILEGES ON DATABASE tracertm_dev TO tracertm_user;

# Exit
\q
```

### Using Command Line

```bash
# Create database
createdb -U postgres tracertm_dev

# Create user
createuser -U postgres tracertm_user
```

## Configure Connection

### Connection String

```bash
# Format
postgresql://username:password@host:port/database

# Example
postgresql://tracertm_user:password@localhost:5432/tracertm_dev
```

### Environment Variable

```bash
# Set in .env file
DATABASE_URL=postgresql://tracertm_user:password@localhost:5432/tracertm_dev
```

## Run Migrations

### Using Alembic

```bash
# Initialize Alembic (first time only)
alembic init alembic

# Create migration
alembic revision --autogenerate -m "Initial migration"

# Apply migrations
alembic upgrade head
```

### Using CLI

```bash
# Run migrations
python -m tracertm.cli migrate

# Or using Docker
docker-compose exec api python -m tracertm.cli migrate
```

## Database Extensions

### Required Extensions

```sql
-- Connect to database
\c tracertm_dev

-- Enable extensions
CREATE EXTENSION IF NOT EXISTS "pg_trgm";  -- For text search
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";  -- For UUID generation
```

## Configuration

### PostgreSQL Settings

Edit `postgresql.conf`:

```conf
# Connection settings
max_connections = 100

# Memory settings
shared_buffers = 256MB
effective_cache_size = 1GB

# Performance
random_page_cost = 1.1  # For SSD
```

### Restart PostgreSQL

```bash
# macOS
brew services restart postgresql@14

# Linux
sudo systemctl restart postgresql
```

## Backup and Restore

### Backup

```bash
# Full backup
pg_dump -U tracertm_user tracertm_dev > backup.sql

# Compressed backup
pg_dump -U tracertm_user -Fc tracertm_dev > backup.dump
```

### Restore

```bash
# From SQL file
psql -U tracertm_user tracertm_dev < backup.sql

# From dump file
pg_restore -U tracertm_user -d tracertm_dev backup.dump
```

## Troubleshooting

### Connection Issues

```bash
# Check PostgreSQL is running
sudo systemctl status postgresql

# Check connection
psql -U tracertm_user -d tracertm_dev -h localhost
```

### Permission Issues

```sql
-- Grant necessary permissions
GRANT ALL PRIVILEGES ON DATABASE tracertm_dev TO tracertm_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO tracertm_user;
```

## Related Documentation

- [Prerequisites](./01-prerequisites) - Required software
- [Environment Variables](./05-environment-variables) - Configuration
- [Docker Setup](./03-docker-setup) - Containerized database
