Database Setup

This guide walks you through configuring database connections in StratusTS, from choosing a database to testing your connection.

Overview

StratusTS supports multiple database systems:

• SQLite - File-based, zero-configuration
• PostgreSQL - Robust, production-ready
• MySQL - Popular, widely supported
• MariaDB - MySQL fork with extra features
• MongoDB - NoSQL document database

Choosing a Database

SQLite - Best for Development

Perfect for:

• Learning and prototyping
• Development environment
• Small applications
• Single-user apps

Pros:

• No server setup required
• Just a file on your computer
• Instant start
• Great for beginners

Cons:

• Limited concurrent writes
• Not ideal for production at scale
• Fewer features than PostgreSQL

When to use: Getting started, prototypes, development

PostgreSQL - Best for Production

Perfect for:

• Production applications
• Complex queries
• Large datasets
• Team projects

Pros:

• Extremely reliable
• Feature-rich
• Excellent performance
• Great community

Cons:

• Requires server setup
• More complex than SQLite

When to use: Serious applications, production environments

MySQL/MariaDB - Popular Alternative

Perfect for:

• Web applications
• WordPress-style projects
• Shared hosting

Pros:

• Widely supported
• Familiar to many developers
• Good hosting options

Cons:

• Less feature-rich than PostgreSQL
• Some licensing considerations (MySQL)

When to use: Traditional web hosting, familiar with MySQL

MongoDB - NoSQL Option

Perfect for:

• Flexible schemas
• Document-based data
• Rapid iteration

Pros:

• Schema flexibility
• JSON-like documents
• Horizontal scaling

Cons:

• Different paradigm (NoSQL)
• Less structured

When to use: Dynamic schemas, document storage

No Database Configuration

If you don’t need a database:

src/settings.ts

const DATABASE: DatabaseType = false;

Use cases:

• Pure API proxy
• External database via API
• Microservices that don’t store data

Your app starts faster without database overhead.

SQLite Configuration

Basic Setup

src/settings.ts

const DATABASE: DatabaseType = {
  config:{
    engine: 'sqlite',
    path: './database.sqlite'
  },
  onSuccess:()=>{
    console.log('database connected successfully')
  }
}

What Happens

1. Creates database.sqlite file in your project root
2. Stores all data in this single file
3. No server or credentials needed

File Location Options

src/settings.ts

// Root directory (default)
database: 'database.sqlite'

// Specific directory
database: './data/app.db'

// Inside src
database: './src/database.sqlite' // Don't do this

In-Memory Database (Testing)

Note

This isn’t tested yet
Use With Warning

src/settings.ts

const DATABASE: DatabaseType = {
  config:{
    engine: 'sqlite',
    path: ':memory:'
  },
  onSuccess:()=>{
    console.log('database connected successfully')
  }
}

Use case: Unit tests - database resets after each test run.

Complete SQLite Example

src/settings.ts

import type { DatabaseType, SettingsType } from 'stratus-ts';

const PORT = 2000;
const APPS = ['users', 'blog'];

const DATABASE: DatabaseType = {
  config:{
    engine: 'sqlite',
    path: ':memory:'
  },
  onSuccess:()=>{
    console.log('database connected successfully')
  }
}

const TEMPLATE_DIR = 'templates';

export default {
  PORT,
  APPS,
  DATABASE,
  TEMPLATE_DIR,
} satisfies SettingsType;

PostgreSQL Configuration

Make Sure you are running postgre

Installation

To Install Postgres Or use Docker to run postgre

Create Database

terminal

# Login as postgres user
sudo -u postgres psql

# Inside psql:
CREATE DATABASE mydb;

CREATE USER myuser WITH PASSWORD 'secure_password';

GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;

\q

Basic Configuration

src/settings.ts

const DATABASE: DatabaseType = {
  config: {
    engine: 'postgre',
    host: 'localhost',
    port: 5432,
    user:'myuser',
    password: 'secure_password',
    database: 'mydb',
  },
  onSuccess: () => {
    console.log('database connected successfully')
  }
}

Using Environment Variables (Recommended)

Create .env file:

.env

DB_HOST=localhost
DB_PORT=5432
DB_USER=myuser
DB_PASSWORD=secure_password
DB_NAME=mydb

Update settings:

src/settings.ts

const DATABASE: DatabaseType = {
  config: {
    engine: 'postgre',
    host: process.env.DB_HOST!,
    port: parseInt(process.env.DB_PORT!),
    user: process.env.DB_USER!,
    password: process.env.DB_PASSWORD!,
    database: process.env.DB_NAME!,
  },
  onSuccess: () => {
    console.log('database connected successfully')
  }
}

Don’t forget: Add .env to .gitignore!

.gitignore

.env
.env.*

MySQL Configuration

Make Sure you are running MySQL

Installation

To Install MySQL Or use Docker to run MySQL

Create Database

terminal

# Login to MySQL
mysql -u root -p

# Inside MySQL:
CREATE DATABASE mydb;

CREATE USER 'myuser'@'localhost' IDENTIFIED BY 'secure_password';

GRANT ALL PRIVILEGES ON mydb.* TO 'myuser'@'localhost';

FLUSH PRIVILEGES;

EXIT;

Basic Configuration

src/settings.ts

const DATABASE: DatabaseType = {
  config: {
    engine: 'mysql',
    host: 'localhost',
    port: 5432,
    user:'myuser',
    password: 'secure_password',
    database: 'mydb',
  },
  onSuccess: () => {
    console.log('database connected successfully')
  }
}

Using Environment Variables (Recommended)

Create .env file:

.env

DB_HOST=localhost
DB_PORT=5432
DB_USER=myuser
DB_PASSWORD=secure_password
DB_NAME=mydb

Update settings:

src/settings.ts

const DATABASE: DatabaseType = {
  config: {
    engine: 'mysql',
    host: process.env.DB_HOST!,
    port: parseInt(process.env.DB_PORT!),
    user: process.env.DB_USER!,
    password: process.env.DB_PASSWORD!,
    database: process.env.DB_NAME!,
  },
  onSuccess: () => {
    console.log('database connected successfully')
  }
}

MariaDB Configuration

This is not implement yet

MongoDB Configuration

Make Sure you are running MongoDB

Installation

To Install MongoDB Or use Docker to run MongoDB

Basic Configuration

src/settings.ts

const DATABASE: DatabaseType = {
  config: {
    engine: 'mongo',
    uri:'mongodb://localhost:27017',
    db:'mydb'
  },
  onSuccess: () => {
    console.log('database connected successfully')
  }
}

Using Environment Variables (Recommended)

Create .env file:

.env

DB_URI="mongodb://localhost:27017"
DB_NAME=mydb

Update settings:

src/settings.ts

const DATABASE: DatabaseType = {
  config: {
    engine: 'mongo',
    uri: process.env.DB_URI!,
    db: process.env.DB_NAME!,
  },
  onSuccess: () => {
    console.log('database connected successfully')
  }
}

MongoDB Atlas (Cloud)

.env

DB_URI="mongodb+srv://user:password@cluster.mongodb.net/"
DB_NAME=mydb

Environment-Specific Configuration

Development vs Production

src/settings.ts

const isProduction = process.env.ENV !== 'prod';

const DATABASE: DatabaseType = !isProduction ? {
  config:{
    engine: 'sqlite',
    path: './database.sqlite'
  },
  onSuccess:()=>{
    console.log('database connected successfully')
  }
} : {
  config: {
    engine: 'postgre',
    host: process.env.DB_HOST!,
    port: parseInt(process.env.DB_PORT!),
    user: process.env.DB_USER!,
    password: process.env.DB_PASSWORD!,
    database: process.env.DB_NAME!,
  },
  onSuccess: () => {
    console.log('database connected successfully')
  }
}

Multiple Environments

src/settings.ts

const environment = process.env.ENV || 'dev';

const databaseConfig = {
  dev: {
    engine: 'sqlite' as const,
    path: './database.sqlite'
  },

  stag: {
    engine: 'postgre' as const,
    host: process.env.DB_HOST!,
    port: parseInt(process.env.DB_PORT!),
    user: process.env.DB_USER!,
    password: process.env.DB_PASSWORD!,
    database: process.env.DB_NAME!,
  },

  prod: {
    engine: 'postgre' as const,
    host: process.env.DB_HOST!,
    port: parseInt(process.env.DB_PORT!),
    user: process.env.DB_USER!,
    password: process.env.DB_PASSWORD!,
    database: process.env.DB_NAME!,
  },
};

const DATABASE: DatabaseType =
  databaseConfig[environment as keyof typeof databaseConfig];

Advanced Options

Logging SQL Queries

Note

This isn’t implemented yet

Testing Your Connection

Start Your Server

terminal

pnpm dev # or npm run dev

Check Console Output

Success:

node

database connected successfully
server running on port : 2000

Failure:

node

Database connection failed: <error message>

Troubleshooting

”Connection Refused” Error

Causes:

• Database server not running
• Wrong host/port
• Firewall blocking connection

Solutions:

terminal

# Check if PostgreSQL is running
brew services list  # macOS
sudo systemctl status postgresql  # Linux

# Start the service
brew services start postgresql  # macOS
sudo systemctl start postgresql  # Linux

# Check port is listening
sudo lsof -i :5432  # PostgreSQL
sudo lsof -i :3306  # MySQL

“Authentication Failed” Error

Causes:

• Wrong username/password
• User doesn’t have permissions
• Wrong authentication method

Solutions:

terminal

# PostgreSQL: Reset password
sudo -u postgres psql
ALTER USER myuser WITH PASSWORD 'new_password';

# MySQL: Reset password
mysql -u root -p
ALTER USER 'myuser'@'localhost' IDENTIFIED BY 'new_password';

“Database Does Not Exist” Error

Solution: Create the database manually:

terminal

sudo -u postgres psql
CREATE DATABASE mydb;

# MySQL
mysql -u root -p
CREATE DATABASE mydb;

Best Practices

1. Never Commit Credentials

❌ Don’t:

src/settings.ts

password: 'my_secret_password',  // In version control!

✅ Do:

src/settings.ts

password: process.env.DB_PASSWORD || ''

2. Use Different Databases per Environment

development → SQLite or local PostgreSQL
staging → Staging PostgreSQL server
production → Production PostgreSQL server

3. Use Migrations, Do Not modify database directly

Let migrations handle schema changes.

Next Steps

Now that your database is configured:

• Migrations - Create migrations form your Models