scar-chat7/dbmanager/README.md

DBManager - SCAR Chat Database Management Tool

Command-line utility for managing SCAR Chat user database.

Overview

dbmanager provides a convenient interface for user administration without requiring direct SQL commands. It handles password hashing with Argon2, avatar management, and user queries.

Database Location

DBManager searches for scarchat.db in the following order:

1. Current working directory
2. CMake install path: /usr/local/share/scarchat/scarchat.db
3. User home directory: ~/.local/share/scarchat/scarchat.db

You can override this with the --db option.

Usage

dbmanager [OPTIONS] COMMAND [ARGS...]

Options

• --db <path> - Specify custom database path
• --help - Display help message

Commands

User Management

Add User

dbmanager adduser <username> <password> [avatar]

Creates a new user with automatic salt generation and Argon2 password hashing.

Examples:

dbmanager adduser alice password123
dbmanager adduser bob secret456 /path/to/avatar.png

Delete User

dbmanager deleteuser <username>

Removes a user from the database.

Example:

dbmanager deleteuser alice

Modify User Fields

Change Password

dbmanager modifypass <username> <newpassword>

Updates user's password with new salt and hash.

Example:

dbmanager modifypass alice newpassword123

Update Avatar

dbmanager modifyavatar <username> <avatar_file>

Sets user's avatar image from file (PNG, JPG, etc.).

Example:

dbmanager modifyavatar alice /home/alice/profile.jpg

Update Email

dbmanager modifyemail <username> <email>

Sets user's email address.

Example:

dbmanager modifyemail alice alice@example.com

Update Role

dbmanager modifyrole <username> <role>

Sets user's role (e.g., admin, moderator, user).

Example:

dbmanager modifyrole alice admin

Query Operations

Fetch User Details

dbmanager fetch <username>

Displays comprehensive information for a specific user.

Example:

dbmanager fetch alice

Output:

User ID: 1
Username: alice
Status: Offline
Email: alice@example.com
Role: admin
Last Login: Sun Dec  7 10:30:45 2025
Has Avatar: Yes
Token: eyJhbGciOiJIUzI1Ni...
Salt: a1b2c3d4e5f6...
Password Hash: $argon2id$v=19$m=...

Search Users

dbmanager search <field> <value>

Searches users by username, email, or role.

Fields: username, email, role

Example:

dbmanager search role admin
dbmanager search username alice
dbmanager search email @example.com

List All Users

dbmanager list

Displays a table of all users with status information.

Example Output:

Total users: 3
Username             Status     Email                     Role            Last Login          
alice                Offline    alice@example.com         admin           2025-12-07 10:30:45
bob                  Online     bob@example.com           user            2025-12-07 11:15:20
charlie              Offline    (not set)                 moderator       Never

Advanced Usage

Custom Database Location

dbmanager --db /custom/path/chat.db list
dbmanager --db ~/databases/scarchat.db adduser test password

Batch Operations

# Create multiple users
for user in alice bob charlie; do
    dbmanager adduser "$user" "password123"
done

# Update all users to default role
dbmanager list | tail -n +4 | awk '{print $1}' | while read user; do
    dbmanager modifyrole "$user" "user"
done

Integration with Scripts

#!/bin/bash
# Setup test environment

# Create admin user
dbmanager adduser admin admin123
dbmanager modifyrole admin admin
dbmanager modifyemail admin admin@localhost

# Create test users
for i in {1..10}; do
    dbmanager adduser "user$i" "pass$i"
done

echo "Test environment ready!"

Password Security

• Algorithm: Argon2id (PHC winner)
• Time Cost: 2 iterations
• Memory Cost: 64 MB
• Parallelism: 4 threads
• Salt: 16-byte random per user
• Hash Length: 32 bytes

Database Schema

The users table has the following structure:

Column	Type	Description
id	INTEGER	Primary key (auto-increment)
username	TEXT	Unique username
password	TEXT	Argon2 hash
salt	TEXT	Random salt (hex)
token	TEXT	JWT session token
status	TEXT	'online' or 'offline'
role	TEXT	User role (admin, user, etc.)
email	TEXT	Email address
last_login	INTEGER	Unix timestamp
avatar_pic	BLOB	Avatar image data

Build

DBManager is built automatically with the SCAR Chat project:

cmake -B build
cmake --build build
./build/dbmanager/dbmanager --help

Installation

sudo cmake --install build
dbmanager --help

Default install locations:

• Binary: /usr/local/bin/dbmanager
• Database: /usr/local/share/scarchat/scarchat.db

Troubleshooting

Database Not Found

Error: Failed to initialize database: scarchat.db

Solution: Use --db to specify path or create database first:

touch scarchat.db
dbmanager adduser testuser testpass

User Already Exists

Error: User 'alice' already exists

Solution: Delete existing user first or choose different username:

dbmanager deleteuser alice
dbmanager adduser alice newpassword

Avatar File Not Found

Error: Failed to read avatar file

Solution: Verify file path and permissions:

ls -l /path/to/avatar.png
dbmanager modifyavatar alice "$(realpath avatar.png)"

See Also

• PROGRESS-DBMANAGER.md - Implementation status
• server/database/database.h - Database API
• shared/crypto/argon2_wrapper.h - Password hashing

License

Same as SCAR Chat project.