Start Server in development environment

Running Actix + SQLx Backend via Docker Compose

This guide describes how to set up and run a Rust (Actix Web + SQLx) backend with PostgreSQL using Docker Compose.

1. Start the PostgreSQL service

1.1 Start PostgreSQL container:

docker compose up -d db --build

• Image: postgres:latest
• Default port: 5432
• Default username: postgres
• Default password: postgres
• Default database: aihub

---

2. Configure database connection

2.1 Set the DATABASE_URL for your current shell session:

export DATABASE_URL=postgres://postgres:postgres@localhost:5432/aihub

This variable will be lost after the shell session ends. When running inside Docker, the host should be db instead of localhost.

Format:

postgres://<username>:<password>@<host>:<port>/<database_name>

---

3. Install SQLx CLI

cargo install sqlx-cli --no-default-features --features native-tls,postgres

Required for creating migrations, running them, and generating offline query cache.

---

4. Create migration files

4.1 Create a new migration file with a timestamp:

sqlx migrate add init

• Run this in the same directory as Cargo.toml.
• The migration files will be stored in the ./migrations directory.

4.2 Edit the generated .sql file to add your SQL schema.

---

5. Create the database

sqlx database create

This creates the aihub database specified in DATABASE_URL.

---

6. Run migrations

sqlx migrate run

Applies all pending migrations to your database.

---

7. Generate SQLx offline cache (optional but recommended)

If you use:

• SQLX_OFFLINE=true in your shell session, or
• ENV SQLX_OFFLINE=true in your Dockerfile

You must generate the offline cache before building the Docker image:

cargo sqlx prepare -- --bin aihub

This will create the .sqlx/ directory containing the query metadata required for offline builds.

---

8. Start the API service

docker compose up api --build

This will build and run the backend service defined in docker-compose.yml.

---

Notes & Common Pitfalls

• Local vs. Docker network: When running inside Docker, use db (the Docker Compose service name) as the database host instead of localhost.

• SQLx offline mode: If you forget to run cargo sqlx prepare before building with SQLX_OFFLINE=true, the build will fail with "no .sqlx data found".

• Rebuilding after migrations: If your SQL schema changes, regenerate the offline cache before rebuilding the Docker image.

• Multiple environments: For development, use a .env.dev file and load it with dotenv or env_file in docker-compose.yml.

---

Via shell, laod env variables only for the progress by cargo run

fish shell: env (cat .env.dev | grep -v '^#' | xargs) && cargo run

bash shell: export $(grep -v '^#' .env.dev | xargs) && cargo run

bash shell: export $(grep -v '^#' .env.dev | xargs) && cargo run

Connect lcoal database

command: psql progresql://progresql:progresql@localhost:5432/aihub Inside Docker: docker exec -it aihub-db-1 psql -U postgres -d aihub