GitHub Actions PostgreSQL Service Containers: Test Museum Imports Without Touching Production

A Catalog Import Test Must Not Write to the Live Database

A museum’s website imports approved accession rows from a CSV export. Its CI job should check constraints, duplicate IDs and transaction behavior before a new parser is deployed. Running those tests against production PostgreSQL would create unnecessary risk to the real collection. GitHub Actions supports PostgreSQL service containers that start alongside a job and provide a temporary database for test code. The integration test can create tables, load synthetic fixtures and inspect a simulated import without exposing live donor records. This is a development workflow, not evidence that the museum’s real records have passed QA. The sample schema and row IDs in this guide are invented to explain safe isolation.

Choose the Network Model Before Copying YAML

GitHub’s guide describes two ways to connect to a service. When the job itself runs in a container, it shares a user-defined Docker network with service containers and connects to the service using its label, commonly postgres, on the container’s port. When the job runs directly on the runner machine, the service port must be mapped to the runner host and the test code generally connects to localhost with the mapped port. Confusing the two approaches makes a healthy database look unreachable. Decide which environment fits your build before writing connection strings. The examples in official documentation use Linux runners because Docker-based job and service containers require that environment.

Create Disposable Credentials and an Empty Test Schema

The PostgreSQL image needs environment variables for an isolated database, user and password. These are disposable test-only values, never the organization’s production credentials. Use a fresh database and schema for each CI run so two branches do not share state. Prefer synthetic accessions such as TEST-001 over any real collection inventory. A developer should not copy a production dump into a public fork’s test runner to make integration tests look realistic. Keep network exposure limited to the job’s needs and avoid printing secrets or connection strings in logs. If the test produces an artifact, it should contain row counts, fixture IDs and failure messages, not private loan details. Destroy the short-lived service when the job finishes.

Wait for Readiness, Not Merely Container Startup

A service container being started does not prove PostgreSQL is ready to accept queries. GitHub’s PostgreSQL example includes Docker health-check options based on pg_isready. Configure the check against the test database and give it appropriate intervals and retries. The job should also fail visibly if the database cannot be reached, instead of skipping the import test and marking CI green. Health checks are an infrastructure prerequisite, not a test of your schema or parser. Distinguish ‘container running’, ‘database accepts connections’, ‘fixtures loaded’ and ‘import assertions passed’. These are separate states, and a dashboard that merges them into one success symbol can hide a broken test pipeline.

Exercise a Small, Realistic Import Transaction

A test fixture can include one valid accession, a duplicated key, a missing required date and a row with a harmless apostrophe in its title. Run the parser against the service database and assert that it rejects invalid rows without corrupting the approved test state. If the application uses transactions, deliberately fail halfway through a batch and check whether the intended rollback occurs. A test that merely connects and runs SELECT 1 is a useful readiness check but is not evidence the importer handles real business rules. Avoid testing an AI-generated historical attribution by pretending its text is a verified catalog record; the script should validate format and provenance requirements, leaving historical interpretation to the curator.

Compare Container Networking and Common Failure Modes

In a container job, the service hostname is its label rather than localhost. In a runner job, use an explicitly mapped port and localhost. A hypothetical misconfiguration may yield a connection-refused error even though the PostgreSQL service itself is fine; another misconfiguration could connect to the wrong external database if credentials leak into the environment. The diagram compares the two correct routes and an unsafe production connection as separate illustrative states. It is not a screenshot or measured network trace. Keep connection settings scoped to the test step and fail immediately if the hostname or database name does not match the expected test configuration. This makes mistakes visible before any import command runs.

Separate Test Results From Deployment Permission

A successful PostgreSQL import test proves that the given code behaved as asserted on that synthetic fixture and environment. It does not approve every incoming record, verify licenses or authorize a deployment. Tie the workflow to a commit or build identifier and require independent checks for caption review, accessibility and artifact integrity where relevant. The deployment job should depend on mandatory test results, and release credentials should not be available to untrusted pull request tests. If a third-party action or container image changes unexpectedly, review the version before allowing the workflow to use broad repository permissions. Keep job-level token permissions minimal and environment secrets outside the database test job.

Review CI Isolation and Recovery Scenarios

Suggested staging exercises include a missing Docker service, a failing health check, a migration that omits an index, a duplicated primary key and a parser crash during a transaction. The correct outcome is a failed test with enough evidence to diagnose it, not a silent fallback to a shared production database. Use the official networking patterns and ensure your workflow has no alternate database host configured behind the scenes. Check whether test dependencies can reach outside services and disable unnecessary egress where practical. A reproducible failure report should list the selected environment, synthetic fixture version and assertion, without exposing passwords. These exercises are recommendations, not tests LabFin claims to have run.

Make the Import Proof Reviewable by Another Maintainer

The handoff for a new catalog parser should include its service container definition, Linux runner choice, database fixture seed, readiness check, SQL assertions and release dependency. A reviewer should be able to recreate the failing row locally or in a permitted CI environment. Keep production migrations as a separately authorized step that operates on approved records, with backups and rollback appropriate to the site. GitHub’s service container feature simplifies temporary integration infrastructure; it does not change who is responsible for source quality or public release. If the pipeline displays every important state, the team can catch dangerous import logic without putting its historical collection at risk.

Related guides

• GitHub Actions Matrix Strategy: Test Museum Imports Across Versions Without Hiding Failures
• GitHub Actions Artifact Retention: Delete Temporary Test Exports Without Losing Evidence
• GitHub Actions Matrix include/exclude: Test Every Approved Caption Language

How We Research

For this guide, we reviewed the official product documentation on November 8, 2026: GitHub Creating PostgreSQL Service Containers, GitHub Communicating With Docker Service Containers, GitHub Workflow Syntax Reference. We checked the named setting or feature against its published behavior, mapped the documented constraints to the specific hypothetical scenario, and reviewed whether the topic duplicated titles in the supplied LabFin WordPress inventory or prior B0267–B0281 ZIPs. No authenticated vendor service was run; we did not perform a benchmark, observe real customer data, verify third-party rights or claim operational outcomes. All illustrated records and comparisons are teaching examples. Confirm product documentation and security requirements again before implementing a workflow in a real organization.

Frequently Asked Questions