Setting Up a Database for Local Development in Akash Console: 3 Proven Methods

Akash Console supports three interchangeable PostgreSQL setups for local development: letting Docker Compose automatically provision and seed a sandbox database, connecting to an existing local PostgreSQL instance via the --no-db flag, or manually restoring from a production backup dump.

Setting up a database for local development in Akash Console requires configuring PostgreSQL to support the API, indexer, and web applications. The akash-network/console repository provides flexible infrastructure-as-code configurations that accommodate different development workflows, from fully containerized environments to external database connections.

Option 1: Let Docker Compose Spin Up PostgreSQL Automatically

The default development mode uses Docker Compose to create a fully configured PostgreSQL container with pre-seeded sandbox data.

How the Automated Docker DB Works

When you run the development command, the dc.sh helper script processes docker-compose.dev.yml and starts a db service. The container executes packages/docker/script/prepare-and-seed-postgres.sh, which:

1. Creates databases listed in the POSTGRES_DBS environment variable
2. Imports the sandbox backup unless POSTGRES_SKIP_IMPORT=true is set
3. Configures schemas required by the API and indexer

The credentials and database names are sourced from packages/docker/.env.sandbox.docker-compose-dev, which defines variables like POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DBS_FOR_IMPORT.

Starting the Development Environment

Use the helper script or npm shortcuts to launch all services including the database:

# Using the dc.sh helper script

./dc.sh up:dev

# Or using the npm shortcut

npm run dc:up:dev

This command blocks until the database is ready and seeded, making it the fastest way for new developers to obtain a working sandbox environment.

Option 2: Connect to a Local PostgreSQL Instance (No-DB Mode)

For developers who prefer to run PostgreSQL natively or need to connect to an existing server, Akash Console supports a "no-db" mode that excludes the Docker database container.

Configuring the Connection

Start the services with the --no-db flag or set SKIP_DC_DB=true to remove the db service from the compose graph:

# Using the helper script with the no-db flag

./dc.sh up:dev --no-db

# Or using the npm shortcut that sets the environment variable

npm run console:dev:no-db

In this mode, the API, indexer, and other services expect to find a PostgreSQL instance at a host-accessible address.

Environment Variables Setup

Create an apps/api/env/.env.local file (or modify your loaded environment) to provide connection strings:

# Primary user database

POSTGRES_DB_URI=postgres://postgres:password@localhost:5432/console-users

# Chain indexer database (sandbox or mainnet)

CHAIN_INDEXER_POSTGRES_DB_URI=postgres://postgres:password@localhost:5432/console-akash-sandbox

The application code in apps/api/src/core/providers/postgres.provider.ts consumes these variables via the Zod-validated configuration in env.config.ts, instantiating the postgres client with the provided URI.

Option 3: Restore From a Production Backup

When you need a specific data snapshot—such as the latest mainnet state—or want to persist data outside Docker containers, you can manually restore from public database dumps.

Downloading and Importing Backups

The repository provides public backup URLs documented in the top-level README.md. Download and restore a backup using standard PostgreSQL tools:

# Download the sandbox backup

curl -O https://storage.googleapis.com/console-postgresql-backups/console-akash-sandbox.sql.gz

# Restore into a local database named "console-akash"

gunzip -c console-akash-sandbox.sql.gz | \
  psql --host localhost --port 5432 --username postgres --dbname console-akash

After restoration, configure the services to use this database by setting POSTGRES_DB_URI (and related variables) to point to the restored database, following the same pattern as Option 2.

How Database Configuration Works Under the Hood

Understanding the internal wiring helps troubleshoot connection issues and customize setups.

The dc.sh script located in packages/docker/ acts as the primary entry point. It processes the --no-db flag to conditionally include or exclude the db service from docker-compose.dev.yml【1†L14-L20】.

When the Docker database starts, it executes packages/docker/script/prepare-and-seed-postgres.sh. This shell script reads POSTGRES_DBS (a comma-separated list) to create databases, then checks POSTGRES_DBS_FOR_IMPORT to determine which backups to import unless POSTGRES_SKIP_IMPORT is set to true【3†L3-L35】.

At runtime, the API server loads database configuration through apps/api/src/core/providers/postgres.provider.ts, which validates environment variables like POSTGRES_DB_URI using Zod schemas defined in the configuration layer【4†L13-L30】. This provider instantiates the postgres client that the indexer and API services use to execute queries.

Summary

• Docker-managed database: Run ./dc.sh up:dev for the fastest setup with automatic seeding via prepare-and-seed-postgres.sh and packages/docker/.env.sandbox.docker-compose-dev.
• External PostgreSQL: Use ./dc.sh up:dev --no-db or npm run console:dev:no-db with POSTGRES_DB_URI configured in apps/api/env/.env.local to connect to a native PostgreSQL installation.
• Backup restoration: Download public dumps from Google Cloud Storage and restore with gunzip | psql, then point services to the restored database using standard environment variables.

Frequently Asked Questions

Can I use MySQL or another database instead of PostgreSQL?

No. The Akash Console codebase is tightly coupled to PostgreSQL. The postgres client is hardcoded in apps/api/src/core/providers/postgres.provider.ts, and SQL migrations use PostgreSQL-specific syntax. You must use PostgreSQL version 14 or higher for compatibility with the schema definitions.

How do I reset the database to a clean state?

When using the Docker-managed option, run ./dc.sh down:dev to remove all containers and volumes, then ./dc.sh up:dev again. This re-runs prepare-and-seed-postgres.sh and re-imports the sandbox backup. For external databases, drop and recreate the databases manually, or restore from a fresh backup dump.

Where are the database backups stored and how current are they?

Public backups are hosted on Google Cloud Storage at storage.googleapis.com/console-postgresql-backups/. The repository typically provides console-akash-sandbox.sql.gz and console-akash-mainnet.sql.gz. According to the README.md, these dumps are generated periodically from production snapshots, though you should check the repository's latest documentation for the exact refresh schedule.

Do I need to run migrations manually when using the Docker setup?

No. When using the Docker-managed database, the prepare-and-seed-postgres.sh script handles schema creation and data seeding automatically when the container starts. The API and indexer services will connect to an already-initialized database. However, if you switch to an external database (Option 2), you may need to ensure migrations run depending on how your specific service version handles schema initialization.

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