This project is a next-generation database endpoint latency benchmarking tool, purpose-built for modern hybrid cloud and distributed application architecture. Its unique value comes from its ability to precisely measure, visualize, and diagnose both network round-trip latency and SQL execution time for a wide range of databases—including Oracle (on-prem and Autonomous/ADB), PostgreSQL, MySQL, and even HTTP/HTTPS endpoints.
By running YOUR own query, this tool captures every millisecond: DNS, handshake, connection pool, DB engine, result marshaling—just as your app user sees it. This is true end-to-end, application-perceived latency and not just network latency.
How Latency Checks Work :
Latency is measured as the total time taken for each test cycle—which includes the connection, SQL execution, and result fetching in a single measurement.
Process per iteration (databases):
- The timer starts just before the database driver begins a query cycle. This includes any necessary database connection and the execution of the test SQL (typically
SELECT 1or a user-provided query). - The timer stops immediately after the query results are fetched (i.e., after
cursor.fetchall()returns). - The elapsed time is recorded as the latency for that operation, in milliseconds.
- This measurement is appended to a list, so statistics (average, mean, p99, p90, stddev) can be calculated on all trials.
This entire measured duration includes:
-
For engines like Oracle/PostgreSQL/MySQL/SQL Server:
- TCP network round-trip time (for connect & query)
- Any network stack or driver overhead
- Server-side session creation (if not pooled)
- Query parsing & planning
- SQL execution on server
- Fetching of any results (for basic
SELECT 1it’s minimal) - Transmission of the results back to the client
The approach does not separate out the network portion vs. SQL execution: it is an end-to-end measurement for “open (if needed) + execute + fetch”.
For URL Latency Checks:
-
The tool uses the Python
requestslibrary. -
The timer starts immediately before
requests.get(url)and stops immediately after the HTTP(S) response has been received (after the body is completely read). -
The measured latency thus includes:
- DNS resolution (if needed)
- TCP/TLS handshake
- Network round-trip(s)
- Server processing time for the request
- Transmission of the full response body
For both DBs and URL cases, it is a “total user-experienced latency” as seen by a typical client, not a fine-grained split of connection and query phases.
Key Features:
- Granular Latency Breakdown: For every test, the tool separately measures the network connect time and the server-side SQL execution time. This allows you to see whether delays come from raw network/infrastructure, from database query planning/execution, or both.
- End-to-End and Per-Operation Metrics: Outputs both total and component latencies for each query iteration, viewable in tables and visualized in real-time charts.
- Live, Interactive UI: Includes a mobile-friendly GUI for interactive testing, as well as a full REST API for automation and integration with CI/CD or monitoring workflows.
- Cloud & Hybrid-Ready: Designed for real-world topologies, it works with databases anywhere—public cloud (AWS, OCI, GCP, Azure), private datacenters, or in hybrid scenarios.
- Easy Secure Remote Testing: Supports SSH tunnels so you can safely benchmark against remote cloud VMs or databases not directly exposed to the public internet.
- Flexible Connection Patterns: Accepts detailed connection parameters or industry-standard DSN strings, supporting advanced Oracle topologies and features like TCPS (TLS) secure connections and failover.
- Custom SQL Query Support: Test both trivial connectivity and the performance/latency of real, business-relevant workload queries.
- Cross-Database Comparison: Enables performance comparisons across database types and clouds, supporting architectural and vendor selection.
- Open, Extensible, and Developer-Friendly: FastAPI/REST backend, Python client code for scripting, and a well-documented interface for extension to additional DB engines or metrics.
How It Helps:
This tool equips architects, SREs, DBAs, and developers to:
- Quantify and visualize the real impact of hybrid or multi-cloud designs, by showing where latency is introduced in split-architecture applications.
- Simulate user experience for apps where the app and database reside in different data centers, clouds, or geographies.
- Optimize architecture design and deployment decisions by differentiating between network-related and DB-query-related bottlenecks.
- Validate and baseline connectivity, driver, TLS, and authentication configurations for complex, regulated, or highly available environments.
- Inform SLAs and help justify needed investments in network or database tuning.
DELTA-Otube-2m.mov
Built with ❤️ using FastAPI.
- Amazon RDS for Oracle
- OCI Autonomous Database (without Wallet TLS)
- OCI Base Database Service
- OCI Exadata Cloud Service - Dedicated
- OCI Exascale Service- Dedicated
- Oracle Database@Azure
- Oracle Database@GCP
- Oracle Database@AWS
- Oracle Database installed on OnPremises or on any other cloud provider in a VM
- Amazon RDS Postgres
- Amazon RDS Aurora Postgres
- OCI PostgreSQL
- PostgreSQL installed on OnPremises or on any other cloud provider in a VM
- Amazon RDS MySQL
- Amazon RDS Aurora MySQL
- Heatwave@AWS
- OCI MySQL Heatwave
- MySQL installed on OnPremises or on any other cloud provider in a VM
- Check Public or Private URLs for latency
Python >=3.9
git clone https://github.com/oracle-quickstart/db-endpoint-latency-testing-ammeter.git && cd db-endpoint-latency-testing-ammeter/export APP_ADMIN_PASS='abcd1234' bash build.shhttps://localhost:8000
- Log in:
admin/abcd1234(update with your password which you set forAPP_ADMIN_PASSenvironment variable). - Fill out the form and run latency tests in real time with live chart and table views.
- For any errors (connection, authentication) you'll see detailed front-end feedback.
curl -u admin:abcd1234 -X POST https://localhost:8000/api/test-latency \
-k \
-d dbtype=mysql \
-d host=localhost \
-d port=3390 \
-d username=snare \
-d password="" \
-d database=snarepoc \
-d interval=1 \
-d period=10 \
| jq .To test with a custom SQL query from the command line, simply add a -d custom_sql="YOUR SQL HERE" parameter to your curl command, like this:
curl -u admin:abcd1234 -X POST https://localhost:8000/api/test-latency \
-k \
-d dbtype=mysql \
-d host=localhost \
-d port=3390 \
-d username=snare \
-d password="" \
-d database=snarepoc \
-d interval=1 \
-d period=10 \
-d custom_sql="select count(*) from WIN2019SNAREDC_SNARE_IA;" \
| jq .-
If
custom_sqlis included (and not empty), that query is used for measuring latency (instead ofSELECT 1). -
All other parameters stay the same as before.
-
You can enter multi-line SQL in the terminal by wrapping it in quotes, or you can pipe in a file with
-d custom_sql="$(cat myquery.sql)".
-
Custom queries that are slower will always yield fewer completed test cycles in a fixed period. For eg: If your custom query takes, for example, 0.3 seconds and your interval is 1 second, each full cycle is actually ~1.3s, so over a 10 second period you’ll only get about 7-8 cycles.
-
For
SELECT 1, each loop is closer to 1s so you see 10 full cycles. -
This is expected behavior and the code is running safely/correctly.
-
Custom queries that are slower will always yield fewer completed test cycles in a fixed period. Hence use Custom queries carefully.
start.sh: Activates the Python virtual environment and launches uvicorn with HTTPS, using the generated self-signed certificate.stop.sh: Finds and terminates any uvicorn process running your app cleanly and safely.
Stop the Delta App
bash stop.shStart the Delta App
bash start.shThis section shows how to set up SSH tunnels to connect to remote databases from your local machine, and how to test each supported database type using the REST API or the GUI.
ssh -fNT -v -L 1522:10.180.2.238:1521 opc@168.x.x.x -i "mydemo_vcn.priv"ssh -fNT -v -L 1521:10.180.2.158:1521 opc@168.x.x.x -i "mydemo_vcn.priv"ssh -fNT -v -L 5432:10.180.2.205:5432 opc@168.x.x.x -i "mydemo_vcn.priv"ssh -fNT -v -L 3306:10.180.2.30:3306 opc@168.x.x.x -i "mydemo_vcn.priv"curl -u admin:abcd1234 -X POST https://localhost:8000/api/test-latency \
-k \
-d dbtype=postgresql \
-d host=localhost \
-d port=5432 \
-d username=ggadmin \
-d password="" \
-d database=dvdrental \
-d interval=1 \
-d period=5 \
| jq .
curl -u admin:abcd1234 -X POST https://localhost:8000/api/test-latency \
-k \
-d dbtype=mysql \
-d host=localhost \
-d port=3306 \
-d username=admin \
-d password="" \
-d database=dvdrental \
-d interval=1 \
-d period=5 \
| jq .
curl -u admin:abcd1234 -X POST https://localhost:8000/api/test-latency \
-k \
-d dbtype=oracle \
-d host=localhost \
-d port=1521 \
-d username=mpos \
-d password="" \
-d database=T1DB04 \
-d interval=1 \
-d period=5 \
| jq .
-
If both "port" and "database" (service_name) are provided in the form/API, it constructs a ConnectParams object using host, port (as int), and service_name, then calls oracledb.connect(user, password, params=ConnectParams(...)).
-
Otherwise, it falls back to oracledb.connect(user, password, dsn=host), allowing users to provide a complete DSN string in the "host" field.
curl -u admin:abcd1234 -X POST https://localhost:8000/api/test-latency \
-k \
-d dbtype=oracle \
-d host="(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1522)(host=localhost))(connect_data=(service_name=****_s***_high.adb.oraclecloud.com))(security=(ssl_server_dn_match=no)))" \
-d username=dvdrental \
-d password="" \
-d interval=1 \
-d period=5 \
| jq .
-
If both "port" and "database" (service_name) are provided in the form/API, it constructs a ConnectParams object using host, port (as int), and service_name, then calls oracledb.connect(user, password, params=ConnectParams(...)).
-
Otherwise, it falls back to oracledb.connect(user, password, dsn=host), allowing users to provide a complete DSN string in the "host" field.
curl -u admin:abcd1234 -X POST https://localhost:8000/api/test-latency \
-k \
-d dbtype=url \
-d url="https://google.com" \
-d interval=1 \
-d period=5 \
| jq .
Summary:
The latency metric reported by this tool is the full end-to-end time required to execute the test operation—from just before the action is started to just after it completes—capturing the complete delay as experienced by a real client under typical network and server conditions.
Yes, you must first download (clone or extract) the GitHub repo to your Windows machine.
Instructions:
-
Download the Repository
-
If you have Git installed:
- Open Command Prompt or PowerShell.
- Run:
git clone https://github.com/oracle-quickstart/db-endpoint-latency-testing-ammeter.git cd db-endpoint-latency-testing-ammeter
- Or download the zip from the GitHub releases or code page, and extract all files to a folder.
-
-
Run the Build Script
- In Command Prompt (NOT PowerShell), navigate to the project folder.
- Run:
build_windows.bat-
This script will:
- Create a virtual environment
- Install dependencies
- Generate a self-signed SSL certificate
- Launch the app on https://localhost:8000
Requirements on Windows:
- Python 3 (with pip)
- openssl.exe in PATH (commonly included with Git Bash or available at slproweb.com)
You do not need to manually install anything except Python and openssl; the script handles the rest.
This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide
Please consult the security guide for our responsible security vulnerability disclosure process
Copyright (c) 2025 Oracle and/or its affiliates.
Released under the Apache License Version 2.0, January 2004 http://www.apache.org/licenses/.