Skip to main content

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.

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

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/Shipfastai
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.

​
Connection pool settings

SQLAlchemy maintains a pool of reusable database connections. Two variables control its size:
VariableDefaultDescription
DATABASE_POOL_SIZE5Number of connections kept open at all times.
DATABASE_MAX_OVERFLOW10Additional 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.
.env
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20
Pool settings are ignored when DATABASE_URL starts with sqlite://. SQLite does not support connection pooling.

​
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: 
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. 
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.
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.
To connect to the database directly while Docker Compose is running: 
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).