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

> Explore 3 methods to set up a database for local development in Akash Console. Learn to provision sandbox databases, connect existing instances, or restore from backups.

- Repository: [Akash Network/console](https://github.com/akash-network/console)
- Tags: how-to-guide
- Published: 2026-02-24

---

**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`](https://github.com/akash-network/console/blob/main/dc.sh) helper script processes [`docker-compose.dev.yml`](https://github.com/akash-network/console/blob/main/docker-compose.dev.yml) and starts a `db` service. The container executes [`packages/docker/script/prepare-and-seed-postgres.sh`](https://github.com/akash-network/console/blob/main/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:

```bash

# 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:

```bash

# 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:

```dotenv

# 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`](https://github.com/akash-network/console/blob/main/apps/api/src/core/providers/postgres.provider.ts) consumes these variables via the Zod-validated configuration in [`env.config.ts`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/README.md). Download and restore a backup using standard PostgreSQL tools:

```bash

# 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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/docker-compose.dev.yml)【1†L14-L20】.

When the Docker database starts, it executes [`packages/docker/script/prepare-and-seed-postgres.sh`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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.