DBOS Instance (#309)

This PR is a **_major breaking change_** to the DBOS public API surface
area. We are removing the global singleton and most of the static
methods on `DBOS` in favor of using DBOS as an instance. We had already
done the work to ensure that everything worked with `DBOS.Instance`
directly. However, the combination of static and instance APIs made for
a poor developer experience, so we've decided to remove the static API
entirely.

Mostly, this PR is test work since nearly all the tests used the static
API. Updating all the tests allowed us to make a couple other changes -
in particular, using
[`@AutoClose`](https://docs.junit.org/6.0.3/writing-tests/built-in-extensions.html#AutoClose)
to simplify test cleanup and using
[TestContainers](https://testcontainers.com/) for database isolation.
The combination of DBOS Instance and TestContainers enables us to run
tests in parallel, bringing a test run down to 6 minutes from 15.

> Major thanks to @hannosgit who did the original TestContainers work!

In addition to the Java work, this PR updates the Kotlin DBOSExtension
class. The previous DBOSExtension primarily provided top level Kotlin
functions for DBOS static methods. Now, the DBOSExtension simply wraps
`DBOS.startWorkflow` and `DBOS.runStep` to support [Kotlin trailing
lambdas
syntax](https://kotlinlang.org/docs/lambdas.html#passing-trailing-lambdas).
We also added a Kotlin test!

fixes #306

Author: devhawk

.github/workflows/publish.yml

@@ -19,12 +19,12 @@ jobs:
     if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/v')
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0 # fetch-depth 0 needed for version calculation
 
       - name: Set up OpenJDK 21
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           java-version: '21'
           distribution: 'temurin'

.github/workflows/test.yml

@@ -12,50 +12,28 @@ jobs:
       fail-fast: false
       matrix:
         jdk-version: ['17', '21', '25']
-        jdk-distro: ['corretto', 'graalvm', 'microsoft', 'oracle', 'semeru', 'temurin', 'zulu' ]
+        jdk-distro: ['graalvm', 'microsoft', 'oracle', 'temurin' ]
         exclude:
-          - jdk-version: 17
-            jdk-distro: graalvm
+          - jdk-distro: graalvm
+            jdk-version: 17
         include:
           - jdk-distro: graalvm
             jdk-version: 17.0.12
 
-    services:
-      postgres:
-        image: sibedge/postgres-plv8:16.3-3.2.2
-        env:
-          POSTGRES_PASSWORD: dbos
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-        ports:
-          - 5432:5432
-
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0 # fetch-depth 0 needed for version calculation
 
       - name: Set up JDK ${{ matrix.jdk-distro }} ${{ matrix.jdk-version }}
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           java-version: ${{ matrix.jdk-version }}
           distribution: ${{ matrix.jdk-distro }}
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4
-
-      - name: Wait for PostgreSQL
-        run: |
-          until pg_isready -h localhost -p 5432 -U postgres; do
-            echo "Waiting for PostgreSQL..."
-            sleep 2
-          done
-        env:
-          PGPASSWORD: dbos
+        uses: gradle/actions/setup-gradle@v5
 
       - name: Run tests
         run: ./gradlew clean build
@@ -72,7 +50,7 @@ jobs:
         if: always()
 
       - name: Upload JDK ${{ matrix.jdk-distro }} ${{ matrix.jdk-version }} test results
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: test-results-${{ matrix.jdk-version }}-${{ matrix.jdk-distro }}

transact-cli/src/test/java/dev/dbos/transact/cli/MigrateCommandTest.java

@@ -1,57 +1,45 @@
 package dev.dbos.transact.cli;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import dev.dbos.transact.Constants;
 import dev.dbos.transact.database.SystemDatabase;
-import dev.dbos.transact.migrations.MigrationManager;
 
 import java.io.PrintWriter;
 import java.io.StringWriter;
-import java.sql.DriverManager;
 import java.sql.SQLException;
-import java.util.Objects;
-import java.util.concurrent.TimeUnit;
+import java.util.Collection;
+import java.util.List;
+import java.util.stream.Stream;
 
-import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.AutoClose;
 import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.Timeout;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
 import picocli.CommandLine;
 
-@Timeout(value = 2, unit = TimeUnit.MINUTES)
+@org.junit.jupiter.api.Timeout(value = 2, unit = java.util.concurrent.TimeUnit.MINUTES)
+@org.junit.jupiter.api.parallel.Execution(org.junit.jupiter.api.parallel.ExecutionMode.CONCURRENT)
 public class MigrateCommandTest {
 
-  static String db_url = "jdbc:postgresql://localhost:5432/migrate_cmd_test";
-  static String db_user = Objects.requireNonNullElse(System.getenv("PGUSER"), "postgres");
-  static String db_password = Objects.requireNonNullElse(System.getenv("PGPASSWORD"), "dbos");
-
-  @BeforeEach
-  public void setup() throws Exception {
-    var pair = MigrationManager.extractDbAndPostgresUrl(db_url);
-    var dropDbSql = String.format("DROP DATABASE IF EXISTS %s WITH (FORCE)", pair.database());
-    try (var conn = DriverManager.getConnection(pair.url(), db_user, db_password);
-        var stmt = conn.createStatement()) {
-      stmt.execute(dropDbSql);
-    }
-  }
+  @AutoClose final PgContainer pgContainer = new PgContainer();
 
   @Test
   public void migrate() throws Exception {
 
-    assertFalse(checkConnection());
-
     var cmd = new CommandLine(new DBOSCommand());
     var sw = new StringWriter();
     cmd.setOut(new PrintWriter(sw));
 
-    var exitCode = cmd.execute("migrate", "-D=" + db_url, "-U=" + db_user);
+    var args =
+        Stream.of(List.of("migrate"), pgContainer.options())
+            .flatMap(Collection::stream)
+            .toArray(String[]::new);
+
+    var exitCode = cmd.execute(args);
     assertEquals(0, exitCode);
 
-    assertTrue(checkConnection());
     assertTrue(checkTable(Constants.DB_SCHEMA, "workflow_status"));
   }
 
@@ -60,67 +48,69 @@ public void migrate_twice() throws Exception {
 
     migrate();
 
-    assertTrue(checkConnection());
-
     var app = new DBOSCommand();
     var cmd = new CommandLine(app);
 
     var sw = new StringWriter();
     cmd.setOut(new PrintWriter(sw));
 
-    var exitCode = cmd.execute("migrate", "-D=" + db_url, "-U=" + db_user);
+    var args =
+        Stream.of(List.of("migrate"), pgContainer.options())
+            .flatMap(Collection::stream)
+            .toArray(String[]::new);
+
+    var exitCode = cmd.execute(args);
     assertEquals(0, exitCode);
 
-    assertTrue(checkConnection());
     assertTrue(checkTable(Constants.DB_SCHEMA, "workflow_status"));
   }
 
   @ParameterizedTest
   @ValueSource(strings = {"invalid\"schema", "invalid'schema"})
   void testRunMigrations_fails_invalid_schema(String schema) throws Exception {
-    assertFalse(checkConnection());
 
     var cmd = new CommandLine(new DBOSCommand());
     var sw = new StringWriter();
     cmd.setOut(new PrintWriter(sw));
 
-    var exitCode =
-        cmd.execute("migrate", "-D=" + db_url, "-U=" + db_user, "--schema", "%s".formatted(schema));
+    var args =
+        Stream.of(
+                List.of("migrate"),
+                pgContainer.options(),
+                List.of("--schema", "%s".formatted(schema)))
+            .flatMap(Collection::stream)
+            .toArray(String[]::new);
+
+    var exitCode = cmd.execute(args);
     assertEquals(1, exitCode);
   }
 
   @ParameterizedTest
   @ValueSource(strings = {"F8nny_sCHem@-n@m3", "embedded\0null"})
   public void migrate_custom_schema(String schema) throws Exception {
 
-    assertFalse(checkConnection());
-
     var cmd = new CommandLine(new DBOSCommand());
     var sw = new StringWriter();
     cmd.setOut(new PrintWriter(sw));
 
-    var exitCode =
-        cmd.execute("migrate", "-D=" + db_url, "-U=" + db_user, "--schema", "%s".formatted(schema));
+    var args =
+        Stream.of(
+                List.of("migrate"),
+                pgContainer.options(),
+                List.of("--schema", "%s".formatted(schema)))
+            .flatMap(Collection::stream)
+            .toArray(String[]::new);
+
+    var exitCode = cmd.execute(args);
     assertEquals(0, exitCode);
 
-    assertTrue(checkConnection());
     assertTrue(checkTable(schema, "workflow_status"));
   }
 
-  static boolean checkConnection() {
-    try (var conn = DriverManager.getConnection(db_url, db_user, db_password);
-        var stmt = conn.createStatement()) {
-      stmt.execute("SELECT 1");
-      return true;
-    } catch (SQLException e) {
-      return false;
-    }
-  }
-
-  static boolean checkTable(String schema, String table) throws SQLException {
+  boolean checkTable(String schema, String table) throws SQLException {
     var sql =
         "SELECT EXISTS(SELECT 1 FROM information_schema.tables WHERE table_schema = ? AND table_name = ?)";
-    try (var conn = DriverManager.getConnection(db_url, db_user, db_password);
+    try (var conn = pgContainer.connection();
         var stmt = conn.prepareStatement(sql)) {
       stmt.setString(1, SystemDatabase.sanitizeSchema(schema));
       stmt.setString(2, table);

transact-cli/src/test/java/dev/dbos/transact/cli/PgContainer.java

@@ -0,0 +1,53 @@
+package dev.dbos.transact.cli;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+import java.util.List;
+
+import org.testcontainers.postgresql.PostgreSQLContainer;
+
+public class PgContainer implements AutoCloseable {
+  private final PostgreSQLContainer pgContainer = new PostgreSQLContainer("postgres:18");
+
+  public PgContainer() {
+    pgContainer.start();
+  }
+
+  @Override
+  public void close() throws Exception {
+    pgContainer.stop();
+  }
+
+  public String jdbcUrl() {
+    return pgContainer.getJdbcUrl();
+  }
+
+  public String username() {
+    return pgContainer.getUsername();
+  }
+
+  public String password() {
+    return pgContainer.getPassword();
+  }
+
+  public Connection connection() throws SQLException {
+    return DriverManager.getConnection(jdbcUrl(), username(), password());
+  }
+
+  public List<String> options() {
+    return List.of(urlOption(), userOption(), passwordOption());
+  }
+
+  public String urlOption() {
+    return "-D=" + jdbcUrl();
+  }
+
+  public String userOption() {
+    return "-U=" + username();
+  }
+
+  public String passwordOption() {
+    return "-P=" + password();
+  }
+}

transact-cli/src/test/java/dev/dbos/transact/cli/ResetCommandTest.java

@@ -4,19 +4,19 @@
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
-import dev.dbos.transact.migrations.MigrationManager;
-
 import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.sql.Connection;
 import java.sql.DatabaseMetaData;
-import java.sql.DriverManager;
 import java.sql.ResultSet;
 import java.sql.SQLException;
-import java.util.Objects;
+import java.util.Collection;
+import java.util.List;
 import java.util.concurrent.TimeUnit;
+import java.util.stream.Stream;
 
-import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.AutoClose;
+import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.MethodOrderer;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestMethodOrder;
@@ -27,32 +27,19 @@
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
 public class ResetCommandTest {
 
-  static String db_url = "jdbc:postgresql://localhost:5432/reset_cmd_test";
-  static String db_user = Objects.requireNonNullElse(System.getenv("PGUSER"), "postgres");
-  static String db_password = Objects.requireNonNullElse(System.getenv("PGPASSWORD"), "dbos");
-
-  @BeforeAll
-  static void setup() throws Exception {
-
-    var pair = MigrationManager.extractDbAndPostgresUrl(db_url);
-    var dropDbSql = String.format("DROP DATABASE IF EXISTS %s WITH (FORCE)", pair.database());
-    var createDbSql = String.format("CREATE DATABASE %s", pair.database());
-    try (var conn = DriverManager.getConnection(pair.url(), db_user, db_password);
-        var stmt = conn.createStatement()) {
-      stmt.execute(dropDbSql);
-      stmt.execute(createDbSql);
-    }
+  @AutoClose final PgContainer pgContainer = new PgContainer();
 
-    var createDummyTableSql =
-        "CREATE TABLE dummy_table (id SERIAL PRIMARY KEY, name VARCHAR(100));";
-    try (var conn = DriverManager.getConnection(db_url, db_user, db_password);
+  @BeforeEach
+  public void setup() throws SQLException {
+    var sql = "CREATE TABLE dummy_table (id SERIAL PRIMARY KEY, name VARCHAR(100));";
+    try (var conn = pgContainer.connection();
         var stmt = conn.createStatement()) {
-      stmt.execute(createDummyTableSql);
+      stmt.execute(sql);
     }
   }
 
-  static boolean dummyTableExists(String url, String user, String password) throws SQLException {
-    try (Connection conn = DriverManager.getConnection(url, user, password)) {
+  boolean dummyTableExists() throws SQLException {
+    try (Connection conn = pgContainer.connection()) {
       DatabaseMetaData metaData = conn.getMetaData();
       try (ResultSet rs = metaData.getTables(null, null, "dummy_table", new String[] {"TABLE"})) {
         return rs.next();
@@ -63,15 +50,19 @@ static boolean dummyTableExists(String url, String user, String password) throws
   @Test
   public void reset() throws Exception {
 
-    assertTrue(dummyTableExists(db_url, db_user, db_password));
+    assertTrue(dummyTableExists());
 
     var cmd = new CommandLine(new DBOSCommand());
     var sw = new StringWriter();
     cmd.setOut(new PrintWriter(sw));
 
-    var exitCode = cmd.execute("reset", "-D=" + db_url, "-U=" + db_user, "-y");
+    var args =
+        Stream.of(List.of("reset"), pgContainer.options(), List.of("-y"))
+            .flatMap(Collection::stream)
+            .toArray(String[]::new);
+    var exitCode = cmd.execute(args);
     assertEquals(0, exitCode);
 
-    assertFalse(dummyTableExists(db_url, db_user, db_password));
+    assertFalse(dummyTableExists());
   }
 }