hirejared-kw-db/docs/project-docs/05-operations/usage.md

System Usage Documentation

Overview

This document details how to use the keyword management system, including script execution, database operations, and LibreOffice Base interactions. The system uses a combination of command-line scripts for administration and LibreOffice Base for daily operations.

Initial Setup

1. Configuration

# Copy configuration template
cp .database.template .database

# Edit configuration with your settings
nano .database

# Set proper permissions
chmod 600 .database

2. Database Initialization

# Create database
./bin/db-admin/create-db.sh

# Verify creation
psql -h localhost -U postgres -d keyword_management -c "\l"

3. LibreOffice Base Connection

1. Open LibreOffice Base
2. Select "Connect to existing database"
3. Choose "PostgreSQL"
4. Enter connection details from .database file

Database Administration

Creating the Database

# Create new database
./bin/db-admin/create-db.sh

# With specific locale (if needed)
./bin/db-admin/create-db.sh --locale en-US

Backup and Restore

# Create backup
./bin/db-admin/backup-db.sh

# Restore from backup
./bin/db-admin/restore-db.sh backups/keyword_management-2024-11-19-100000.sql.gz

Database Removal

# Remove database (requires confirmation)
./bin/db-admin/drop-db.sh

Table Management

Creating Tables

# Create all tables
./bin/table-admin/create-tables/create-all-tables.sh

# Create specific table
./bin/table-admin/create-tables/create-keywords-table.sh

Table Modifications

# Apply specific version
./bin/table-admin/alter-tables/execute-version.sh 20241119_01 upgrade

# Rollback version
./bin/table-admin/alter-tables/execute-version.sh 20241119_01 rollback

Data Import Operations

GKWP Import

# Import single GKWP file
./bin/import-scripts/gkwp/import-gkwp-file.sh "GKWP - keyword.csv"

# Batch import GKWP files
./bin/import-scripts/gkwp/batch-import-gkwp.sh /path/to/gkwp/files

SEMRush Import

# Import SEMRush keyword data
./bin/import-scripts/semrush/standard/import-semrush-file.sh "SEMRush - keyword.csv"

# Import competitor data
./bin/import-scripts/semrush/competitor/import-competitor-file.sh "SEMRush Comp - example.com.csv"

Plain List Import

# Basic keyword list import
./bin/import-scripts/plain-list/import-keywords.sh keywords.txt

# Import with ad group assignment
./bin/import-scripts/plain-list/import-with-adgroups.sh keywords.csv ad_group_id

# Create ad group and import
./bin/import-scripts/plain-list/create-adgroup-import.sh keywords.txt "New Ad Group" campaign_id landing_page_id

LibreOffice Base Operations

Campaign Management

1. Open campaign management form
2. Create new campaign:
   • Enter campaign name
   • Set status
   • Add notes
   • Save

Ad Group Management

1. Open ad group management form
2. Create new ad group:
   • Select campaign
   • Choose landing page
   • Enter ad group name
   • Save

Keyword Assignment

1. Open keyword assignment form
2. Select target ad group
3. Choose keywords to assign
4. Confirm assignment

Data Views

Available views:

• Active Keywords per Ad Group
• Landing Page Usage
• Recent Imports
• Keyword Metrics

Testing

Running Tests

# Run all tests
./tests/run-all.sh

# Run specific test category
./tests/run-category.sh create-functions

# Run single test
./tests/db-admin/create-db.test.sh

Test Result Verification

# View test logs
cat logs/YYYY-MM-DD-test-execution.log

# Check test coverage
./tests/check-coverage.sh

Common Operations

Adding New Campaign

1. Create campaign using LibreOffice Base form
2. Add landing pages
3. Create ad groups
4. Import keywords
5. Assign keywords to ad groups

Updating Keyword Data

1. Export current keywords
2. Get new data from source
3. Run appropriate import script
4. Verify updates in LibreOffice Base

Managing Ad Groups

1. Open ad group management view
2. Create or modify ad groups
3. Assign landing pages
4. Add keywords through import or assignment

Maintenance

Regular Maintenance

# Backup database
./bin/db-admin/backup-db.sh

# Clean old logs
./bin/maintenance/clean-logs.sh

# Check database health
./bin/maintenance/check-db-health.sh

Error Recovery

# View recent errors
./bin/maintenance/show-errors.sh

# Retry failed imports
./bin/maintenance/retry-imports.sh

Best Practices

Data Import

1. Always verify file format before import
2. Use appropriate import script for data source
3. Check import logs for errors
4. Verify data in LibreOffice Base after import

Database Management

1. Regular backups
2. Monitor database size
3. Archive old data periodically
4. Maintain error logs

Ad Group Organization

1. Consistent naming conventions
2. Clear campaign structure
3. Proper landing page assignments
4. Regular review of keyword assignments

Troubleshooting

Common Issues

1. Import failures

   • Check file format
   • Verify permissions
   • Review error logs

2. Connection issues

   • Verify database configuration
   • Check network connectivity
   • Confirm credentials

3. Performance problems

   • Monitor database size
   • Check index usage
   • Review query patterns

Getting Help

• Check logs in /logs directory
• Review documentation
• Contact system administrator

Would you like me to expand on any particular aspect of system usage or provide additional examples?