feat: adds Java-based Postgres demo to the library (#816)

* feat: initial creation of java-based postgres demo

Signed-off-by: Anthony D. Mays <[email protected]>

* fix: ensures .env file can be loaded from the right location

Signed-off-by: Anthony D. Mays <[email protected]>

* feat: adds JPA demo

Signed-off-by: Anthony D. Mays <[email protected]>

---------

Signed-off-by: Anthony D. Mays <[email protected]>

Author: anthonydmays

lib/java/postgres_demo/.env.example

@@ -0,0 +1,4 @@
+# Database Configuration
+DB_URL=jdbc:postgresql://localhost:5433/demo_db
+DB_USER=demo_user
+DB_PASSWORD=demo_password

lib/java/postgres_demo/.gitattributes

@@ -0,0 +1,12 @@
+#
+# https://help.github.com/articles/dealing-with-line-endings/
+#
+# Linux start script should use lf
+/gradlew        text eol=lf
+
+# These are Windows script files and should use crlf
+*.bat           text eol=crlf
+
+# Binary files should be left untouched
+*.jar           binary
+

lib/java/postgres_demo/.gitignore

@@ -0,0 +1,6 @@
+# Ignore Gradle project-specific cache directory
+.gradle
+
+# Ignore Gradle build output directory
+build
+.env

lib/java/postgres_demo/README.md

@@ -0,0 +1,212 @@
+# Postgres Demo
+
+A Spring Boot application demonstrating PostgreSQL database connectivity with Flyway migrations, built with Gradle (Kotlin DSL).
+
+## Features
+
+- Spring Boot 3.2.1 application
+- PostgreSQL database connection using Spring Data JDBC
+- Flyway database migrations (managed by Spring Boot)
+- Configuration via `application.yml` with Spring's built-in environment variable support
+- Environment variable support via `.env` files (using spring-dotenv)
+- Docker Compose setup for local PostgreSQL instance
+- Gradle Kotlin DSL build configuration
+
+## Prerequisites
+
+- Java 17 or higher
+- Docker and Docker Compose (for running PostgreSQL)
+- Gradle (wrapper included)
+
+## Project Structure
+
+```
+postgres_demo/
+├── app/
+│   ├── build.gradle.kts          # Gradle build configuration
+│   └── src/
+│       └── main/
+│           ├── java/
+│           │   └── com/codesociety/
+│           │       ├── PostgresDemoApplication.java  # Spring Boot main class
+│           │       └── DemoRunner.java               # CommandLineRunner for demo
+│           └── resources/
+│               ├── application.yml                   # Spring Boot configuration
+│               └── db/migration/
+│                   ├── V1__create_users_table.sql    # Flyway migration
+│                   └── V2__create_posts_table.sql    # Flyway migration
+├── docker-compose.yml            # PostgreSQL Docker setup
+├── .env                          # Environment variables (local)
+└── .env.example                  # Environment variables template
+```
+
+## Setup
+
+1. **Copy environment variables:**
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Start PostgreSQL with Docker Compose:**
+   ```bash
+   docker-compose up -d
+   ```
+
+3. **Verify PostgreSQL is running:**
+   ```bash
+   docker-compose ps
+   ```
+
+## Configuration
+
+Spring Boot automatically loads configuration from multiple sources in this order:
+
+### 1. application.yml (Spring Boot standard)
+Located at `app/src/main/resources/application.yml`:
+```yaml
+spring:
+  datasource:
+    url: ${DB_URL:jdbc:postgresql://localhost:5432/demo_db}
+    username: ${DB_USER:demo_user}
+    password: ${DB_PASSWORD:demo_password}
+```
+
+Spring Boot supports `${ENV_VAR:default_value}` syntax natively!
+
+### 2. .env file (via spring-dotenv)
+Create a `.env` file in the project root:
+```
+DB_URL=jdbc:postgresql://localhost:5432/demo_db
+DB_USER=demo_user
+DB_PASSWORD=demo_password
+```
+
+### 3. Environment variables
+Export environment variables directly:
+```bash
+export DB_URL=jdbc:postgresql://localhost:5432/demo_db
+export DB_USER=demo_user
+export DB_PASSWORD=demo_password
+```
+
+## Running the Application
+
+### Quick start (includes Docker setup):
+```bash
+./start.sh
+```
+
+### Run with Gradle:
+```bash
+./gradlew :app:bootRun
+```
+
+### Build the application:
+```bash
+./gradlew :app:build
+```
+
+### Run as a JAR:
+```bash
+./gradlew :app:bootJar
+java -jar app/build/libs/app.jar
+```
+
+## What the Application Does
+
+1. Loads environment variables from `.env` file (via spring-dotenv)
+2. Reads configuration from `application.yml` (Spring Boot handles this)
+3. Runs Flyway database migrations automatically (Spring Boot integration)
+4. Connects to PostgreSQL database using Spring's DataSource
+5. Queries and displays users and posts from the database using JdbcTemplate
+
+## Database Schema
+
+The application creates two tables:
+
+**Users table:**
+```sql
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    username VARCHAR(100) NOT NULL UNIQUE,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+**Posts table:**
+```sql
+CREATE TABLE posts (
+    id SERIAL PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    title VARCHAR(255) NOT NULL,
+    content TEXT,
+    published BOOLEAN NOT NULL DEFAULT false,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT fk_user FOREIGN KEY(user_id) REFERENCES users(id)
+);
+```
+
+## Docker Commands
+
+**Start PostgreSQL:**
+```bash
+docker-compose up -d
+```
+
+**Stop PostgreSQL:**
+```bash
+docker-compose down
+```
+
+**View PostgreSQL logs:**
+```bash
+docker-compose logs -f postgres
+```
+
+**Connect to PostgreSQL CLI:**
+```bash
+docker-compose exec postgres psql -U demo_user -d demo_db
+```
+
+**Stop and remove volumes (delete data):**
+```bash
+docker-compose down -v
+```
+
+## Spring Boot Features Used
+
+- **Auto-configuration:** Spring Boot automatically configures DataSource, JdbcTemplate, and Flyway
+- **Environment variable support:** Built-in `${VAR:default}` syntax in application.yml
+- **Flyway integration:** Migrations run automatically on startup
+- **CommandLineRunner:** DemoRunner executes after the application starts
+
+## Dependencies
+
+- Spring Boot Starter (3.2.1)
+- Spring Boot Starter Data JDBC
+- PostgreSQL JDBC Driver (42.7.1)
+- Flyway Core (managed by Spring Boot)
+- Flyway PostgreSQL
+- Spring Dotenv (4.0.0) - for .env file support
+
+## Troubleshooting
+
+**Connection refused:**
+- Ensure PostgreSQL is running: `docker-compose ps`
+- Check the database URL in `.env` matches your setup
+
+**Flyway migration errors:**
+- Reset the database: `docker-compose down -v && docker-compose up -d`
+- Check migration files in `app/src/main/resources/db/migration/`
+
+**Build errors:**
+- Clean and rebuild: `./gradlew clean :app:build`
+- Ensure Java 17+ is installed: `java -version`
+
+**Tests fail:**
+- The tests require a running database or use H2 in-memory database
+- To skip tests: `./gradlew :app:build -x test`
+

lib/java/postgres_demo/app/build.gradle.kts

@@ -0,0 +1,66 @@
+/*
+ * This file was generated by the Gradle 'init' task.
+ *
+ * This generated file contains a sample Java application project to get you started.
+ * For more details on building Java & JVM projects, please refer to https://docs.gradle.org/8.14.1/userguide/building_java_projects.html in the Gradle documentation.
+ */
+
+plugins {
+    // Apply the application plugin to add support for building a CLI application in Java.
+    application
+    // Spring Boot plugin
+    id("org.springframework.boot") version "3.2.1"
+    id("io.spring.dependency-management") version "1.1.4"
+}
+
+repositories {
+    // Use Maven Central for resolving dependencies.
+    mavenCentral()
+}
+
+dependencies {
+    // Spring Boot Starter
+    implementation("org.springframework.boot:spring-boot-starter")
+    
+    // Spring Boot JDBC
+    implementation("org.springframework.boot:spring-boot-starter-data-jdbc")
+    
+    // Spring Boot JPA
+    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
+    
+    // PostgreSQL JDBC Driver
+    implementation("org.postgresql:postgresql")
+    
+    // Flyway Core (managed by Spring Boot)
+    implementation("org.flywaydb:flyway-core")
+    
+    // Dotenv for loading .env files
+    implementation("me.paulschwarz:spring-dotenv:4.0.0")
+    
+    // Testing
+    testImplementation("org.springframework.boot:spring-boot-starter-test")
+    // H2 Database for testing
+    testImplementation("com.h2database:h2")
+}
+
+// Apply a specific Java toolchain to ease working on different environments.
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(17)
+    }
+}
+
+application {
+    // Define the main class for the application.
+    mainClass = "com.codesociety.PostgresDemoApplication"
+}
+
+tasks.named<Test>("test") {
+    // Use JUnit Platform for unit tests.
+    useJUnitPlatform()
+}
+
+tasks.named<org.springframework.boot.gradle.tasks.run.BootRun>("bootRun") {
+    // Set working directory to project root so .env file can be found
+    workingDir = project.rootDir
+}

lib/java/postgres_demo/app/src/main/java/com/codesociety/DemoRunner.java

@@ -0,0 +1,71 @@
+package com.codesociety;
+
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+@Component
+@ConditionalOnProperty(name = "app.demo.enabled", havingValue = "true", matchIfMissing = true)
+@org.springframework.core.annotation.Order(1)
+public class DemoRunner implements CommandLineRunner {
+
+    private final JdbcTemplate jdbcTemplate;
+
+    public DemoRunner(JdbcTemplate jdbcTemplate) {
+        this.jdbcTemplate = jdbcTemplate;
+    }
+
+    @Override
+    public void run(String... args) {
+        System.out.println("\n=== Postgres Demo Application ===\n");
+
+        System.out.println("✓ Spring Boot application started successfully!");
+        System.out.println("✓ Database connection established");
+        System.out.println("✓ Flyway migrations executed\n");
+
+        // Query the users table
+        List<Map<String, Object>> users = jdbcTemplate.queryForList("SELECT * FROM users ORDER BY id");
+
+        System.out.println("Users in database:");
+        System.out.println("-------------------------------------------");
+        System.out.printf("%-5s %-20s %-30s%n", "ID", "Username", "Email");
+        System.out.println("-------------------------------------------");
+
+        for (Map<String, Object> user : users) {
+            System.out.printf("%-5d %-20s %-30s%n",
+                    user.get("id"),
+                    user.get("username"),
+                    user.get("email"));
+        }
+
+        System.out.println("-------------------------------------------");
+
+        // Query the posts table
+        List<Map<String, Object>> posts = jdbcTemplate.queryForList(
+                "SELECT p.id, p.title, u.username, p.published "
+                + "FROM posts p "
+                + "JOIN users u ON p.user_id = u.id "
+                + "ORDER BY p.id"
+        );
+
+        System.out.println("\nPosts in database:");
+        System.out.println("-------------------------------------------------------------------");
+        System.out.printf("%-5s %-30s %-20s %-10s%n", "ID", "Title", "Author", "Published");
+        System.out.println("-------------------------------------------------------------------");
+
+        for (Map<String, Object> post : posts) {
+            System.out.printf("%-5d %-30s %-20s %-10s%n",
+                    post.get("id"),
+                    post.get("title"),
+                    post.get("username"),
+                    post.get("published"));
+        }
+
+        System.out.println("-------------------------------------------------------------------");
+        System.out.println("\n✓ Demo completed successfully!\n");
+    }
+}