Skip to main content

​
Overview

The Soft-Bee API uses PostgreSQL as its database backend. Database configuration is managed through the DATABASE_URL environment variable and varies by environment.
The application follows PostgreSQL connection URI format for database configuration.

​
Database URL Format

The DATABASE_URL follows the PostgreSQL connection string format: 
postgresql://[user[:password]@][host][:port][/database]

​
Components

​
user
string
required
PostgreSQL username
​
password
string
required
PostgreSQL password
​
host
string
required
Database server hostname or IP address
​
port
number
default:"5432"
PostgreSQL port number
​
database
string
required
Database name

​
Environment-Specific Databases

Each environment uses a separate database to prevent data conflicts:

​
Local Environment

​
DATABASE_URL
string
Database connection for local development
.env.local
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/softbee_local
Default Configuration:
  • Database Name: softbee_local
  • Host: localhost
  • Port: 5432
  • User: postgres
  • Password: postgres

​
Development Environment

​
DATABASE_URL
string
Database connection for development server
.env.development
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/softbee_dev
Default Configuration:
  • Database Name: softbee_dev
  • Host: localhost
  • Port: 5432
  • User: postgres
  • Password: postgres

​
Production Environment

​
DATABASE_URL
string
required
Database connection for production (REQUIRED)
Production environment requires DATABASE_URL to be explicitly set. The application will fail to start if this variable is missing.
.env.production
DATABASE_URL=postgresql://prod_user:secure_password@db.example.com:5432/softbee_prod
Production Considerations:
  • No default value provided
  • Must be explicitly configured
  • Use strong credentials
  • Consider using connection pooling
  • Enable SSL/TLS for remote connections

​
Testing Environment

​
DATABASE_URL
string
Database connection for automated tests
.env.testing
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/softbee_test
Default Configuration:
  • Database Name: softbee_test
  • Host: localhost
  • Port: 5432
  • User: postgres
  • Password: postgres
The test database is isolated to prevent interference with development or production data.

​
Additional PostgreSQL Variables

For advanced PostgreSQL configuration, you can use these optional variables:
​
PGUSER
string
default:"postgres"
PostgreSQL username (alternative to DATABASE_URL)
​
PGPASSWORD
string
default:"postgres"
PostgreSQL password (alternative to DATABASE_URL)
​
PGHOST
string
default:"localhost"
PostgreSQL host (alternative to DATABASE_URL)
​
PGPORT
number
default:"5432"
PostgreSQL port (alternative to DATABASE_URL)
​
PGDATABASE
string
default:"softbee"
PostgreSQL database name (alternative to DATABASE_URL)
​
SSL_MODE
string
SSL mode for PostgreSQL connections (e.g., require, disable, prefer)
.env
PGUSER=postgres
PGPASSWORD=postgres
PGHOST=localhost
PGPORT=5432
PGDATABASE=softbee
SSL_MODE=require
While these individual PostgreSQL variables are supported, using DATABASE_URL is recommended as it’s more portable and follows standard conventions.

​
Database Setup Examples

​
Local Development Setup

1

Install PostgreSQL

Install PostgreSQL on your local machine
# macOS
brew install postgresql

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# Windows
# Download installer from postgresql.org
2

Create Local Database

Create the local development database
psql -U postgres
CREATE DATABASE softbee_local;
\q
3

Configure Environment

Set the DATABASE_URL in your .env file
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/softbee_local

​
Docker Setup

version: '3.8'

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: softbee_local
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

​
Production Setup with SSL

For production deployments with SSL-enabled PostgreSQL: 
DATABASE_URL=postgresql://user:password@db.example.com:5432/softbee_prod?sslmode=require
Always use SSL/TLS for production database connections, especially when connecting to remote databases.

​
Connection Pooling

For production environments with high traffic, consider using connection pooling: 
# The application automatically handles connection pooling
# through SQLAlchemy's engine configuration

​
Troubleshooting

​
Connection Refused

Ensure PostgreSQL service is running:
# macOS
brew services start postgresql

# Ubuntu/Debian
sudo systemctl start postgresql

# Check status
pg_isready
Verify your username and password are correct:
psql -U postgres -h localhost -d softbee_local
Create the database if it doesn’t exist:
createdb -U postgres softbee_local
Check if port 5432 is available or change the port in your configuration:
lsof -i :5432

​
Best Practices

Use separate databases per environment to prevent data contamination
Use environment variables for production credentials, never hardcode
Enable SSL/TLS for all remote database connections
Use strong passwords for production database users
Regular backups of production databases
Monitor connection pool usage in production

​
Next Steps

Environment Configuration

Learn about environment-specific settings

JWT Configuration

Configure authentication tokens

Build docs developers (and LLMs) love

Get started for freeTalk to us