Akron ORM - Universal Python ORM

Your First Akron Application

In this quick start guide, you'll build a simple blog application using Akron ORM. We'll cover database setup, table creation, and basic CRUD operations.

🎯 What You'll Build

• A simple blog application with users and posts
• Database tables with proper relationships
• CRUD operations for managing data
• Both Python API and CLI examples

Step 1: Project Setup

Create Project Directory

First, let's create a new directory for our blog application:

Project Setup

1# Create project directory
2mkdir blog_app
3cd blog_app
4
5# Create a virtual environment (recommended)
6python -m venv venv
7
8# Activate virtual environment
9# Windows:
10venv\Scripts\activate
11# macOS/Linux:
12source venv/bin/activate
13
14# Install Akron
15pip install akron
16
17# Create main application file
18touch blog_app.py
19
20# Verify installation
21python -c "import akron; print('Akron ready!')"

Expected Output

Akron ready!

Step 2: Define Your Models

Create Data Models

Create blog_app.py and define your data models using Pydantic:

blog_app.py - Data Models

1from akron import Akron
2from pydantic import BaseModel, EmailStr
3from akron.models import ModelMixin
4from datetime import datetime
5from typing import Optional
6
7# Define User model
8class User(BaseModel, ModelMixin):
9    id: int
10    username: str
11    email: str
12    full_name: Optional[str] = None
13    is_active: bool = True
14    created_at: datetime
15
16# Define Post model
17class Post(BaseModel, ModelMixin):
18    id: int
19    title: str
20    content: str
21    author_id: int  # Foreign key to User.id
22    published: bool = False
23    created_at: datetime
24    updated_at: Optional[datetime] = None
25
26# Initialize database connection
27def create_database():
28    """Create database and tables"""
29    # Using SQLite for this example (no server required)
30    db = Akron("sqlite:///blog.db")
31    
32    # Create tables
33    print("Creating database tables...")
34    User.create_table(db)
35    Post.create_table(db)
36    
37    print("✓ Database tables created successfully!")
38    return db
39
40if __name__ == "__main__":
41    db = create_database()
42    print("Blog application initialized!")

Run the script to create your database:

1python blog_app.py

Expected Output

Creating database tables...
✓ Database tables created successfully!
Blog application initialized!

Step 3: Add Sample Data

Insert Users and Posts

Let's add some sample data to our blog application:

Add to blog_app.py - Sample Data

1def seed_data(db):
  """Add sample users and posts"""
  print("Adding sample data...")
  
  # Create sample users
  alice = User(
      id=1,
      username="alice",
      email="alice@example.com",
      full_name="Alice Johnson",
      created_at=datetime.now()
  )
  
  bob = User(
      id=2,
      username="bob", 
      email="bob@example.com",
      full_name="Bob Smith",
      created_at=datetime.now()
  )
  
  # Insert users
  User.insert(db, alice)
  User.insert(db, bob)
  print("✓ Users created")
  
  # Create sample posts
  post1 = Post(
      id=1,
      title="Welcome to My Blog",
      content="This is my first post using Akron ORM! It's amazing how easy it is to work with databases.",
      author_id=1,  # Alice's post
      published=True,
      created_at=datetime.now()
  )
  
  post2 = Post(
      id=2,
      title="Database Magic with Akron",
      content="Akron ORM makes database operations so simple. No more complex SQL queries!",
      author_id=2,  # Bob's post
      published=True,
      created_at=datetime.now()
  )
  
  post3 = Post(
      id=3,
      title="Draft Post",
      content="This post is still being written...",
      author_id=1,  # Alice's draft
      published=False,
      created_at=datetime.now()
  )
  
  # Insert posts
  Post.insert(db, post1)
  Post.insert(db, post2)
  Post.insert(db, post3)
  print("✓ Posts created")
  
  print("Sample data added successfully!")
62
63# Update the main section
64if __name__ == "__main__":
  db = create_database()
  seed_data(db)
  print("\nBlog application ready!")

Run the updated script:

1python blog_app.py

Expected Output

Creating database tables...
✓ Database tables created successfully!
Adding sample data...
✓ Users created
✓ Posts created
Sample data added successfully!

Blog application ready!

Step 4: Query and Display Data

Read Operations

Now let's add functions to query and display our blog data:

Add to blog_app.py - Query Functions

1def display_blog_stats(db):
  """Display blog statistics"""
  print("\n" + "="*50)
  print("BLOG STATISTICS")
  print("="*50)
  
  # Count total users
  all_users = User.select(db)
  print(f"Total Users: {len(all_users)}")
  
  # Count total posts
  all_posts = Post.select(db)
  print(f"Total Posts: {len(all_posts)}")
  
  # Count published posts
  published_posts = Post.select(db, where={"published": True})
  print(f"Published Posts: {len(published_posts)}")
  
  # Count draft posts
  draft_posts = Post.select(db, where={"published": False})
  print(f"Draft Posts: {len(draft_posts)}")
22
23def display_users(db):
  """Display all users"""
  print("\n" + "="*50)
  print("USERS")
  print("="*50)
  
  users = User.select(db)
  for user in users:
      status = "Active" if user.is_active else "Inactive"
      print(f"[{user.id}] {user.username} ({user.full_name})")
      print(f"    Email: {user.email}")
      print(f"    Status: {status}")
      print(f"    Joined: {user.created_at.strftime('%Y-%m-%d')}")
      print()
37
38def display_posts(db, published_only=False):
  """Display posts"""
  title = "PUBLISHED POSTS" if published_only else "ALL POSTS"
  print("\n" + "="*50)
  print(title)
  print("="*50)
  
  if published_only:
      posts = Post.select(db, where={"published": True})
  else:
      posts = Post.select(db)
  
  for post in posts:
      # Get author information
      author = User.find(db, {"id": post.author_id})
      author_name = author.username if author else "Unknown"
      
      status = "✓ Published" if post.published else "✏ Draft"
      print(f"[{post.id}] {post.title}")
      print(f"    Author: {author_name}")
      print(f"    Status: {status}")
      print(f"    Created: {post.created_at.strftime('%Y-%m-%d %H:%M')}")
      print(f"    Content: {post.content[:100]}{'...' if len(post.content) > 100 else ''}")
      print()
62
63def search_posts(db, keyword):
  """Search posts by keyword in title or content"""
  print(f"\n" + "="*50)
  print(f"SEARCH RESULTS FOR: '{keyword}'")
  print("="*50)
  
  all_posts = Post.select(db)
  matching_posts = [
      post for post in all_posts 
      if keyword.lower() in post.title.lower() or keyword.lower() in post.content.lower()
  ]
  
  if matching_posts:
      for post in matching_posts:
          author = User.find(db, {"id": post.author_id})
          author_name = author.username if author else "Unknown"
          print(f"[{post.id}] {post.title} by {author_name}")
          print(f"    {post.content[:150]}{'...' if len(post.content) > 150 else ''}")
          print()
  else:
      print("No posts found matching your search.")
84
85# Update the main section
86if __name__ == "__main__":
  db = create_database()
  seed_data(db)
  
  # Display blog data
  display_blog_stats(db)
  display_users(db)
  display_posts(db, published_only=True)
  search_posts(db, "Akron")
  
  print("\nBlog application demo complete!")

Run the complete application:

1python blog_app.py

Expected Output

Creating database tables...
✓ Database tables created successfully!
Adding sample data...
✓ Users created
✓ Posts created
Sample data added successfully!

==================================================
BLOG STATISTICS
==================================================
Total Users: 2
Total Posts: 3
Published Posts: 2
Draft Posts: 1

==================================================
USERS
==================================================
[1] alice (Alice Johnson)
    Email: alice@example.com
    Status: Active
    Joined: 2024-01-15

[2] bob (Bob Smith)
    Email: bob@example.com
    Status: Active
    Joined: 2024-01-15

==================================================
PUBLISHED POSTS
==================================================
[1] Welcome to My Blog
    Author: alice
    Status: ✓ Published
    Created: 2024-01-15 10:30
    Content: This is my first post using Akron ORM! It's amazing how easy it is to work with databases.

[2] Database Magic with Akron
    Author: bob
    Status: ✓ Published
    Created: 2024-01-15 10:30
    Content: Akron ORM makes database operations so simple. No more complex SQL queries!

==================================================
SEARCH RESULTS FOR: 'Akron'
==================================================
[1] Welcome to My Blog by alice
    This is my first post using Akron ORM! It's amazing how easy it is to work with databases.

[2] Database Magic with Akron by bob
    Akron ORM makes database operations so simple. No more complex SQL queries!

Blog application demo complete!

Step 5: Update and Delete Operations

Modify Your Data

Let's add functions to update and delete blog data:

Add to blog_app.py - Update/Delete Functions

1def update_post(db, post_id, title=None, content=None, published=None):
  """Update a blog post"""
  print(f"\nUpdating post {post_id}...")
  
  # Prepare update data
  update_data = {"updated_at": datetime.now()}
  if title:
      update_data["title"] = title
  if content:
      update_data["content"] = content
  if published is not None:
      update_data["published"] = published
  
  # Update the post
  result = Post.update(db, {"id": post_id}, update_data)
  
  if result:
      print(f"✓ Post {post_id} updated successfully!")
      
      # Show updated post
      updated_post = Post.find(db, {"id": post_id})
      if updated_post:
          print(f"  Title: {updated_post.title}")
          print(f"  Published: {updated_post.published}")
          print(f"  Updated: {updated_post.updated_at}")
  else:
      print(f"✗ Failed to update post {post_id}")
28
29def publish_draft(db, post_id):
  """Publish a draft post"""
  print(f"\nPublishing post {post_id}...")
  
  post = Post.find(db, {"id": post_id})
  if not post:
      print(f"✗ Post {post_id} not found")
      return
  
  if post.published:
      print(f"Post '{post.title}' is already published")
      return
  
  # Publish the post
  Post.update(db, {"id": post_id}, {
      "published": True,
      "updated_at": datetime.now()
  })
  
  print(f"✓ Post '{post.title}' published successfully!")
49
50def delete_post(db, post_id):
  """Delete a blog post"""
  print(f"\nDeleting post {post_id}...")
  
  # Get post details before deletion
  post = Post.find(db, {"id": post_id})
  if not post:
      print(f"✗ Post {post_id} not found")
      return
  
  # Delete the post
  result = Post.delete(db, {"id": post_id})
  
  if result:
      print(f"✓ Post '{post.title}' deleted successfully!")
  else:
      print(f"✗ Failed to delete post {post_id}")
67
68def create_new_post(db, title, content, author_id, published=False):
  """Create a new blog post"""
  print(f"\nCreating new post: '{title}'...")
  
  # Get next available ID
  all_posts = Post.select(db)
  next_id = max([post.id for post in all_posts], default=0) + 1
  
  # Create new post
  new_post = Post(
      id=next_id,
      title=title,
      content=content,
      author_id=author_id,
      published=published,
      created_at=datetime.now()
  )
  
  # Insert the post
  result = Post.insert(db, new_post)
  
  if result:
      print(f"✓ Post '{title}' created successfully!")
      return next_id
  else:
      print(f"✗ Failed to create post '{title}'")
      return None
95
96# Interactive demo function
97def run_interactive_demo(db):
  """Run an interactive demo of CRUD operations"""
  print("\n" + "="*60)
  print("INTERACTIVE CRUD OPERATIONS DEMO")
  print("="*60)
  
  # 1. Create a new post
  new_post_id = create_new_post(
      db, 
      title="My Python Journey",
      content="Learning Python has been an incredible experience. From basic syntax to advanced frameworks like Akron ORM, every step has been exciting!",
      author_id=1,  # Alice
      published=False  # Start as draft
  )
  
  # 2. Update the post content
  if new_post_id:
      update_post(
          db,
          new_post_id,
          content="Learning Python has been an incredible experience. From basic syntax to advanced frameworks like Akron ORM, every step has been exciting! I particularly love how Akron makes database operations so intuitive.",
          published=False
      )
  
  # 3. Publish the draft
  if new_post_id:
      publish_draft(db, new_post_id)
  
  # 4. Show current stats
  display_blog_stats(db)
  
  # 5. Delete the demo post
  if new_post_id:
      delete_post(db, new_post_id)
  
  # 6. Final stats
  print("\nFinal statistics after cleanup:")
  display_blog_stats(db)
135
136# Update the main section
137if __name__ == "__main__":
  db = create_database()
  seed_data(db)
  
  # Run basic demo
  display_blog_stats(db)
  display_posts(db, published_only=True)
  
  # Run interactive CRUD demo
  run_interactive_demo(db)
  
  print("\n" + "="*60)
  print("✓ Quick Start Demo Complete!")
  print("="*60)
  print("Next steps:")
  print("• Try different database types (MySQL, PostgreSQL, MongoDB)")
  print("• Explore the CLI commands")
  print("• Check out the full API documentation")
  print("• Build your own application!")

Run the complete demo:

1python blog_app.py

Expected Output

Creating database tables...
✓ Database tables created successfully!
Adding sample data...
✓ Users created
✓ Posts created
Sample data added successfully!

==================================================
BLOG STATISTICS
==================================================
Total Users: 2
Total Posts: 3
Published Posts: 2
Draft Posts: 1

============================================================
INTERACTIVE CRUD OPERATIONS DEMO
============================================================

Creating new post: 'My Python Journey'...
✓ Post 'My Python Journey' created successfully!

Updating post 4...
✓ Post 4 updated successfully!
  Title: My Python Journey
  Published: False
  Updated: 2024-01-15 10:30:45.123456

Publishing post 4...
✓ Post 'My Python Journey' published successfully!

==================================================
BLOG STATISTICS
==================================================
Total Users: 2
Total Posts: 4
Published Posts: 3
Draft Posts: 1

Deleting post 4...
✓ Post 'My Python Journey' deleted successfully!

Final statistics after cleanup:
==================================================
BLOG STATISTICS
==================================================
Total Users: 2
Total Posts: 3
Published Posts: 2
Draft Posts: 1

============================================================
✓ Quick Start Demo Complete!
============================================================
Next steps:
• Try different database types (MySQL, PostgreSQL, MongoDB)
• Explore the CLI commands
• Check out the full API documentation
• Build your own application!

Step 6: Using the CLI

Command-Line Interface

Akron also provides a powerful CLI for database operations. Let's explore some commands:

CLI Examples

1# Inspect your database schema
2akron inspect-schema --db "sqlite:///blog.db"
3
4# Query data using raw SQL
5akron raw-sql --db "sqlite:///blog.db" --query "SELECT * FROM users"
6
7# Add more users via CLI
8akron seed users --db "sqlite:///blog.db" --data '[
9  {
10    "id": 3,
11    "username": "charlie", 
12    "email": "charlie@example.com",
13    "full_name": "Charlie Brown",
14    "is_active": true,
15    "created_at": "2024-01-15T10:30:00"
16  }
17]'
18
19# Create a new table via CLI
20akron create-table comments --db "sqlite:///blog.db" --schema '{
21  "id": "int",
22  "post_id": "int", 
23  "author_name": "str",
24  "content": "str",
25  "created_at": "str"
26}'
27
28# Verify the new table
29akron inspect-schema --db "sqlite:///blog.db"

Expected Output

Database Schema (SQLite):
=====================================
├── users
│   ├── id (INTEGER)
│   ├── username (TEXT)
│   ├── email (TEXT)
│   ├── full_name (TEXT)
│   ├── is_active (INTEGER)
│   └── created_at (TEXT)
├── posts
│   ├── id (INTEGER)
│   ├── title (TEXT)
│   ├── content (TEXT)
│   ├── author_id (INTEGER)
│   ├── published (INTEGER)
│   ├── created_at (TEXT)
│   └── updated_at (TEXT)
└── comments
    ├── id (INTEGER)
    ├── post_id (INTEGER)
    ├── author_name (TEXT)
    ├── content (TEXT)
    └── created_at (TEXT)

✓ User added successfully
✓ Table 'comments' created successfully

Try Different Databases

Same Code, Different Databases

The beauty of Akron is that you can use the same code with different databases. Just change the connection string:

Database Variations

1# Try with PostgreSQL (if you have it running)
2# db = Akron("postgres://user:password@localhost:5432/blog")
3
4# Try with MySQL (if you have it running)  
5# db = Akron("mysql://user:password@localhost:3306/blog")
6
7# Try with MongoDB (if you have it running)
8# db = Akron("mongodb://localhost:27017/blog")
9
10# For production, use environment variables
11import os
12db_url = os.getenv("DATABASE_URL", "sqlite:///blog.db")
13db = Akron(db_url)

🔄 Database Portability

Your models and operations work identically across all databases:

• Same Python code for all database types
• Automatic type conversion and mapping
• Consistent API across SQL and NoSQL databases
• Easy migration between database systems

Complete Application Code

Final blog_app.py

Here's the complete code for your blog application:

Complete blog_app.py

1"""
2Simple Blog Application using Akron ORM
3A complete example demonstrating CRUD operations and best practices.
4"""
5
6from akron import Akron
7from pydantic import BaseModel
8from akron.models import ModelMixin
9from datetime import datetime
10from typing import Optional
11import os
12
13# Data Models
14class User(BaseModel, ModelMixin):
  id: int
  username: str
  email: str
  full_name: Optional[str] = None
  is_active: bool = True
  created_at: datetime
21
22class Post(BaseModel, ModelMixin):
  id: int
  title: str
  content: str
  author_id: int
  published: bool = False
  created_at: datetime
  updated_at: Optional[datetime] = None
30
31def get_database():
  """Get database connection"""
  db_url = os.getenv("DATABASE_URL", "sqlite:///blog.db")
  return Akron(db_url)
35
36def setup_database():
  """Initialize database and tables"""
  db = get_database()
  User.create_table(db)
  Post.create_table(db)
  return db
42
43def create_sample_data(db):
  """Create sample users and posts"""
  # Add users
  users = [
      User(id=1, username="alice", email="alice@example.com", 
           full_name="Alice Johnson", created_at=datetime.now()),
      User(id=2, username="bob", email="bob@example.com",
           full_name="Bob Smith", created_at=datetime.now())
  ]
  
  for user in users:
      User.insert(db, user)
  
  # Add posts
  posts = [
      Post(id=1, title="Welcome to Akron", 
           content="Getting started with Akron ORM is super easy!",
           author_id=1, published=True, created_at=datetime.now()),
      Post(id=2, title="Database Magic",
           content="Akron works with SQLite, MySQL, PostgreSQL, and MongoDB!",
           author_id=2, published=True, created_at=datetime.now()),
      Post(id=3, title="Work in Progress",
           content="This post is still being written...",
           author_id=1, published=False, created_at=datetime.now())
  ]
  
  for post in posts:
      Post.insert(db, post)
71
72def show_blog_summary(db):
  """Display blog summary"""
  users = User.select(db)
  all_posts = Post.select(db)
  published_posts = Post.select(db, where={"published": True})
  
  print("\n🏠 BLOG SUMMARY")
  print("=" * 40)
  print(f"Users: {len(users)}")
  print(f"Total Posts: {len(all_posts)}")
  print(f"Published: {len(published_posts)}")
  print(f"Drafts: {len(all_posts) - len(published_posts)}")
  
  print("\n📝 RECENT POSTS")
  print("-" * 40)
  for post in published_posts:
      author = User.find(db, {"id": post.author_id})
      print(f"• {post.title} by {author.username if author else 'Unknown'}")
90
91if __name__ == "__main__":
  print("🚀 Akron Blog Application")
  print("=" * 50)
  
  # Setup
  db = setup_database()
  create_sample_data(db)
  
  # Demo
  show_blog_summary(db)
  
  print("\n✅ Application ready!")
  print("\nNext steps:")
  print("• Modify the code to add your own features")
  print("• Try different database connections") 
  print("• Explore the Akron CLI commands")
  print("• Check out the full documentation")

🎉 Congratulations!

You've successfully built your first Akron application! You now know how to:

✅ What You've Learned

• Install and configure Akron ORM
• Define data models with Pydantic
• Create database tables
• Perform CRUD operations
• Use both Python API and CLI
• Handle relationships between tables

🎯 Key Concepts

• Universal database connectivity
• Type-safe model definitions
• Consistent API across databases
• Automatic schema management
• Easy data validation
• Simple migration handling

Next Steps

Basic Usage Guide

Deep dive into Akron's features and best practices

API Reference

Complete documentation for all Akron methods

CLI Commands

Learn all command-line tools and utilities

Database Guides

Database-specific features and optimizations