Oracle Dev Service

A service providing an Oracle database for development and testing purposes. The minimum supported version is 23ai. For previous versions, use the Oracle XE Dev Service.

It works with Spring Boot libraries that support Oracle via JDBC, including:

This Dev Service is mutually exclusive with other JDBC dev services. If more than one is active at the same time, the application will fail at startup with a clear error message. Disable all but one by setting arconia.dev.services.<name>.enabled=false.

Dependencies

First, you need to add the Dev Service dependency to your project.

  • Gradle

  • Maven

dependencies {
  testAndDevelopmentOnly "io.arconia:arconia-dev-services-oracle"
}
<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-oracle</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

You can optionally include the Spring Boot DevTools dependency to enable live reload of your application during development.

  • Gradle

  • Maven

dependencies {
  developmentOnly "org.springframework.boot:spring-boot-devtools"
}
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

When you use the Spring Boot DevTools in your project and run the application in dev mode, Arconia keeps the Dev Services running while you make changes to your code instead of restarting them with the application. This allows you to see the changes in real-time without having to restart the Dev Services. Changes to the configuration of a Dev Service take effect once you stop and start the application again.

Running the Application

When using the Arconia Dev Services, you can keep running your application as you normally would. The Dev Services will automatically start when you run your application.

  • Gradle

  • Maven

  • CLI

./gradlew bootRun
./mvnw spring-boot:run
arconia dev
Unlike the lower-level Testcontainers support in Spring Boot, Arconia doesn’t require special tasks to run your application when using Dev Services (./gradlew bootTestRun or ./mvnw spring-boot:test-run) nor requires you to define a separate @SpringBootApplication class for configuring Testcontainers.

Your @SpringBootTest integration tests use the Dev Service with no additional configuration, and so do the test slices built on a JDBC data source: @JdbcTest, @DataJdbcTest, @DataJpaTest, and @JooqTest. To use Spring Boot’s embedded database in a test slice instead, when one is on the classpath, disable the Dev Service for that test with arconia.dev.services.oracle.enabled=false.

By default, each application starts its own Oracle Dev Service. To let multiple applications running simultaneously in dev mode use the same one, set the arconia.dev.services.oracle.reuse-strategy property to framework: the application connects to a running Oracle Dev Service started by another application if available, or else starts its own that other applications can discover in turn. The applications using the same Dev Service must use the same username, password, and database name. Learn more about Reusing Dev Services.

Initializing the Database

You can initialize the database by providing one or more SQL scripts to be executed when the database is started. This can be useful for creating test data or applying other customizations that are only needed during development and testing.

If you need to create the database schema or apply other changes that are required also in production, you should use a database migration tool such as Flyway or Liquibase instead. They will also work automatically with Arconia Dev Services.

The scripts must be available in the application classpath, and you can specify their location using the arconia.dev.services.oracle.init-script-paths property, which accepts a list of classpath locations.

For example, if you have a script named init.sql located in the src/main/resources/data directory of your project, you can configure the Dev Service to execute it when the database is started by adding the following property to your application.yml or application.properties file:

arconia.dev.services.oracle.init-script-paths=data/init.sql

If you need to execute SQL scripts only when running tests, you can place them in the src/test/resources directory instead of src/main/resources.

The scripts run every time the application starts the container, including a container kept running across application runs by the testcontainers reuse strategy, so write them to be idempotent (for example, CREATE TABLE IF NOT EXISTS). An application connecting to a container started by another application, with the framework reuse strategy, doesn’t run them: the application that started the container did.

Configuring the Dev Service

You can configure the Dev Service via configuration properties. Testcontainers rejects a db-name equal to freepdb1, the database the image creates on its own, and a username of sys or system, which Oracle reserves.

Property Default Description

arconia.dev.services.oracle.enabled

true

Whether the dev service is enabled.

arconia.dev.services.oracle.image-name

gvenzl/oracle-free

Full name of the container image used in the dev service.

arconia.dev.services.oracle.environment

{}

Environment variables to set in the service.

arconia.dev.services.oracle.network-aliases

[]

Additional hostnames the dev service container is reachable by on the shared network, next to the name of the dev service. Only applicable when the shared network is enabled.

arconia.dev.services.oracle.port

0

Fixed port for exposing the Oracle database port to the host. When it’s 0 (default), a random available port is assigned dynamically.

arconia.dev.services.oracle.resources

[]

Resources from the classpath or host filesystem to copy into the container. They can be files or directories that will be copied to the specified destination path inside the container at startup and are immutable (read-only).

arconia.dev.services.oracle.reuse-strategy

none

Strategy for reusing a running container for the dev service across applications or restarts. Only applicable in dev mode. See Reusing Dev Services.

arconia.dev.services.oracle.startup-timeout

120s

Maximum waiting time for the service to start, counted from the container start.

arconia.dev.services.oracle.volumes

[]

Files or directories to mount from the host filesystem into the container. They are mounted at the specified destination path inside the container at startup and are mutable (read-write). Changes in either the host or the container will be immediately reflected in the other.

arconia.dev.services.oracle.username

arconia

Username to be used for connecting to the database.

arconia.dev.services.oracle.password

arconia

Password to be used for connecting to the database.

arconia.dev.services.oracle.db-name

arconia

Name of the database to be created.

arconia.dev.services.oracle.init-script-paths

[]

List of paths to SQL scripts to be loaded from the classpath and applied to the database for initialization.

Disabling the Dev Service

Set the arconia.dev.services.oracle.enabled property to false to disable the Dev Service. To disable it in one mode only, use the profile Arconia activates for that mode (see Profiles), for example in an application-test.yml file to disable it in tests:

arconia:
  dev:
    services:
      oracle:
        enabled: false

To disable it for a single test class, set the property with @SpringBootTest(properties = …​) or @TestPropertySource. To disable all the Dev Services at once, set arconia.dev.services.enabled to false.