Standardize folder structure and format by amaksimo · Pull Request #223 · aws-samples/aurora-dsql-samples

amaksimo · 2025-12-23T00:54:19Z

Summary of changes in commit message:

Restructures Python, JavaScript, and Java examples with
example_preferred as the golden path (pool + connector).

Python/JS: Copied pool examples from connector repos,
restored SDK-only from pre-Update samples to use DSQL connectors #221
Java: Merged pgjdbc_hikaricp into pgjdbc,
restored SDK-only from pre-java: Use JDBC connector in pgJDBC sample #198
Added README in each alternatives/ folder
Added smoke tests for all examples

Notes

I kept the SDK auth token generation code since it might be useful and put it under alternatives

Refer to: https://amzn-aws.slack.com/archives/C09UL3KG458/p1766193841285889

The connector will be the source of truth.
I will add automation such that if the connector code examples are changed, dsql-samples will automatically update (this is a follow-up commit)... for now we just copied

Following:

<language>/<driver>/
├── README.md
├── <config files>
├── src/
│   ├── example_preferred.<ext>  # Synced from connector (pool concurrent if available)
│   └── alternatives/
│       ├── no_connection_pool/
│       │   ├── example_with_no_connector.<ext>  # SDK-based, lives only in samples
│       │   └── example_with_no_connection_pool.<ext>  # Synced from connector
│       └── pool/
│           └── <other pool variants>  # Synced from connector
└── test/
    └── <matching test structure>

anwesham-lab

We need to update the tests with the correct paths now, ie examples_preferred. I think we should have a smoke test for all examples being used so you'll want the tests repo to be refactored

We'll also want to update the driver-layer README.md files to keep the default running example_preferred.py.

You can add the follow-up explaining the alternatives and why they're present in a separate PR if it makes more sense.

This sample will give you some examples of how to refactor the tests in the python case for example: #215

amaksimo · 2025-12-23T02:57:30Z

It's a very long PR. Here is a summary of what I moved around and what is new:

Summary

Restructures Python, JavaScript, and Java examples to follow a consistent folder structure with example_preferred as the golden path (concurrent connection pool with connector).

Goal

Make aurora-dsql-samples the single source for golden path examples. The connector repos are the source of truth for connector-based examples, and this repo syncs from them. Manual/SDK only examples (no connector) live only here.

Structure

src/
├── example_preferred.*           # Golden path: concurrent pool + connector
└── alternatives/
    ├── README.md                  # Explains why pool+connector is preferred
    ├── pool/                      # Other pool configurations
    └── no_connection_pool/
        ├── example_with_no_connection_pool.*   # Single connection + connector
        └── example_with_no_connector.*         # Manual SDK (no connector)

Changes

Copied from connector repos:

Python psycopg pool examples from aurora-dsql-python-connector
Python psycopg2 pool examples from aurora-dsql-python-connector
Node.js no-pool examples from aurora-dsql-nodejs-connector

New code:

Node.js pool examples (example_preferred.js, example_with_nonconcurrent_connection_pool.js) - didn't exist in connector repos so I made it following the other examples
README files in alternatives/ folders explaining the structure

Restored from pre-#221 / pre-#198:

SDK-only examples (example_with_no_connector.*) - original tested code before connectors were added

Notes

All the connector examples have tests for them now.

Java restructure:

Merged pgjdbc_hikaricp/ into pgjdbc/ as ExamplePreferred.java
Moved original pgjdbc/Example.java to alternatives/no_connection_pool/ExampleWithNoConnectionPool.java
Restored SDK-only example from pre-java: Use JDBC connector in pgJDBC sample #198 as ExampleWithNoConnector.java
Deleted pgjdbc_hikaricp/ folder and its workflow (redundant)
Renamed test file to ExamplePreferredTest.java and added tests for alternatives

Other:

Added psycopg-pool to Python psycopg requirements.txt
Added HikariCP + AWS SDK dependencies to Java pgjdbc pom.xml
Renamed JS test files to Jest convention (*.test.js)
Updated workflows to run example_preferred

Related PRs

aurora-dsql-jdbc-connector: feature/add-examples - adds examples folder with same structure
aurora-dsql-python-connector: feature/restructure-examples - restructures existing examples
aurora-dsql-nodejs-connector: feature/add-pool-examples - adds pool examples

Next Steps

Future: automate sync from connector repos → aurora-dsql-samples

danielfrankcom · 2025-12-23T16:00:46Z

  "type": "module",
  "scripts": {
-    "test": "node --experimental-vm-modules node_modules/.bin/jest --testPathPattern='test/smoke.test.js' --runInBand --detectOpenHandles --forceExit"
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --testPathPattern='test/example_preferred.test.js' --runInBand --detectOpenHandles --forceExit"


Does this imply we're only running the one test? We may want to remove the testPathPattern flag entirely like what was done for the Node.js connectors change. In the other PR the integration tests run all of the examples which is better imo.

Missed that, will fix for this PR.

danielfrankcom · 2025-12-23T16:01:07Z

  "type": "module",
  "scripts": {
-    "test": "node --experimental-vm-modules node_modules/.bin/jest --testPathPattern='test/smoke.test.js' --runInBand --detectOpenHandles --forceExit"
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --testPathPattern='test/example_preferred.test.js' --runInBand --detectOpenHandles --forceExit"


Same comment here, I think we want to run all of the tests rather than just the one.

Thanks, fair comment, will fix that.

danielfrankcom · 2025-12-23T16:03:24Z

        echo "$GITHUB_WORKSPACE" >> $GITHUB_PATH
        wget https://www.amazontrust.com/repository/AmazonRootCA1.pem -O root.pem
-        python src/example.py
+        python src/example_preferred.py


It seems like we should invoke pytest for both of the Psycopg workflows rather than the example script directly. Currently only the one example is exercised, and the tests aren't used at all.

Thanks, will add testing for all of them.

danielfrankcom · 2025-12-23T16:04:53Z

+        raise FileNotFoundError(f"SSL certificate file not found: {ssl_cert_path}")
+
+    conn_params = {
+        "dbname": "postgres",


Do we want to include things that have sensible defaults in the connector, like dbname, port sslmode? I'd have to test to make sure but I think these can be safely removed here as we've done elsewhere.

I agree with you. I think this should be done in follow-up. The connectors are the source of truth, so we will need to update the code there. Currently the code here is duplicate/same as what we have in the connectors.

The next steps would look something like:

Improve connector code to remove the sensible defaults. Update the readmes to include info about the defaults

Automate

.. now dsql-samples will have that.

Let me know if that sounds reasonable.

Yep that sounds good to me

danielfrankcom · 2025-12-23T16:05:17Z

+        raise FileNotFoundError(f"SSL certificate file not found: {ssl_cert_path}")
+
+    conn_params = {
+        "dbname": "postgres",


Same comment about using DSQL defaults to simplify UX for "preferred" sample

Same comment as above

danielfrankcom · 2025-12-23T16:06:40Z

+        "user": cluster_user,
+        "host": cluster_endpoint,
+        "port": "5432",
+        "region": region,


I'm not sure the region is needed here given the endpoint contains the region for the connectors.

Same comment as above

danielfrankcom · 2025-12-23T16:07:02Z

+        "user": cluster_user,
+        "host": cluster_endpoint,
+        "port": "5432",
+        "region": region,


Same comment, not sure region is needed.

Same comment as above

Restructures Python, JavaScript, and Java examples with example_preferred as the golden path (pool + connector). - Python/JS: Copied pool examples from connector repos, restored SDK-only from pre-#221 - Java: Merged pgjdbc_hikaricp into pgjdbc, restored SDK-only from pre-#198 - Added README in each alternatives/ folder - Added smoke tests for all examples

anwesham-lab requested changes Dec 23, 2025

View reviewed changes

amaksimo force-pushed the feature/sync-connector-examples branch from f892447 to b041480 Compare December 23, 2025 02:06

amaksimo marked this pull request as draft December 23, 2025 02:08

amaksimo force-pushed the feature/sync-connector-examples branch 3 times, most recently from f7ee006 to a51fa04 Compare December 23, 2025 02:17

amaksimo marked this pull request as ready for review December 23, 2025 02:20

amaksimo force-pushed the feature/sync-connector-examples branch 5 times, most recently from 61321bd to f743b80 Compare December 23, 2025 02:53

amaksimo changed the title ~~Restructure examples with alternatives folder structure~~ Standardize folder structure and format Dec 23, 2025

amaksimo enabled auto-merge (squash) December 23, 2025 03:03

danielfrankcom reviewed Dec 23, 2025

View reviewed changes

amaksimo force-pushed the feature/sync-connector-examples branch from f743b80 to e06f582 Compare December 23, 2025 18:11

danielfrankcom approved these changes Dec 23, 2025

View reviewed changes

anwesham-lab approved these changes Dec 23, 2025

View reviewed changes

amaksimo merged commit 02dc4d3 into main Dec 23, 2025
17 checks passed

amaksimo deleted the feature/sync-connector-examples branch December 23, 2025 19:54

Conversation

amaksimo commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of changes in commit message:

Notes

Uh oh!

anwesham-lab left a comment

Choose a reason for hiding this comment

Uh oh!

amaksimo commented Dec 23, 2025

Summary

Goal

Structure

Changes

Related PRs

Next Steps

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

amaksimo commented Dec 23, 2025 •

edited

Loading