OrafitSQL

English | 日本語 | Project page

Run Oracle-oriented Java applications on PostgreSQL with a bounded JDBC compatibility layer.

OrafitSQL translates supported Oracle SQL at runtime and provides Oracle-compatible behavior on PostgreSQL through oracle_compat. When a statement cannot be translated safely, OrafitSQL rejects it instead of silently changing its meaning.

OrafitSQL is not a full Oracle emulator. Check the Oracle compatibility matrix before using it for a migration.

How it works

flowchart LR
    A["Java application"] -->|"Oracle SQL / JDBC"| B["OrafitSQL JDBC Driver"]
    B -->|"Translated SQL"| C["pgJDBC"]
    C --> D["PostgreSQL + oracle_compat"]

Loading

Component	Responsibility
OrafitSQL JDBC Driver	Oracle SQL recognition and rewriting, bind lineage, JDBC behavior, metadata, and fail-closed admission
pgJDBC	PostgreSQL connectivity
oracle_compat	Runtime value/type/error semantics that need PostgreSQL values or concrete server-side parameter types

The JDBC layer decides whether an Oracle form can be translated safely. oracle_compat does not parse Oracle SQL; it provides only the database-side semantics required by translated SQL. pgJDBC is required separately and is not bundled with OrafitSQL.

Quick start

Building requires JDK 17 or newer. You do not need to install Maven separately.

git clone https://github.com/yukkes/OrafitSQL.git
cd OrafitSQL
./build.sh

mvnw always uses the Maven version pinned by this repository and a project-local Maven repository under .mvn/. On the first online build it downloads the pinned Maven runtime, verifies its SHA-512 checksum, and resolves the required Maven dependencies into that local repository. Maven always compiles OrafitSQL with --release 17.

The JDBC JAR is created under build/.

To run OrafitSQL, use PostgreSQL 16 or 17 and keep pgJDBC on the application classpath together with the OrafitSQL JDBC JAR.

Install oracle_compat on PostgreSQL using either the native extension or plain-SQL path described in extension/README.md. The plain-SQL path is intended for managed environments such as Aurora PostgreSQL Serverless v2.

Then configure the application to use OrafitSQL:

driver=io.github.orafitsql.jdbc.OrafitSqlDriver
url=jdbc:orafit://<host>:<port>/<database>

Offline build

Offline builds use the same Maven runtime and the same project-local Maven repository as normal builds. There is no separate offline build implementation.

The Offline Build Kit GitHub Actions workflow runs the normal ./build.sh, verifies that the populated Maven environment works with networking disabled at the Maven level, and publishes a source-inclusive artifact containing:

• the exact tested OrafitSQL source snapshot;
• the repository-pinned Maven runtime;
• the complete project-local Maven repository required by the build.

A JDK is intentionally not bundled. Any JDK 17 or newer can run the build while compilation remains fixed to Java 17 through --release 17.

After downloading the .tar.zst file and matching .sha256 file from the Offline Build Kit Actions artifact:

sha256sum -c orafitsql-offline-build-kit-<sha>.tar.zst.sha256
tar --zstd -xf orafitsql-offline-build-kit-<sha>.tar.zst
cd orafitsql
./build.sh

After the artifact is downloaded, no Git checkout, separate Maven installation, or Maven network access is required. mvnw detects the build-kit marker and runs the same project-local Maven environment in offline mode.

See CONTRIBUTING.md for the complete build and test workflow.

Compatibility scope

OrafitSQL supports a deliberately bounded Oracle SQL/JDBC surface.

Area	Representative examples
SQL semantics	DUAL, Oracle empty-string/NULL, concatenation, selected implicit conversions, date/number/string behavior
Query syntax	bounded ROWNUM, legacy outer joins, selected hierarchical queries and aggregation
DML and JDBC	selected MERGE, RETURNING ... INTO, bind ordering, metadata, update counts, and error behavior

Unsupported or ambiguous forms fail closed. Full PL/SQL, Oracle administration and data dictionary behavior, arbitrary proprietary Oracle JDBC APIs, and environment-dependent behavior such as unbounded NLS semantics are outside the runtime migration boundary.

Use the Oracle compatibility matrix as the source of truth for supported subsets, deliberate rejections, and migration pre-checks.

Supported PostgreSQL targets

Target	Status
PostgreSQL 17	Primary supported version
PostgreSQL 16	Supported version
Aurora PostgreSQL 17 Serverless v2	Supported through the plain-SQL oracle_compat path
Aurora PostgreSQL 16 Serverless v2	Supported through the plain-SQL oracle_compat path
PostgreSQL 18	Compatibility check only
PostgreSQL 15 and older	Not supported

CI validates native and plain-SQL deployment on upstream PostgreSQL 16 and 17. Aurora support refers to the plain-SQL deployment contract; it does not mean every release is exercised on a live Aurora cluster.

Validation

The executable Oracle compatibility reference is Oracle Database 18c XE. Automatic main CI runs the canonical Oracle-visible contract against that reference and compares supported behavior with PostgreSQL 16 and 17.

Oracle-visible cases live in compat/oracle/cases/**/*.toml. Oracle 19c+ behavior is not part of the compatibility contract unless the behavior also exists in Oracle 18c and is represented by that executable case inventory.

See Validation for the full test and release-authority model.

Development

All Maven commands go through the repository launcher:

./mvnw test    # Java tests with JUnit 5
./mvnw verify  # Full Java/Maven gate
./build.sh     # Full local repository gate

See CONTRIBUTING.md for formatting and PostgreSQL integration tests.

Contributing and community

Contributions are welcome from first-time and experienced contributors. Issues and pull requests may be written in English or Japanese.

Start with CONTRIBUTING.md. It explains issue selection, pull-request scope, local validation, and compatibility evidence. Project decisions and maintainer roles are described in GOVERNANCE.md.

Please follow the Code of Conduct. Security vulnerabilities must be reported using SECURITY.md, not through ordinary public issue details.

Documentation

Topic	Document
Compatibility and migration scope	Oracle compatibility matrix
Install oracle_compat	extension/README.md
Build, test, and contribute	CONTRIBUTING.md
Project governance	GOVERNANCE.md
Support channels	SUPPORT.md
Security reporting	SECURITY.md
Architecture	maintainers/architecture.md
Validation	maintainers/validation.md
Release process	maintainers/releasing.md
Changes	CHANGELOG.md

License

OrafitSQL is released under the MIT License. See THIRD_PARTY_NOTICES.md for third-party notices.