Code_of_Conquest/api/scripts/README.md

Scripts Directory

This directory contains utility scripts for database initialization, migrations, and other maintenance tasks.

Database Initialization

init_database.py

Initializes all database tables in Appwrite with the correct schema, columns, and indexes.

Usage:

# Ensure virtual environment is activated
source venv/bin/activate

# Run the initialization script
python scripts/init_database.py

Prerequisites:

1. Appwrite instance running and accessible
2. .env file configured with Appwrite credentials:
   • APPWRITE_ENDPOINT
   • APPWRITE_PROJECT_ID
   • APPWRITE_API_KEY
   • APPWRITE_DATABASE_ID

What it does:

1. Validates environment configuration

2. Creates the following tables:

   • characters: Player character data with userId indexing

3. Creates necessary columns and indexes for efficient querying

4. Skips tables/columns/indexes that already exist (idempotent)

Output:

============================================================
Code of Conquest - Database Initialization
============================================================

✓ Environment variables loaded
  Endpoint: https://your-appwrite-instance.com/v1
  Project: your-project-id
  Database: main

Initializing database tables...

============================================================
Initialization Results
============================================================

✓ characters: SUCCESS

Total: 1 succeeded, 0 failed

✓ All tables initialized successfully!

You can now start the application.

Adding New Tables

To add a new table to the initialization process:

1. Open app/services/database_init.py
2. Create a new method following the pattern of init_characters_table()
3. Add the table initialization to init_all_tables() method
4. Run the initialization script

Example:

def init_sessions_table(self) -> bool:
    """Initialize the sessions table."""
    table_id = 'sessions'

    # Create table
    table = self.tables_db.create_table(
        database_id=self.database_id,
        table_id=table_id,
        name='Sessions'
    )

    # Create columns
    self._create_column(
        table_id=table_id,
        column_id='userId',
        column_type='string',
        size=255,
        required=True
    )

    # Create indexes
    self._create_index(
        table_id=table_id,
        index_id='idx_userId',
        index_type='key',
        attributes=['userId']
    )

    return True

Troubleshooting

Missing Environment Variables

If you see errors about missing environment variables, ensure your .env file contains all required Appwrite configuration.

Connection Errors

If the script cannot connect to Appwrite:

• Verify the APPWRITE_ENDPOINT is correct and accessible
• Check that the API key has sufficient permissions
• Ensure the database exists in your Appwrite project

Column/Index Already Exists

The script is idempotent and will log warnings for existing columns/indexes without failing. This is normal if you run the script multiple times.