From e68d965baeecda145aef72b43efdde970dfe8157 Mon Sep 17 00:00:00 2001 From: Shayan Khorsandi Date: Mon, 9 Feb 2026 14:55:04 -0800 Subject: [PATCH 1/5] docs: add backend README with setup instructions Add backend/README.md documenting how to run and configure the backend service. Includes prerequisites (Java 17, Maven), required databases (Oracle and PostgreSQL), environment variables (PRIMARY_DB, FLYWAY_ENVIRONMENT), examples for running with Oracle/Postgres, Maven wrapper run command, application.yml primary-db setting, Flyway migration locations (dev vs prod), and test commands for both databases. --- backend/README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 backend/README.md diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 000000000..94dca0553 --- /dev/null +++ b/backend/README.md @@ -0,0 +1,87 @@ +# Backend Service + +This document provides instructions to run the backend service and configure it for different database environments (Oracle and PostgreSQL). + +--- + +## Prerequisites + +1. **Java**: Ensure Java 17 is installed. +2. **Maven**: Install Maven (or use the provided `mvnw` wrapper). +3. **Databases**: + - Oracle Database (if using Oracle as the primary database). + - PostgreSQL Database (Required even when running Oracle as the primary as it is used to save user preferences.) +4. **Environment Variables**: + - `PRIMARY_DB`: Specifies the primary database (`oracle` or `postgres`). + - `FLYWAY_ENVIRONMENT`: Specifies the Flyway migration environment (`dev`, `prod`). + +--- + +## Running the Backend + +### 1. Clone the Repository +```bash +git clone +cd nr-silva/backend +``` + +### 2. Set Environment Variables + +#### Example for Oracle: +```bash +export PRIMARY_DB=oracle +export FLYWAY_ENVIRONMENT=dev +``` + +#### Example for PostgreSQL: +```bash +export PRIMARY_DB=postgres +export FLYWAY_ENVIRONMENT=dev +``` + +### 3. Run the Application + +Using Maven Wrapper: +```bash +./mvnw spring-boot:run +``` + +--- + +## Configuration + +### 1. Database Configuration + +The backend uses the `application.yml` file for database configuration. The `server.primary-db` property determines the primary database. + +```yaml +server: + primary-db: ${PRIMARY_DB:oracle} +``` + +### 2. Flyway Migrations + +Flyway migrations are environment-specific and determined by the `FLYWAY_ENVIRONMENT` variable. + +- **Development Migrations**: Located in `src/main/resources/db/migration-dev/`. +- **Production Migrations**: Located in `src/main/resources/db/migration/`. + +--- + +## Testing + +### Run Tests for Oracle: +```bash +./mvnw clean install -Dflyway-environment=dev -Dserver.primary-db=oracle +``` + +### Run Tests for PostgreSQL: +```bash +./mvnw clean install -Dflyway-environment=dev -Dserver.primary-db=postgres +``` + +--- + +## Notes + +- Ensure the database is running and accessible before starting the backend. From e4dd457a173290e441fc5ee8f0be94492044235a Mon Sep 17 00:00:00 2001 From: Shayan Khorsandi Date: Mon, 9 Feb 2026 16:40:55 -0800 Subject: [PATCH 2/5] docs: update backend/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- backend/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backend/README.md b/backend/README.md index 94dca0553..9b74d991e 100644 --- a/backend/README.md +++ b/backend/README.md @@ -22,7 +22,7 @@ This document provides instructions to run the backend service and configure it ### 1. Clone the Repository ```bash git clone -cd nr-silva/backend +cd /backend ``` ### 2. Set Environment Variables From ab17d300a7ccfbed44e698a46c0f21774b98cd04 Mon Sep 17 00:00:00 2001 From: Shayan Khorsandi Date: Mon, 9 Feb 2026 16:43:17 -0800 Subject: [PATCH 3/5] docs: update backend/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- backend/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backend/README.md b/backend/README.md index 9b74d991e..0faaa8854 100644 --- a/backend/README.md +++ b/backend/README.md @@ -10,7 +10,7 @@ This document provides instructions to run the backend service and configure it 2. **Maven**: Install Maven (or use the provided `mvnw` wrapper). 3. **Databases**: - Oracle Database (if using Oracle as the primary database). - - PostgreSQL Database (Required even when running Oracle as the primary as it is used to save user preferences.) + - PostgreSQL Database (always required; used to store user preferences, even when Oracle is configured as the primary database). 4. **Environment Variables**: - `PRIMARY_DB`: Specifies the primary database (`oracle` or `postgres`). - `FLYWAY_ENVIRONMENT`: Specifies the Flyway migration environment (`dev`, `prod`). From b94b419064ac34d6afaea7b19ff25fd5dfc7f533 Mon Sep 17 00:00:00 2001 From: Shayan Khorsandi Date: Mon, 9 Feb 2026 16:44:00 -0800 Subject: [PATCH 4/5] docs: update backend/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- backend/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/backend/README.md b/backend/README.md index 0faaa8854..980cf5697 100644 --- a/backend/README.md +++ b/backend/README.md @@ -61,10 +61,11 @@ server: ### 2. Flyway Migrations -Flyway migrations are environment-specific and determined by the `FLYWAY_ENVIRONMENT` variable. +Flyway migrations are determined by the `FLYWAY_ENVIRONMENT` variable. -- **Development Migrations**: Located in `src/main/resources/db/migration-dev/`. -- **Production Migrations**: Located in `src/main/resources/db/migration/`. +- **Shared/Baseline Migrations**: Located in `src/main/resources/db/migration/`. These migrations are applied in all environments (including `prod` and non-`prod`). +- **Development-Only Migrations**: Located in `src/main/resources/db/migration-dev/`. For non-`prod` values of `FLYWAY_ENVIRONMENT` (for example, `dev`), Flyway loads migrations from **both** `db/migration/` and `db/migration-dev/`. +- **Production Environment**: When `FLYWAY_ENVIRONMENT=prod`, only the shared/baseline migrations in `src/main/resources/db/migration/` are applied. --- From b3c7108573481e8e0192595a822eefb068cd4bbc Mon Sep 17 00:00:00 2001 From: Shayan Khorsandi Date: Tue, 10 Feb 2026 15:45:42 -0800 Subject: [PATCH 5/5] docs: add local PostgreSQL test data loading docs Add a section to backend/README.md explaining how to load test data into a local PostgreSQL environment. The new text points to ora2pg/tools/README.md for detailed instructions on combining migration files and importing them into the database, making it easier for developers to populate local dev databases for testing. --- backend/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/backend/README.md b/backend/README.md index 980cf5697..d188e4bf7 100644 --- a/backend/README.md +++ b/backend/README.md @@ -81,6 +81,10 @@ Flyway migrations are determined by the `FLYWAY_ENVIRONMENT` variable. ./mvnw clean install -Dflyway-environment=dev -Dserver.primary-db=postgres ``` +### Loading Test Data on Local PostgreSQL Environment + +To load test data into your local PostgreSQL environment, you can use the tools provided in the [`ora2pg/tools/README.md`](../ora2pg/tools/README.md) file. This document provides detailed instructions on combining migration files and loading them into your PostgreSQL database. + --- ## Notes