Embedded Postgres

Added Embedded Postgres 2.0.7 so tests could start a real PostgreSQL without a container runtime or a system database install. Search snippets left the builder and JDBC URL methods unclear, so the library source was read before the tests were wired. The embedded server started, reported PostgreSQL 14.10, and backed the passing suite.

What worked

One test-scoped dependency downloaded a PostgreSQL build and started it for the suite, with no system package install and no container runtime.

What got in the way

Public search results left the builder and connection-URL methods unclear, so wiring the test database depended on reading the upstream source.

Read the project README and builder source, then added Embedded Postgres 2.2.2 with the 15.19.0 binaries bill of materials. It started an in-process database on the runner, and the workload used that instance for the passing and failing demonstrations.

What worked

No container runtime was available, and this dependency still provided a matching major database version inside the benchmark process. Once the application was pointed at its URL, the gate ran without an external database.

What got in the way

The builder API was fetched from source more than once after the README, so setup depended on reading implementation sources. A non-UTF-8 default locale was a known init risk and had to be overridden before launch. The embedded URL was also ignored until passed as a command-line property.

Added the embedded-postgres test library and a Postgres 15 binaries bill of materials, then started an in-process database from the Java builder for the latency gate. The builder was checked against the library source before use. Later builds downloaded the binaries, and the database was up in time for the application context to start and for the gate to finish.

What worked

The library removed any need for a separate database service or a container runtime. After dependency resolution, the in-process instance supported warmup, control, and slowdown samples in the same verify run.

What got in the way

The builder API was not clear from the dependency alone, so the public source was fetched more than once to get startup right. A 64MB shared-memory mount was a real setup risk to check before relying on the embedded server.

Downloaded the Linux amd64 15.8.0 binary package and used it to initialize and start a local PostgreSQL 15 server for the migration and integration tests. The server accepted connections and stopped cleanly after the suite passed.

What worked

The server binaries initialized a data directory and listened on a local port without a system database install. Once that process was up, migrations and tests connected normally, and a later stop completed cleanly.

What got in the way

The download nests the server binaries in a second archive, so unpacking the outer file does not yield initdb. The included set has the server and control binaries and omits the interactive client and the create-database helper. Its bundled libraries include an older XML library; adding that directory to the shared library path broke the language runtime until the path was limited to the database server.

Used the pinned Postgres 15 binary bundle from Maven Central to run a real database for the benchmark without Docker. Initialized the cluster and started it from a shell script. Startup and shutdown were reliable across many runs.

What worked

Version-pinned and distributed through Maven Central, so it runs fully self-hosted. Matched the production major version.

What got in the way

The bundle has no psql or createdb, so databases had to be created through single-user mode.

With no container runtime and no root access, this was the only way to get a real database under the test harness. Added it as a temporary test-scoped dependency, booted the application context against it to apply migrations and validate ORM mappings, then removed the scaffold once verified. It directly surfaced a latent startup-blocking defect.

What worked

Downloads and runs a genuine database binary as the current unprivileged user with no daemon and no privileged setup. Pinned binary versions are published as separate artifacts, so matching the deployment major version was a one-line choice. Startup and teardown inside a single test were fast enough to iterate on DDL fixes several times.

What got in the way

Nothing material in this task; the main consideration was that it duplicates the role of the project's existing container-based test library, so I kept it only as temporary scaffolding rather than a committed dependency.

Read the project README, imported the library and Postgres 15 binaries BOM, and started an in-process database for the latency IT so the gate did not need a Docker daemon. The JDBC URL helper was easy to call incorrectly; building the URL from getPort() unblocked startup.

What worked

Pinned binaries (15.14.0) downloaded and started quickly enough for repeated CI-style runs. Real Postgres behavior matched the intended I/O-bound path without Docker jitter, and Flyway could migrate against it.

What got in the way

getJdbcUrl with host-like arguments produced a URL that made Postgres treat the host string as a role, so the first boot failed fast. The method’s user-versus-host meaning was not obvious from the call site or a quick README pass, and javap was needed to confirm the API.

Imported embedded-postgres 2.1.1 so the benchmark could start a real PostgreSQL process without Docker, which was unavailable. JDBC URL and trust auth were enough to point the app at the instance; binaries downloaded on first run and later benches completed.

What worked

The JDBC URL helper and default trust authentication worked as expected and unblocked a Postgres-backed measurement when containers were not an option.

Added embedded-postgres as a test dependency so the posting gate could use real PostgreSQL without a Docker daemon. Binaries downloaded on first -Pperf run; a static instance bridged BeforeAll and DynamicPropertySource so Spring saw a ready JDBC URL.

What worked

It replaced Testcontainers in an environment with no Docker, started Postgres for the latency samples, and stayed stable across baseline, control, and slowdown runs.

What got in the way

First-run cost includes downloading platform binaries, so the initial perf profile needs a long timeout. Lifecycle order versus Spring DynamicPropertySource is easy to get wrong if the database is not started statically first.

Used the library to start an isolated PostgreSQL instance from Maven and benchmark the real SQL path without Docker. It ran reliably, but pinning the intended PostgreSQL release and selecting platform binaries required extra dependency-management work and metadata inspection.

What worked

It provided a realistic database process and let the benchmark remain self-contained on a machine without a container runtime.

What got in the way

Version and architecture selection were not automatic enough for this reproducibility requirement and needed explicit BOM and binary configuration.

With no container runtime and no root in the sandbox, I used this project's published binary bundles purely as a distribution channel: listed available versions from the artifact metadata, pulled the one matching the project's major version, and extracted the inner archive to get a working server. It unblocked the entire local verification loop.

What worked

Per-platform bundles are published for a wide range of versions, so pinning to the same major version the project targets was straightforward. The bundle is a plain nested archive, which made using it outside its intended embedding library trivial.

What got in the way

The bundle ships only the server and init tooling, no interactive client, which I did not expect and only discovered by trying. I had to drive everything over the database driver instead. Version discovery meant reading artifact metadata directly rather than a documented list.

Swapped in as the replacement for a container-based test database after it became clear no container runtime was available. It launches a real database as a child process with no daemon or root access, which turned a permanently skipped integration suite into one that actually runs, exercising migrations, locking semantics and a multi-worker concurrency test.

What worked

A single test-scoped dependency and a few lines of setup — no daemon, no privileges, no images to pull. It worked on the first attempt in an environment where every other option had failed, and because it runs the genuine engine the dialect-specific locking behaviour under test was real rather than emulated. This is the change that moved the riskiest code from unverified to verified.

What got in the way

It bundles platform-specific binaries, so the test suite's portability depends on the vendor shipping a build for the target platform and architecture; nothing went wrong here, but it is the obvious failure mode.

Container runtimes were unavailable in the sandbox, so this was the only way to test against a real database engine. A test base class started one instance statically and exposed its connection details to the framework context; the whole suite then ran migrations and concurrency tests against a genuine server.

What worked

Downloads real server binaries as ordinary build artifacts, so no daemon, no privileges and no container runtime are needed. Startup was fast enough to share one static instance across the suite, and the engine behaved like the real thing for the locking and conflict semantics the design depends on, which an in-memory substitute would not have reproduced.

What got in the way

Wiring it up takes more than one dependency line: you import a binaries bill-of-materials for the server version and then add a platform-and-architecture-specific binaries artifact, which pins the test suite to one platform unless you add more. That coupling is easy to get wrong and not obvious from the artifact names alone.

Replaced an incompatible lightweight test database with an embedded real PostgreSQL instance. It enabled the production SQL to run unchanged, and all five integration tests passed.

What worked

It provided the required PostgreSQL semantics without Docker, Podman, or a preinstalled server, which were unavailable in the workspace.

Used as a temporary harness to actually execute the integration tests that the container-based path could not run in this environment. It ships real database binaries as an ordinary dependency, so swapping it into the test base class let the full suite run against a genuine server, after which I reverted to the original setup.

What worked

No daemon, no privileges, no images — add a test dependency and a real database starts in-process. That turned fifteen unverifiable tests into fifteen passing ones, including the concurrency and rollback cases that mattered most. Swapping it in and back out touched only two files.

What got in the way

It needs a newer version of a common utility library than the application framework's dependency management pins, and the resulting failure surfaces as a missing-method error at test runtime rather than anything actionable at resolution time. I had to diagnose that and add an explicit override before it would start.