Refresh public DB services, builds, and documentation

.github/workflows/build.yml

@@ -0,0 +1,64 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Java ${{ matrix.java }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: drremote_test
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      DRREMOTE_TEST_POSTGRES_URL: jdbc:postgresql://localhost:5432/drremote_test
+      DRREMOTE_TEST_POSTGRES_USER: postgres
+      DRREMOTE_TEST_POSTGRES_PASSWORD: postgres
+    strategy:
+      fail-fast: false
+      matrix:
+        java: ['17', '21']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+      - name: Build, test, and verify Karaf features
+        run: mvn --batch-mode --no-transfer-progress clean install
+      - name: Build the SQLite example
+        run: mvn --batch-mode --no-transfer-progress -f examples/notes-client/pom.xml verify
+      - name: Upload bundles, feature descriptors, and example
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: drremote-db-java-${{ matrix.java }}
+          if-no-files-found: error
+          path: |
+            de.drremote.db.*/target/*.jar
+            de.drremote.db.*.features/target/feature/feature.xml
+            examples/notes-client/target/*.jar
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: test-reports-java-${{ matrix.java }}
+          if-no-files-found: ignore
+          path: de.drremote.db.*/target/surefire-reports/

.gitignore

@@ -31,4 +31,6 @@ Thumbs.db
 *~
 
 # Optional Maven wrapper cache artifacts
-.mvn/timing.properties
+.mvn/timing.properties
+# Local agent execution records
+.superpowers/

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 1.1.0-SNAPSHOT — unreleased
+
+- Add DuckDB as an embedded analytical database option, with a JDBC bundle, Karaf feature, configuration, and tests.
+- Refresh PostgreSQL and SQLite transaction handling. Nested calls on the same transaction manager/thread join the outer transaction; a nested failure marks it rollback-only even if caught.
+- Add SQLite atomic batch migrations, optional baselines for new installations, migration SQL drift detection, and automatic migration readiness services.
+- Refresh PostgreSQL migration coordination, JDBC URL conversion, and `psql` execution. Script migrations default to a single transaction and stop on SQL errors.
+- Fix PostgreSQL JDBC migration schema creation and run migration locking/work on one borrowed connection. Failed lock acquisition releases its connection.
+- Add regression tests, live PostgreSQL CI, Java 17/21 builds, actual Karaf feature resolution checks, and a buildable SQLite client example.
+- Correct the source-build and installation instructions. The former public Maven repository is retired; project artifacts must be built locally.
+
+### Upgrading from the existing public source
+
+The public Maven names remain `de.drremote.db:postgresql`, `sqlite`, and their `*-features` artifacts. Exported Java API packages and bundle symbolic names remain unchanged. DuckDB adds `de.drremote.db:duckdb` and `duckdb-features`.
+
+Use `1.1.0-SNAPSHOT` consistently for Maven artifacts; Karaf displays its normalized feature/bundle version as `1.1.0.SNAPSHOT`. The former README's `1.0.0-SNAPSHOT` examples did not match the public POM's `1.0.0` version.
+
+The minimum Java version is now 17. The supported feature target is Karaf 4.4.11. Existing PostgreSQL/SQLite single-statement migration descriptors remain supported; the new SQLite baseline method has a default implementation returning `null`.
+
+Nested PostgreSQL/SQLite transaction failures now prevent an outer commit. PostgreSQL script migrations default to `psql --single-transaction`; override `ScriptMigration.isSingleTransaction()` only for commands that cannot execute inside a transaction. Review both changes if older callers relied on the previous behavior.
+
+Do not edit already-applied migrations. Add a new version instead. SQLite now reports SQL drift for recorded migrations with stored SQL. Baselines only apply when the plugin has no existing migration history.
+
+DuckDB currently has a simpler transaction/migration layer: avoid nested transaction calls, register/apply migrations explicitly, and use one SQL statement per migration. It does not expose the PostgreSQL/SQLite `DatabaseReady` contract.
+
+There is no new tagged release or remotely published artifact implied by this development version.

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Issues and pull requests are welcome. Describe the database, Java/Karaf versions, configuration with credentials removed, expected behavior, actual behavior, and a small reproduction.
+
+## Build and tests
+
+Requirements: JDK 17+ and Maven 3.9+.
+
+```sh
+mvn clean verify
+mvn install
+mvn -f examples/notes-client/pom.xml verify
+```
+
+The main suite includes PostgreSQL transaction/URL/script-runner regression tests, SQLite migration/transaction tests, and real temporary DuckDB transaction/migration tests. It does not require a running PostgreSQL server by default. The PostgreSQL integration tests run when `DRREMOTE_TEST_POSTGRES_URL` is set; CI supplies a PostgreSQL 17 service and runs them on both Java versions. Those tests require `psql` and a dedicated test database, and cover fresh schemas, replay, one-connection pools, and mixed JDBC/script migrations.
+
+To run them locally, point `DRREMOTE_TEST_POSTGRES_URL` at a disposable database (for example `jdbc:postgresql://localhost:5432/drremote_test`) and set `DRREMOTE_TEST_POSTGRES_USER` and `DRREMOTE_TEST_POSTGRES_PASSWORD` as appropriate. The default test user/password are `postgres`. The tests create uniquely named schemas and remove their objects afterward; do not use a production database.
+
+Karaf's Maven plugin verifies all three feature descriptors against Java 17 and Karaf 4.4.11. The GitHub workflow repeats the build on Java 17 and 21. Live Karaf smoke checks are separate from the default Maven suite.
+
+For a clean-room check, create an empty settings file and choose a fresh cache directory:
+
+```xml
+<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"/>
+```
+
+```sh
+mvn -s /path/to/empty-settings.xml -gs /path/to/empty-settings.xml   -Dmaven.repo.local=/path/to/fresh-cache clean install
+```
+
+Use the same settings and cache when building the example. No private parent, account, sibling repository, or DrRemote Runtime is needed.
+
+## Changes
+
+- Keep existing public Maven artifact names and exported API packages stable.
+- Add regression tests for changed database behavior; use temporary databases/files.
+- Keep Java 17 compatibility and all project content in English.
+- Use parameterized SQL for values. Do not add real credentials or deployment state.
+- Keep dependency versions and feature descriptors aligned through the parent POM.
+- Update configuration/examples and the changelog when behavior changes.
+
+Publishing and release credentials are not part of the build. A successful `mvn install` does not imply a public artifact release.