diff --git a/README.md b/README.adoc similarity index 55% rename from README.md rename to README.adoc index a6aabf319..06189d639 100644 --- a/README.md +++ b/README.adoc @@ -1,41 +1,46 @@ -# SQLite JDBC Driver -[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/xerial/sqlite-jdbc/ci.yml?branch=master)](https://github.com/xerial/sqlite-jdbc/actions/workflows/ci.yml?query=branch%3Amaster) -[![Join the chat at https://gitter.im/xerial/sqlite-jdbc](https://badges.gitter.im/xerial/sqlite-jdbc.svg)](https://gitter.im/xerial/sqlite-jdbc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.xerial/sqlite-jdbc/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.xerial/sqlite-jdbc/) -[![javadoc](https://javadoc.io/badge2/org.xerial/sqlite-jdbc/javadoc.svg)](https://javadoc.io/doc/org.xerial/sqlite-jdbc) -[![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/org.xerial/sqlite-jdbc?color=blue&label=maven%20snapshot&server=https%3A%2F%2Foss.sonatype.org%2F)](https://oss.sonatype.org/content/repositories/snapshots/org/xerial/sqlite-jdbc/) += SQLite JDBC Driver +:project-version: 3.41.2.1 -SQLite JDBC is a library for accessing and creating [SQLite](https://www.sqlite.org) database files in Java. +image:https://img.shields.io/github/actions/workflow/status/xerial/sqlite-jdbc/ci.yml?branch=master[GitHub Workflow Status (branch),link=https://github.com/xerial/sqlite-jdbc/actions/workflows/ci.yml?query=branch%3Amaster] +image:https://badges.gitter.im/xerial/sqlite-jdbc.svg[Join the chat,link=https://gitter.im/xerial/sqlite-jdbc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge] +image:https://maven-badges.herokuapp.com/maven-central/org.xerial/sqlite-jdbc/badge.svg[Maven Central,link=https://maven-badges.herokuapp.com/maven-central/org.xerial/sqlite-jdbc/] +image:https://javadoc.io/badge2/org.xerial/sqlite-jdbc/javadoc.svg[javadoc,link=https://javadoc.io/doc/org.xerial/sqlite-jdbc] +image:https://img.shields.io/nexus/s/org.xerial/sqlite-jdbc?color=blue&label=maven%20snapshot&server=https%3A%2F%2Foss.sonatype.org%2F[Sonatype Nexus (Snapshots),link=https://oss.sonatype.org/content/repositories/snapshots/org/xerial/sqlite-jdbc/] + +SQLite JDBC is a library for accessing and creating https://www.sqlite.org[SQLite] database files in Java. Our SQLiteJDBC library requires no configuration since native libraries for major OSs, including Windows, macOS, Linux etc., are assembled into a single JAR (Java Archive) file. -# Usage +== Usage -:arrow_right: More usage examples and configuration are available in [USAGE.md](USAGE.md) +➡️ More usage examples and configuration are available in link:USAGE.md[USAGE.md] -SQLite JDBC is a library for accessing SQLite databases through the JDBC API. For the general usage of JDBC, see [JDBC Tutorial](https://docs.oracle.com/javase/tutorial/jdbc/index.html) or [Oracle JDBC Documentation](https://www.oracle.com/technetwork/java/javase/tech/index-jsp-136101.html). +SQLite JDBC is a library for accessing SQLite databases through the JDBC API. For the general usage of JDBC, see https://docs.oracle.com/javase/tutorial/jdbc/index.html[JDBC Tutorial] or https://www.oracle.com/technetwork/java/javase/tech/index-jsp-136101.html[Oracle JDBC Documentation]. -1. [Download](#download) `sqlite-jdbc-(VERSION).jar` +. <> `sqlite-jdbc-{project-version}.jar` then append this jar file into your classpath. -2. Open a SQLite database connection from your code. (see the example below) +. Open a SQLite database connection from your code. (see the example below) + +=== Example usage -## Example usage -Assuming `sqlite-jdbc-(VERSION).jar` is placed in the current directory. +Assuming `sqlite-jdbc-{project-version}.jar` is placed in the current directory. -```shell +[source,shell,subs="attributes+"] +---- > javac Sample.java -> java -classpath ".;sqlite-jdbc-(VERSION).jar" Sample # in Windows +> java -classpath ".;sqlite-jdbc-{project-version}.jar" Sample # in Windows or -> java -classpath ".:sqlite-jdbc-(VERSION).jar" Sample # in macOS or Linux +> java -classpath ".:sqlite-jdbc-{project-version}.jar" Sample # in macOS or Linux name = leo id = 1 name = yui id = 2 -``` +---- -**Sample.java** +=== Sample.java -```java +[source,java] +---- import java.sql.Connection; import java.sql.DriverManager; import java.sql.ResultSet; @@ -87,36 +92,40 @@ id = 2 } } } -``` -# How does SQLiteJDBC work? -Our SQLite JDBC driver package (i.e., `sqlite-jdbc-(VERSION).jar`) contains three +---- + +== How does SQLiteJDBC work? + +Our SQLite JDBC driver package (i.e., `sqlite-jdbc-{project-version}.jar`) contains three types of native SQLite libraries (`sqlitejdbc.dll`, `sqlitejdbc.jnilib`, `sqlitejdbc.so`), each of them is compiled for Windows, macOS and Linux. An appropriate native library file is automatically extracted into your OS's temporary folder, when your program loads `org.sqlite.JDBC` driver. -## Supported Operating Systems +=== Supported Operating Systems + Since sqlite-jdbc-3.6.19, the natively compiled SQLite engines will be used for the following operating systems: -| | x86 | x86_64 | armv5 | armv6 | armv7 | arm64 | ppc64 | -|--------------|-----|--------|-------|-------|-------|-------|-------| -| Windows | ✔ | ✔ | | | ✔ | ✔ | | -| macOS | | ✔ | | | | ✔ | | -| Linux (libc) | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | -| Linux (musl) | ✔ | ✔ | | | | ✔ | | -| Android | ✔ | ✔ | ✔ | | | ✔ | | -| FreeBSD | ✔ | ✔ | | | | ✔ | | +|=== +| |x86 |x86_64 |armv5 |armv6 |armv7 |arm64 |ppc64 +|Windows |✔ |✔ | | |✔ |✔ | +|macOS | |✔ | | | |✔ | +|Linux (libc) |✔ |✔ |✔ |✔ |✔ |✔ |✔ +|Linux (musl) |✔ |✔ | | | |✔ | +|Android |✔ |✔ |✔ | | |✔ | +|FreeBSD |✔ |✔ | | | |✔ | +|=== In the other OSs not listed above, the pure-java SQLite is used. (Applies to versions before 3.7.15) -If you want to use the native library for your OS, [build the source from scratch](./CONTRIBUTING.md). +If you want to use the native library for your OS, link:./CONTRIBUTING.md[build the source from scratch]. -## GraalVM native-image support +=== GraalVM native-image support -Sqlite JDBC supports [GraalVM native-image](https://www.graalvm.org/native-image/) out of the box starting from version 3.40.1.0. +Sqlite JDBC supports https://www.graalvm.org/native-image/[GraalVM native-image] out of the box starting from version 3.40.1.0. There has been rudimentary support for some versions before that, but this was not actively tested by the CI. By default, the `sqlitejdbc` library for the compilation target will be included in the native image, accompanied by the required JNI configuration. @@ -127,15 +136,21 @@ As a result, the native image itself will be slightly smaller and the overhead o but you need to make sure the library can be found at run-time. The best way to do this is to simply place the library next to the executable. -### CLI example -```shell +==== CLI example + +[source,shell] +---- native-image -Dorg.sqlite.lib.exportPath=~/outDir -H:Path=~/outDir -cp foo.jar org.example.Main -``` +---- + This will place both the `sqlitejdbc` shared library and the native-image output in the `~/outDir` folder. -### Maven example -This example uses the [native-build-tools](https://graalvm.github.io/native-build-tools/latest/index.html) maven plugin: -```xml +=== Maven example + +This example uses the https://graalvm.github.io/native-build-tools/latest/index.html[native-build-tools] maven plugin: + +[source,xml] +---- org.graalvm.buildtools native-maven-plugin @@ -145,56 +160,62 @@ This example uses the [native-build-tools](https://graalvm.github.io/native-buil -``` +---- + This will automatically place the `sqlitejdbc` library in the `/target` folder of your project, creating a functional execution environment. When packaging the resulting app, simply include the library in the distribution bundle. -# Download +== Download -Download from [Maven Central](https://search.maven.org/artifact/org.xerial/sqlite-jdbc) or from the [releases](https://github.com/xerial/sqlite-jdbc/releases) page. +Download from https://search.maven.org/artifact/org.xerial/sqlite-jdbc[Maven Central] or from the https://github.com/xerial/sqlite-jdbc/releases[releases] page. -```xml +[source,xml,subs="attributes+"] +---- org.xerial sqlite-jdbc - (version) + {project-version} -``` +---- + +Snapshots of the development version are available in https://oss.sonatype.org/content/repositories/snapshots/org/xerial/sqlite-jdbc/[Sonatype's snapshots repository]. -Snapshots of the development version are available in [Sonatype's snapshots repository](https://oss.sonatype.org/content/repositories/snapshots/org/xerial/sqlite-jdbc/). +=== Project versioning explained -## Project versioning explained The project's version follows the version of the SQLite library that is bundled in the jar, with an extra digit to denote the project's increment. For example, if the SQLite version is `3.39.2`, the project version will be `3.39.2.x`, where `x` starts at 0, and increments with every release that is not changing the SQLite version. If the SQLite version is updated to `3.40.0`, the project version will be updated to `3.40.0.0`. -## Hint for maven-shade-plugin +=== Hint for maven-shade-plugin You may need to add shade plugin transformer to solve `No suitable driver found for jdbc:sqlite:` issue. -```xml +[source,xml] +---- META-INF/services/java.sql.Driver -``` +---- -```xml +[source,xml,subs="attributes+"] +---- org.xerial sqlite-jdbc - (version) + {project-version} -``` +---- -# How can I help? +== How can I help? We are always looking for: -- **Reviewers** for issues or PRs, you can check https://github.com/xerial/sqlite-jdbc/labels/review%20wanted -- **Contributors** to submit PRs, you can check https://github.com/xerial/sqlite-jdbc/labels/help%20wanted and https://github.com/xerial/sqlite-jdbc/labels/good%20first%20issue -Please read our [contribution](./CONTRIBUTING.md) guide. +- *Reviewers* for issues or PRs, you can check image:https://img.shields.io/github/labels/xerial/sqlite-jdbc/review%20wanted[GitHub labels,link=https://github.com/xerial/sqlite-jdbc/labels/review%20wanted] +- *Contributors* to submit PRs, you can check image:https://img.shields.io/github/labels/xerial/sqlite-jdbc/help%20wanted[GitHub labels,link=https://github.com/xerial/sqlite-jdbc/labels/help%20wanted] and image:https://img.shields.io/github/labels/xerial/sqlite-jdbc/good%20first%20issue[GitHub labels,link=https://github.com/xerial/sqlite-jdbc/labels/good%20first%20issue] + +Please read our link:./CONTRIBUTING.md[contribution] guide. \ No newline at end of file diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 000000000..9948452e2 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,15 @@ += Security Policy +:sqlite-version: 3.41.2 + +== Supported Versions + +|=== +|Version |Supported + +|{sqlite-version}.x |:white_check_mark: +|< {sqlite-version}.x |:x: +|=== + +== Reporting a Vulnerability + +See https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 398a729f9..000000000 --- a/SECURITY.md +++ /dev/null @@ -1,12 +0,0 @@ -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 3.41.x | :white_check_mark: | -| < 3.40.0| :x: | - -## Reporting a Vulnerability - -See https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability#privately-reporting-a-security-vulnerability