Where to Find Database Schema Documentation for Akash Console

The definitive database schema documentation for Akash Console resides in the doc/database-structure.md file within the akash-network/console repository, which details every table, relationship, and indexing strategy alongside version-controlled migration scripts in the migrations/ directory.

The akash-network/console repository powers the Akash Console, a web-based interface for deploying workloads on the Akash Network's decentralized cloud marketplace. Understanding the database schema documentation for Akash Console is essential for developers contributing to backend services, building analytics integrations, or troubleshooting deployment lifecycle data.

Primary Documentation Location

The canonical source for schema information is the doc/database-structure.md file located at the repository root. This markdown document serves as the single source of truth for the Console’s persistence layer architecture.

The documentation covers:

• Complete table definitions with column types, constraints, and default values
• Entity relationship diagrams illustrating foreign key dependencies between tables
• Indexing strategies optimized for the Console’s query patterns
• Migration history linking schema changes to specific SQL files

You can view the documentation directly on GitHub: Akash Console Database Structure.

Core Database Entities

The schema centers around five primary entities that manage the Akash Network interaction lifecycle.

Deployments

The deployments table stores every user-initiated deployment request. It tracks the current status of the workload, references the associated lease through lease_id, and maintains created_at and updated_at timestamps for temporal queries.

Leases

The leases table represents the contractual agreement between a tenant and a provider. Critical fields include resource allocation specifications (resource_cpu, resource_memory), pricing terms, expiration dates, and foreign key references to both the provider and the deployment.

Providers

Provider profile data resides in the providers table, including geographic location, attribute capabilities (GPU types, storage classes), and operational status indicators that facilitate provider discovery.

Wallets

The wallets table tracks AKT token balances, transaction histories, and associates blockchain addresses with internal user identifiers through the user_id field.

Audit Logs

For compliance and debugging, the audit_logs table captures every state-changing operation, recording the entity type, entity ID, action performed, and the user responsible for the change.

Relationships and Indexing Strategy

Understanding how these entities connect is crucial for writing efficient queries against the Akash Console database schema.

Entity Relationships

The schema enforces referential integrity through strategic foreign key constraints:

• deployments → leases: One-to-many relationship via lease_id
• leases → providers: Many-to-one relationship via provider_id
• wallets → users: One-to-one relationship via user_id
• audit_logs reference primary keys from all major tables to track modifications

Performance Optimization

The documentation details specific indexing strategies to support the Console's query patterns:

• Composite indexes on (provider_id, status) enable rapid filtering of active leases by specific providers
• Time-based indexes on created_at and updated_at columns across all tables support time-series analytics, such as calculating daily new user counts or lease creation rates
• Foreign key indexes ensure efficient join operations between related entities

Schema Evolution and Migrations

The Akash Console database schema is version-controlled through migration scripts stored in the migrations/ directory at the repository root.

Each migration file represents an incremental change to the schema, allowing the database to evolve without data loss. The doc/database-structure.md file cross-references these migrations, providing links to specific SQL files that created or modified tables.

This approach enables developers to:

• Trace the historical evolution of any table structure
• Understand when specific indexes were added for performance
• Replicate the exact schema state for local development or testing

Querying the Database

The schema documentation includes practical patterns for interacting with the database using both raw SQL and the application's Go-based backend services.

SQL Query Patterns

To retrieve active leases for a specific provider along with their deployment status:

SELECT l.id,
       l.resource_cpu,
       l.resource_memory,
       l.expiration,
       d.status AS deployment_status
FROM   leases l
JOIN   deployments d ON d.lease_id = l.id
WHERE  l.provider_id = $PROVIDER_ID
  AND  l.status = 'active';

This query leverages the composite index on (provider_id, status) for optimal performance.

Application-Level Integration

When working with the Console's Go backend, the deployments table structure maps to structs like this:

type Deployment struct {
    ID          string    `db:"id"`
    UserID      string    `db:"user_id"`
    LeaseID     string    `db:"lease_id"`
    Status      string    `db:"status"`
    CreatedAt   time.Time `db:"created_at"`
    UpdatedAt   time.Time `db:"updated_at"`
}

func CreateDeployment(db *sqlx.DB, d *Deployment) error {
    query := `
        INSERT INTO deployments (id, user_id, lease_id, status, created_at, updated_at)
        VALUES (:id, :user_id, :lease_id, :status, :created_at, :updated_at);
    `
    _, err := db.NamedExec(query, d)
    return err
}

The column names in the struct tags directly correspond to the Deployments table definition in the schema documentation.

Audit Logging Implementation

For compliance tracking, the audit_logs table captures state changes:

func LogAudit(db *sqlx.DB, entity, entityID, action, userID string) error {
    _, err := db.Exec(`
        INSERT INTO audit_logs (entity, entity_id, action, performed_by, timestamp)
        VALUES ($1, $2, $3, $4, NOW())
    `, entity, entityID, action, userID)
    return err
}

Summary

The database schema documentation for Akash Console provides comprehensive guidance for developers working with the platform's persistence layer. Key takeaways include:

• The canonical documentation lives in doc/database-structure.md within the akash-network/console repository
• Five core entities manage the deployment lifecycle: deployments, leases, providers, wallets, and audit_logs
• Strategic indexing on (provider_id, status) and time-based columns optimizes query performance for the Console's workload patterns
• Version-controlled migration scripts in the migrations/ directory track schema evolution and ensure reproducible database states

Frequently Asked Questions

Where is the official database schema documentation for Akash Console located?

The official database schema documentation resides in the doc/database-structure.md file at the root of the akash-network/console GitHub repository. This markdown file contains complete table definitions, entity relationship diagrams, indexing strategies, and links to migration scripts.

What are the main tables in the Akash Console database?

The schema centers around five primary tables: deployments (workload requests and status), leases (provider agreements and resource allocation), providers (infrastructure profiles and capabilities), wallets (AKT balances and transactions), and audit_logs (compliance tracking and state change history).

How does the Akash Console handle database schema migrations?

Schema changes are managed through version-controlled SQL migration scripts stored in the migrations/ directory. Each file represents an incremental schema change, allowing the database to evolve without data loss. The doc/database-structure.md file cross-references these migrations to provide historical context for schema modifications.

What indexing strategies does the Akash Console use for performance?

The database employs composite indexes on (provider_id, status) to accelerate provider-centric queries, time-based indexes on created_at and updated_at columns for analytics, and foreign-key indexes to optimize joins between related entities like deployments, leases, and providers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}