Akron ORM - Universal Python ORM

Overview

Akron ORM can be installed via pip and supports multiple database backends. This guide covers installation for all supported databases and common setup scenarios.

📋 Requirements

• Python 3.7 or higher
• pip package manager
• Database server (for MySQL, PostgreSQL, MongoDB)
• Virtual environment (recommended)

Basic Installation

Install Akron ORM

Install Akron using pip. This includes SQLite support by default:

Basic Installation

1# Install Akron ORM
2pip install akron
3
4# Verify installation
5python -c "import akron; print(f'Akron {akron.__version__} installed successfully')"
6
7# Check CLI availability
8akron --version

Expected Output

Collecting akron
Installing collected packages: akron
Successfully installed akron-1.0.0

Akron 1.0.0 installed successfully
akron 1.0.0

✅ What's Included

• Akron ORM core library
• SQLite driver (built into Python)
• Pydantic integration for type safety
• Command-line interface (CLI)
• Migration system

Database-Specific Installation

MySQL Support

Install MySQL connector for MySQL database support:

MySQL Installation

1# Install with MySQL support
2pip install akron mysql-connector-python
3
4# Alternative MySQL driver (if needed)
5pip install akron PyMySQL
6
7# Verify MySQL connection capability
8python -c "import mysql.connector; print('MySQL connector ready')"
9
10# Test connection (replace with your credentials)
11python -c "
12from akron import Akron
13try:
14    db = Akron('mysql://user:password@localhost:3306/test')
15    print('MySQL connection successful')
16except Exception as e:
17    print(f'MySQL connection failed: {e}')
18"

Prerequisites for MySQL

• Running MySQL server (8.0+ recommended)
• Database user with appropriate privileges
• Network access to MySQL server

PostgreSQL Support

Install PostgreSQL adapter for PostgreSQL database support:

PostgreSQL Installation

1# Install with PostgreSQL support
2pip install akron psycopg2-binary
3
4# For production (compile from source)
5pip install akron psycopg2
6
7# Using conda (alternative)
8conda install akron psycopg2
9
10# Verify PostgreSQL connection capability
11python -c "import psycopg2; print('PostgreSQL adapter ready')"
12
13# Test connection (replace with your credentials)
14python -c "
15from akron import Akron
16try:
17    db = Akron('postgres://user:password@localhost:5432/test')
18    print('PostgreSQL connection successful')
19except Exception as e:
20    print(f'PostgreSQL connection failed: {e}')
21"

Prerequisites for PostgreSQL

• Running PostgreSQL server (12+ recommended)
• Database user with appropriate privileges
• libpq-dev package (for psycopg2 compilation)

MongoDB Support

Install MongoDB driver for MongoDB database support:

MongoDB Installation

1# Install with MongoDB support
2pip install akron pymongo
3
4# With additional features (DNS SRV support for Atlas)
5pip install akron "pymongo[srv]"
6
7# Verify MongoDB connection capability
8python -c "import pymongo; print('MongoDB driver ready')"
9
10# Test connection (replace with your credentials)
11python -c "
12from akron import Akron
13try:
14    db = Akron('mongodb://localhost:27017/test')
15    print('MongoDB connection successful')
16except Exception as e:
17    print(f'MongoDB connection failed: {e}')
18"

Prerequisites for MongoDB

• Running MongoDB server (4.4+ recommended)
• Authentication configured (if required)
• Network access to MongoDB server

Complete Installation

All Databases at Once

Install Akron with support for all databases in one command:

Full Installation

1# Install with all database drivers
2pip install akron mysql-connector-python psycopg2-binary pymongo
3
4# Or using a requirements.txt file
5echo "akron
6mysql-connector-python
7psycopg2-binary
8pymongo" > requirements.txt
9
10pip install -r requirements.txt
11
12# Verify all drivers
13python -c "
14import akron
15import sqlite3
16import mysql.connector
17import psycopg2
18import pymongo
19
20print('✓ Akron ORM installed')
21print('✓ SQLite support (built-in)')
22print('✓ MySQL support available') 
23print('✓ PostgreSQL support available')
24print('✓ MongoDB support available')
25print('\nAll database drivers ready!')
26"

Expected Output

✓ Akron ORM installed
✓ SQLite support (built-in)
✓ MySQL support available
✓ PostgreSQL support available
✓ MongoDB support available

All database drivers ready!

Virtual Environment Setup

Recommended: Using Virtual Environments

It's recommended to install Akron in a virtual environment to avoid conflicts:

Virtual Environment Setup

1# Create virtual environment
2python -m venv akron_env
3
4# Activate virtual environment (Windows)
5akron_env\Scripts\activate
6
7# Activate virtual environment (macOS/Linux)
8source akron_env/bin/activate
9
10# Install Akron in virtual environment
11pip install akron mysql-connector-python psycopg2-binary pymongo
12
13# Verify installation
14which python  # Should show path in akron_env
15pip list | grep akron
16
17# Deactivate when done
18deactivate

Using conda

Alternative installation using conda package manager:

Conda Installation

1# Create conda environment
2conda create -n akron_env python=3.9
3
4# Activate environment
5conda activate akron_env
6
7# Install Akron and dependencies
8pip install akron  # Akron not yet in conda-forge
9conda install mysql-connector-python psycopg2 pymongo
10
11# Verify installation
12conda list | grep -E "(akron|mysql|psycopg2|pymongo)"
13
14# Deactivate when done
15conda deactivate

Installation Verification

Complete Verification Script

Run this script to verify your installation and test all database connections:

Verification Script (save as test_installation.py)

1#!/usr/bin/env python3
2"""
3Akron ORM Installation Verification Script
4Run this to test your installation and database connectivity.
5"""
6
7import sys
8from datetime import datetime
9
10def test_akron_import():
  """Test basic Akron import and version"""
  try:
      import akron
      print(f"✓ Akron ORM {akron.__version__} imported successfully")
      return True
  except ImportError as e:
      print(f"✗ Failed to import Akron: {e}")
      return False
19
20def test_cli_availability():
  """Test CLI availability"""
  import subprocess
  try:
      result = subprocess.run(['akron', '--version'], 
                            capture_output=True, text=True, timeout=10)
      if result.returncode == 0:
          print(f"✓ CLI available: {result.stdout.strip()}")
          return True
      else:
          print(f"✗ CLI failed: {result.stderr}")
          return False
  except (subprocess.TimeoutExpired, FileNotFoundError) as e:
      print(f"✗ CLI not available: {e}")
      return False
35
36def test_database_drivers():
  """Test database driver availability"""
  drivers = {
      'SQLite': 'sqlite3',
      'MySQL': 'mysql.connector', 
      'PostgreSQL': 'psycopg2',
      'MongoDB': 'pymongo'
  }
  
  results = {}
  for db_name, module_name in drivers.items():
      try:
          __import__(module_name)
          print(f"✓ {db_name} driver available")
          results[db_name] = True
      except ImportError:
          print(f"✗ {db_name} driver not available")
          results[db_name] = False
  
  return results
56
57def test_basic_functionality():
  """Test basic Akron functionality"""
  try:
      from akron import Akron
      from pydantic import BaseModel
      from akron.models import ModelMixin
      
      # Test in-memory SQLite
      db = Akron("sqlite:///:memory:")
      
      # Test table creation
      db.create_table("test_table", {"id": "int", "name": "str"})
      
      # Test data insertion
      test_id = db.insert("test_table", {"id": 1, "name": "test"})
      
      # Test data retrieval
      result = db.find("test_table", {"id": 1})
      
      if result and result[0]["name"] == "test":
          print("✓ Basic CRUD operations working")
          return True
      else:
          print("✗ Basic CRUD operations failed")
          return False
          
  except Exception as e:
      print(f"✗ Basic functionality test failed: {e}")
      return False
86
87def main():
  """Run all verification tests"""
  print("Akron ORM Installation Verification")
  print("=" * 40)
  print(f"Python version: {sys.version}")
  print(f"Test time: {datetime.now()}")
  print("-" * 40)
  
  # Run tests
  tests = [
      ("Akron Import", test_akron_import),
      ("CLI Availability", test_cli_availability), 
      ("Database Drivers", test_database_drivers),
      ("Basic Functionality", test_basic_functionality)
  ]
  
  results = {}
  for test_name, test_func in tests:
      print(f"\n{test_name}:")
      results[test_name] = test_func()
  
  # Summary
  print("\n" + "=" * 40)
  print("VERIFICATION SUMMARY")
  print("=" * 40)
  
  all_passed = True
  for test_name, passed in results.items():
      status = "PASS" if passed else "FAIL"
      print(f"{test_name}: {status}")
      if not passed:
          all_passed = False
  
  if all_passed:
      print("\n✓ All tests passed! Akron is ready to use.")
      return 0
  else:
      print("\n✗ Some tests failed. Check installation.")
      return 1
126
127if __name__ == "__main__":
  sys.exit(main())

Run the verification script:

1python test_installation.py

Expected Output

Akron ORM Installation Verification
========================================
Python version: 3.9.7 (default, Sep 16 2021, 08:50:36)
Test time: 2024-01-15 10:30:45.123456
----------------------------------------

Akron Import:
✓ Akron ORM 1.0.0 imported successfully

CLI Availability:
✓ CLI available: akron 1.0.0

Database Drivers:
✓ SQLite driver available
✓ MySQL driver available
✓ PostgreSQL driver available
✓ MongoDB driver available

Basic Functionality:
✓ Basic CRUD operations working

========================================
VERIFICATION SUMMARY
========================================
Akron Import: PASS
CLI Availability: PASS
Database Drivers: PASS
Basic Functionality: PASS

✓ All tests passed! Akron is ready to use.

Troubleshooting

pip install fails

If pip installation fails, try these solutions:

1# Update pip first
2python -m pip install --upgrade pip
3
4# Install with verbose output to see errors
5pip install -v akron
6
7# Install from specific index if needed
8pip install -i https://pypi.org/simple akron
9
10# Clear pip cache if corrupted
11pip cache purge
12pip install akron

psycopg2 compilation errors

PostgreSQL driver compilation issues on some systems:

1# Use binary version (recommended)
2pip install psycopg2-binary
3
4# On Ubuntu/Debian, install system dependencies
5sudo apt-get install libpq-dev python3-dev
6
7# On CentOS/RHEL
8sudo yum install postgresql-devel python3-devel
9
10# On macOS with Homebrew
11brew install postgresql

MySQL connector issues

MySQL connector installation or connection problems:

1# Try alternative MySQL driver
2pip uninstall mysql-connector-python
3pip install PyMySQL
4
5# Update connection string for PyMySQL
6# From: mysql://user:pass@host/db
7# To:   mysql+pymysql://user:pass@host/db
8
9# Or install MySQL official connector
10pip install mysql-connector-python==8.0.33

Permission errors

Permission denied during installation:

1# Install for current user only
2pip install --user akron
3
4# Or use virtual environment (recommended)
5python -m venv myenv
6source myenv/bin/activate  # Linux/macOS
7myenv\Scripts\activate    # Windows
8pip install akron

Next Steps

Now that Akron is installed, you're ready to start building applications:

Quick Start Guide

Get up and running with your first Akron application in minutes

Basic Usage

Learn the fundamental concepts and operations

API Reference

Detailed documentation for all Akron methods

Database Guides

Database-specific features and configurations