> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipfastai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Database setup and connection configuration

> Configure PostgreSQL with SQLAlchemy, tune connection pooling, and run Alembic migrations for your Shipfastai app locally and in production.

Shipfastai uses PostgreSQL as its primary database, accessed through SQLAlchemy with connection pooling enabled. You configure the connection via the `DATABASE_URL` environment variable. When developing locally, Docker Compose spins up a PostgreSQL instance for you automatically — no manual installation required.

## Connection string

Set `DATABASE_URL` to a standard PostgreSQL connection string in your `.env` file:

```
postgresql://user:password@host:port/dbname
```

<CodeGroup>
  ```bash Local development theme={null}
  DATABASE_URL=postgresql://postgres:postgres@localhost:5432/Shipfastai
  ```

  ```bash Railway theme={null}
  DATABASE_URL=postgresql://postgres:RaNdOmPaSsWoRd@containers-us-west-123.railway.app:6543/railway
  ```

  ```bash Supabase (direct) theme={null}
  DATABASE_URL=postgresql://postgres:your-password@db.xxxxxxxxxxxx.supabase.co:5432/postgres
  ```
</CodeGroup>

<Note>
  When using Docker Compose for local development, the backend container connects to the `db` service using `postgresql://postgres:postgres@db:5432/Shipfastai`. The `.env` file value is overridden by the `environment` block in `docker-compose.yml`.
</Note>

## Connection pool settings

SQLAlchemy maintains a pool of reusable database connections. Two variables control its size:

| Variable                | Default | Description                                                                                                        |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `DATABASE_POOL_SIZE`    | `5`     | Number of connections kept open at all times.                                                                      |
| `DATABASE_MAX_OVERFLOW` | `10`    | Additional connections allowed when the pool is exhausted. Maximum total connections = `POOL_SIZE + MAX_OVERFLOW`. |

The defaults work well for most small-to-medium deployments. Increase `DATABASE_POOL_SIZE` when you observe connection wait times under sustained load, or when your hosting provider offers a larger connection limit.

```bash .env theme={null}
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20
```

<Note>
  Pool settings are ignored when `DATABASE_URL` starts with `sqlite://`. SQLite does not support connection pooling.
</Note>

## Running migrations

Shipfastai manages database schema changes through migration scripts. After setting up your environment, apply any pending migrations by running the following from the `backend/` directory of your tier:

```bash theme={null}
cd products/basic/backend
alembic upgrade head
```

Run this command whenever you pull an update that includes new migration files.

## Using Docker

When you start the application with Docker Compose, PostgreSQL is provisioned automatically. You do not need a local PostgreSQL installation.

```bash theme={null}
docker compose up
```

The `docker-compose.yml` file defines a `db` service running `postgres:15-alpine` on port `5432`. The backend service declares a `depends_on` health check, so it will not start until PostgreSQL is ready.

<Note>
  Docker Compose handles the database for local development. You still need to run `alembic upgrade head` on first start or after pulling new migrations. The Docker entrypoint does not run migrations automatically.
</Note>

To connect to the database directly while Docker Compose is running:

```bash theme={null}
docker exec -it <project-name>-db-1 psql -U postgres -d Shipfastai
```

Replace `<project-name>` with your Docker Compose project name (by default, the directory name).