Docs: Add docs / guides for AI agents

rbygrave · rbygrave · commit 7afc6bc62e6d · 2026-04-12T16:35:50.000+12:00
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ A robust and fast SQL DataSource implementation
 
 ## Table of Contents
 
+- [Documentation & Guides](#documentation--guides)
 - [Example use](#example-use)
 - [Robust and fast](#robust-and-fast)
 - [Read-Only Connection Pools](#read-only-connection-pools)
@@ -16,6 +17,16 @@ A robust and fast SQL DataSource implementation
 - [Mature](#mature)
 - [Java modules use](#java-modules-use)
 
+### Documentation & Guides
+
+This project includes step-by-step guides for common datasource configuration scenarios.
+
+**See [docs/guides/README.md](docs/guides/README.md)** for:
+- [Creating DataSource pools](docs/guides/create-datasource-pool.md) — basic pools, read-only pools, Kubernetes deployment, AWS Lambda, and configuration reference
+- Instructions for AI agents to discover and follow these guides
+
+These guides are designed for both developers and AI coding agents (Copilot, Claude, Cursor, etc.) to follow step-by-step instructions for common tasks.
+
 ### Example use:
 
 ```java
diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -0,0 +1,74 @@
+# Guides
+
+Step-by-step guides written as instructions for AI agents and developers.
+
+## Creating DataSource Pools
+
+Step-by-step guide covering common scenarios for creating and configuring connection pools.
+
+| Guide | Description |
+|-------|-------------|
+| [Create a DataSource Pool](create-datasource-pool.md) | Basic pool creation, read-only pools, Kubernetes configuration, AWS Lambda setup, and connection validation settings |
+
+---
+
+## Helping AI agents find these guides
+
+AI coding agents can only follow these guides if they know they exist. Below are
+copy-paste snippets for the most common AI tooling configurations. Add whichever
+applies to your project.
+
+### Project `README.md` (universal — works with all AI tools)
+
+Add a section near the top of your project README:
+
+```markdown
+## Documentation & Guides
+
+This project includes step-by-step guides for common tasks with the ebean-datasource connection pool:
+
+**https://github.com/ebean-orm/ebean-datasource/tree/main/docs/guides/**
+
+AI agents should fetch and follow the relevant guide before performing datasource-related tasks.
+```
+
+### Why README is important
+
+Many AI agents (Copilot, Claude, Cursor, Aider) read the project `README.md`
+automatically as part of understanding the codebase. A visible link in README is the
+most universally effective way to ensure any agent working on your project will
+discover the guides without requiring tool-specific configuration files.
+
+------
+
+### GitHub Copilot — `.github/copilot-instructions.md`
+
+```markdown
+## ebean-datasource
+
+This project uses ebean-datasource for connection pooling. Step-by-step guides for common
+tasks are at: https://github.com/ebean-orm/ebean-datasource/tree/main/docs/guides/
+
+Key guides (fetch and follow when performing the relevant task):
+- Create a DataSource Pool: https://raw.githubusercontent.com/ebean-orm/ebean-datasource/main/docs/guides/create-datasource-pool.md
+```
+
+### Claude Code — `CLAUDE.md`
+
+Same content as above — Claude Code reads `CLAUDE.md` at the project root.
+
+### Cursor — `.cursor/rules/ebean-datasource.mdc`
+
+```markdown
+---
+description: ebean-datasource connection pool guidance
+globs: ["**/*.java", "**/pom.xml"]
+alwaysApply: false
+---
+
+## ebean-datasource
+
+This project uses ebean-datasource for connection pooling. Before performing any datasource configuration task, fetch and
+follow the relevant step-by-step guide from:
+https://github.com/ebean-orm/ebean-datasource/tree/main/docs/guides/
+```
diff --git a/docs/guides/create-datasource-pool.md b/docs/guides/create-datasource-pool.md
@@ -0,0 +1,222 @@
+# Guide: Create a DataSource Pool
+
+## Purpose
+
+This guide provides step-by-step instructions for creating and configuring DataSource pools for different deployment scenarios. Follow the steps for the scenario that matches your use case.
+
+---
+
+## Prerequisites
+
+- A Java project with Maven
+- `io.ebean:ebean-datasource` dependency already added to `pom.xml`
+- Database connection details (URL, username, password)
+- Understanding of your deployment environment (standard server, Kubernetes, AWS Lambda, etc.)
+
+---
+
+## Scenario 1: Basic DataSource Pool (Standard Server/VM)
+
+Use this configuration for traditional server deployments.
+
+### Step 1 — Create the pool builder
+
+```java
+DataSourcePool pool = DataSourcePool.builder()
+  .name("mypool")
+  .url("jdbc:postgresql://localhost:5432/myapp")
+  .username("app_user")
+  .password("password")
+  .minConnections(5)
+  .maxConnections(50)
+  .build();
+```
+
+### Step 2 — Use the pool in your application
+
+```java
+try (Connection connection = pool.getConnection()) {
+  try (PreparedStatement stmt = connection.prepareStatement("SELECT * FROM users WHERE id = ?")) {
+    stmt.setInt(1, 123);
+    try (ResultSet rs = stmt.executeQuery()) {
+      while (rs.next()) {
+        // Process results
+      }
+    }
+  }
+}
+```
+
+---
+
+## Scenario 2: Read-Only Pool
+
+Use this configuration for read-only workloads (analytics, reporting, caching layers).
+This adds readOnly(true) and autoCommit(true) options when building the pool.
+
+### Step 1 — Create a read-only pool
+
+```java
+DataSourcePool readOnlyPool = DataSourcePool.builder()
+  .name("mypool-readonly")
+  .url("jdbc:postgresql://read-replica.example.com:5432/myapp")
+  .username("readonly_user")
+  .password("password")
+  .readOnly(true)           // Signal no writes will occur
+  .autoCommit(true)         // Skip transaction overhead
+  .minConnections(5)
+  .maxConnections(30)
+  .build();
+```
+
+### Step 2 — Use the read-only pool
+
+```java
+try (Connection connection = readOnlyPool.getConnection()) {
+  try (PreparedStatement stmt = connection.prepareStatement("SELECT * FROM large_table")) {
+    try (ResultSet rs = stmt.executeQuery()) {
+      while (rs.next()) {
+        // Process results - queries will be faster with read-only optimization
+      }
+    }
+  }
+}
+```
+
+---
+
+## Scenario 3: Kubernetes Deployment
+
+Use this configuration when deploying to Kubernetes clusters.
+
+### Step 1 — Create a pool with warm-up configuration
+
+When pods start, they immediately receive production traffic. Start with `initialConnections`
+set higher than `minConnections` to avoid cold-start connection creation overhead.
+
+```java
+DataSourcePool pool = DataSourcePool.builder()
+  .name("mypool")
+  .url("jdbc:postgresql://postgres.default.svc.cluster.local:5432/myapp")
+  .username("app_user")
+  .password(System.getenv("DB_PASSWORD"))  // Use environment variables
+  .minConnections(5)
+  .initialConnections(20)     // Start with 20 connections ready
+  .maxConnections(50)
+  .build();
+```
+
+### Step 2 — Use environment variables for configuration
+
+For Kubernetes deployments, externalize database credentials:
+
+```java
+String dbUrl = System.getenv("DATABASE_URL");
+String dbUser = System.getenv("DATABASE_USER");
+String dbPass = System.getenv("DATABASE_PASSWORD");
+
+DataSourcePool pool = DataSourcePool.builder()
+  .name("mypool")
+  .url(dbUrl)
+  .username(dbUser)
+  .password(dbPass)
+  .minConnections(5)
+  .initialConnections(20)
+  .maxConnections(50)
+  .build();
+```
+
+
+---
+
+## Scenario 4: AWS Lambda
+
+Use this configuration for AWS Lambda functions.
+
+### Step 1 — Create a minimal pool
+
+The ebean datasource automatically detects when it is running in Lambda via the `LAMBDA_TASK_ROOT` environment variable
+and disables background heartbeat validation to optimize for cost and lambda suspend behaviour.
+
+```java
+DataSourcePool pool = DataSourcePool.builder()
+  .name("mypool")
+  .url("jdbc:postgresql://mydb.region.rds.amazonaws.com:5432/myapp")
+  .username("app_user")
+  .password(System.getenv("DB_PASSWORD"))
+  .minConnections(1)
+  .initialConnections(2)
+  .maxConnections(10)
+  .build();
+```
+
+### Step 2 — Understanding Lambda connection pooling
+
+**Important:** Connection pooling in Lambda is **per-Lambda instance**, not per-invocation:
+
+- A single Lambda container can be reused across many warm invocations
+- Connection pool persists across warm invocations
+- Cold starts get a fresh pool
+- Connections are trimmed automatically if unused
+
+
+---
+
+## Configuration Reference
+
+### Common Settings
+
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `minConnections` | 2 | Minimum connections to maintain in the pool |
+| `initialConnections` | Same as minConnections | Connections to create when pool starts (useful for Kubernetes/warm-up) |
+| `maxConnections` | 200 | Maximum connections to allow |
+| `readOnly` | false | Set to true for read-only workloads |
+| `autoCommit` | false | Set to true to skip transaction boundaries |
+| `validateOnHeartbeat` | true (false in Lambda) | Enable background connection validation |
+| `heartbeatFreqSecs` | 30 | How often to validate connections (seconds) |
+
+### Typical Sizing
+
+**Development/Testing:**
+```java
+.minConnections(1)
+.initialConnections(1)
+.maxConnections(5)
+```
+
+**Production - Standard Server:**
+```java
+.minConnections(5)
+.initialConnections(10)
+.maxConnections(50)
+```
+
+**Production - High Traffic:**
+```java
+.minConnections(10)
+.initialConnections(40)
+.maxConnections(100)
+```
+
+**Lambda - Standard:**
+```java
+.minConnections(1)
+.initialConnections(2)
+.maxConnections(10)
+```
+
+**Lambda - Provisioned Concurrency:**
+```java
+.minConnections(2)
+.initialConnections(10)
+.maxConnections(20)
+```
+
+---
+
+## Next Steps
+
+- Read the [README](../../README.md) for more information about the connection pool
+- Check the [ebean-datasource GitHub repository](https://github.com/ebean-orm/ebean-datasource) for latest updates
+- Consult the [DataSourceBuilder API documentation](https://javadoc.io/doc/io.ebean/ebean-datasource) for all available configuration options
