# xerial/sqlite-jdbc architecture

> Architecture diagram of the GitHub repository xerial/sqlite-jdbc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xerial/sqlite-jdbc
- Repository: https://github.com/xerial/sqlite-jdbc

## Overview

##### Project type and purpose
- This is a Java library—a JDBC driver that embeds the SQLite native engine.
- Purpose: expose SQLite database functionality through standard Java JDBC interfaces, auto-extracting an OS-specific native library at runtime, and supporting GraalVM native-image builds.

##### File-structure overview
- Top level
- pom.xml / Makefile / Dockerfiles / GitHub workflows → build, CI, cross-compile.
- src/main/java/org/sqlite → core JDBC driver classes (Driver, Connection, Statement, ResultSet, Configuration, listeners).
- src/main/java/org/sqlite/core → JNI wrapper (NativeDB.java / NativeDB.c) and core DB metadata + statement implementations.
- src/main/java/org/sqlite/util, /date, /jdbc3, /jdbc4, /javax → utility, backward-compatibility, javax-pool support.
- src/main/resources/org/sqlite/native/... → prebuilt native libraries (.so/.dll/.dylib) for each OS/arch.
- src/main/ext/extension-functions.c → custom SQLite UDF extension code.
- src/test & src/test/resources → unit/integration tests, sample DBs.
- demo/ → sample usage.
- docker/ → cross-compilation Docker images and scripts.
- README.adoc and USAGE.md describe usage, architecture, GraalVM support.

A. Java client code (your application)
B. JDBC API layer (java.sql.* interfaces)
C. org.sqlite.JDBC driver
- DriverManager registration → Driver class
- SQLiteJDBCLoader / ResourceFinder → finds correct native lib in JAR
- Extraction to OS temp folder
- System.load → loads JNI library
D. JNI bridge (NativeDB.java + NativeDB.c)
- JNI methods map Java calls (open, execSQL, prepare) to C API
E. SQLite native engine (C library)
- .so/.dll/.dylib code executed via JNI
- Filesystem interaction: reads/writes .db file
F. Optional GraalVM native-image integration
- native-build-tools plugin configuration
- Resource config under META-INF/native-image
G. Build & CI
- Maven (pom.xml) + shade plugin
- Docker cross-compile scripts (docker/)
- GitHub Actions workflows (.github/workflows)

##### Relationships & interactions
- Bi-directional data flows for queries/results.
- Extension functions loaded from src/main/ext.

##### Architectural patterns & principles
- Wrapper / Adapter pattern: JDBC interfaces adapted to native C via JNI.
- Auto-configuration: packaged native libs + ResourceFinder.
- Modularity: separate packages for core, util, date, JDBC3 vs JDBC4, javax.
- Cross-platform packaging: native libraries per OS/arch bundled in one JAR.

##### Detail capture
- Native-extraction process (ResourceFinder → temp folder → System.load).
- Where extension UDF code plugs in.
- Test harness (src/test) only if diagramming end-to-end CI build.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Java Layer" 
        classDef java fill:#AED6F1,stroke:#1B4F72;
        Demo["Java Client Code"]:::java
        JDBCAPI["JDBC API Layer (java.sql)"]:::java
        Driver["org.sqlite.JDBC Driver"]:::java
        LoaderLM["SQLiteJDBCLoader"]:::java
        ResourceFinder["ResourceFinder"]:::java
        Config["SQLiteConfig"]:::java
        CommitListener["SQLiteCommitListener"]:::java
        UpdateListener["SQLiteUpdateListener"]:::java
        Connection["SQLiteConnection"]:::java
        DataSource["SQLiteDataSource"]:::java
        CoreStatement["CoreStatement"]:::java
        CorePrepared["CorePreparedStatement"]:::java
        CoreResultSet["CoreResultSet"]:::java
    end

    subgraph "JNI Bridge" 
        classDef jni fill:#F5B041,stroke:#9A7D0A;
        JNIJava["NativeDB.java"]:::jni
        JNIC["NativeDB.c"]:::jni
    end

    subgraph "Native Layer"
        classDef native fill:#ABEBC6,stroke:#1D8348;
        DB["DB Wrapper (DB.java)"]:::native
        Meta["CoreDatabaseMetaData"]:::native
        UDF["Extension UDFs"]:::native
        NativeLib["Prebuilt Native Libraries"]:::native
        SQLiteEngine["SQLite Native Engine"]:::native
        Filesystem["Filesystem (.db files)"]:::native
    end

    subgraph "GraalVM Integration"
        classDef graal fill:#D2B4DE,stroke:#6C3483;
        GraalFeature["SqliteJdbcFeature"]:::graal
        NativeProps["native-image.properties"]:::graal
    end

    subgraph "Build & CI"
        classDef build fill:#ABB2B9,stroke:#566573;
        Maven["Maven Build (pom.xml)"]:::build
        Makefile["Makefile"]:::build
        MakefileCommon["Makefile.common"]:::build
        Docker["docker/"]:::build
        CI1["CI Workflow (ci.yml)"]:::build
        CI2["CI Workflow (build-native.yml)"]:::build
        Tests["Unit & Integration Tests"]:::build
    end

    %% Data flows
    Demo -->|"DriverManager.getConnection()"| JDBCAPI
    JDBCAPI -->|uses| Driver
    Driver -->|loads| LoaderLM
    LoaderLM -->|invokes| ResourceFinder
    ResourceFinder -->|finds native lib| NativeLib
    NativeLib -->|extracted to temp| LoaderLM
    LoaderLM -->|System.load JNI lib| JNIJava
    Driver -->|creates| Connection
    Connection -->|prepare/execute| CorePrepared
    CorePrepared -->|execSQL| CoreStatement
    Connection -->|createStatement| CoreStatement
    CoreStatement -->|uses| JNIJava
    CorePrepared -->|uses| JNIJava
    JNIJava -->|JNI call| JNIC
    JNIC -->|calls C API| SQLiteEngine
    UDF -->|registered with| SQLiteEngine
    SQLiteEngine -->|read/write| Filesystem

    %% GraalVM path
    Maven -->|configures| GraalFeature
    GraalFeature -->|reads| NativeProps

    %% CI & Build
    Maven -->|builds| Driver
    Makefile -->|scripts| Maven
    MakefileCommon -->|includes| Makefile
    Docker -->|cross-compile images| Maven
    CI1 -->|runs| Maven
    CI1 -->|runs| Tests
    CI2 -->|builds native-image| GraalFeature

    %% Click Events
    click Demo "https://github.com/xerial/sqlite-jdbc/blob/master/demo/Sample.java"
    click JDBCAPI "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/resources/java.sql.Driver"
    click Driver "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/JDBC.java"
    click LoaderLM "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/SQLiteJDBCLoader.java"
    click ResourceFinder "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/util/ResourceFinder.java"
    click Config "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/SQLiteConfig.java"
    click CommitListener "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/SQLiteCommitListener.java"
    click UpdateListener "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/SQLiteUpdateListener.java"
    click Connection "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/SQLiteConnection.java"
    click DataSource "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/SQLiteDataSource.java"
    click CoreStatement "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/core/CoreStatement.java"
    click CorePrepared "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/core/CorePreparedStatement.java"
    click CoreResultSet "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/core/CoreResultSet.java"
    click JNIJava "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/core/NativeDB.java"
    click JNIC "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/core/NativeDB.c"
    click DB "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/core/DB.java"
    click Meta "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java/org/sqlite/core/CoreDatabaseMetaData.java"
    click UDF "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/ext/extension-functions.c"
    click NativeLib "https://github.com/xerial/sqlite-jdbc/tree/master/src/main/resources/org/sqlite/native/"
    click GraalFeature "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/java9/org/sqlite/nativeimage/SqliteJdbcFeature.java"
    click NativeProps "https://github.com/xerial/sqlite-jdbc/blob/master/src/main/resources/META-INF/native-image/org.xerial/sqlite-jdbc/native-image.properties"
    click Maven "https://github.com/xerial/sqlite-jdbc/blob/master/pom.xml"
    click Makefile "https://github.com/xerial/sqlite-jdbc/tree/master/Makefile"
    click MakefileCommon "https://github.com/xerial/sqlite-jdbc/blob/master/Makefile.common"
    click Docker "https://github.com/xerial/sqlite-jdbc/blob/master/docker/updatescripts.sh"
    click CI1 "https://github.com/xerial/sqlite-jdbc/blob/master/.github/workflows/ci.yml"
    click CI2 "https://github.com/xerial/sqlite-jdbc/blob/master/.github/workflows/build-native.yml"
    click Tests "https://github.com/xerial/sqlite-jdbc/tree/master/src/test/java/org/sqlite/"
    
    %% Styles
    class Demo,JDBCAPI,Driver,LoaderLM,ResourceFinder,Config,CommitListener,UpdateListener,Connection,DataSource,CoreStatement,CorePrepared,CoreResultSet java
    class JNIJava,JNIC jni
    class DB,Meta,UDF,NativeLib,SQLiteEngine,Filesystem native
    class GraalFeature,NativeProps graal
    class Maven,Makefile,MakefileCommon,Docker,CI1,CI2,Tests build
```
