Skip to content

Commit

Permalink
Update README.md corresponding to the split modules
Browse files Browse the repository at this point in the history
  • Loading branch information
ShreckYe committed Nov 20, 2024
1 parent 9a93c0e commit 90dc927
Show file tree
Hide file tree
Showing 3 changed files with 53 additions and 6 deletions.
55 changes: 51 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,46 @@

Only PostgreSQL with [Reactive PostgreSQL Client](https://vertx.io/docs/vertx-pg-client/java/) is currently supported.

## Experimental

This library is experimental now. The APIs are subject to change (especially those marked with
`@ExperimentalEvscApi`), the tests are incomplete, and please expect bugs and report them.

## Maven coordinate

```kotlin
"com.huanshankeji:exposed-vertx-sql-client-postgresql:$version"
"com.huanshankeji:exposed-vertx-sql-client-$module:$evscVersion"
```

## API documentation

See the [hosted API documentation](https://huanshankeji.github.io/exposed-vertx-sql-client/) for the APIs.

## Basic usage guide

Here is a basic usage guide. This project currently serves our own use, therefore, there are temporarily no detailed docs, APIs are experimental, tests are incomplete, and please expect bugs. To learn more in addition to the guide below, see the [hosted API documentation](https://huanshankeji.github.io/exposed-vertx-sql-client/), and see [DatabaseClient.kt](lib/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/DatabaseClient.kt) and [DatabaseClientSql.kt](lib/src/main/kotlin/com/huanshankeji/exposedvertxsqlclient/sql/DatabaseClientSql.kt) for the major APIs.
Here is a basic usage guide.

### Before v0.5.0

Add the PostgreSQL module, which was the only module, to your dependencies with the Gradle build script:

```kotlin
implementation("com.huanshankeji:exposed-vertx-sql-client-postgresql:0.4.0")
```

### Since v0.5.0

Add the core module to your dependencies with the Gradle build script:

```kotlin
implementation("com.huanshankeji:exposed-vertx-sql-client-core:$evscVersion")
```

And add an RDBMS module, for example, the PostgreSQL module:

```kotlin
implementation("com.huanshankeji:exposed-vertx-sql-client-postgresql:$evscVersion")
```

### Create a `DatabaseClient`

Expand Down Expand Up @@ -109,7 +140,15 @@ databaseClient.executeSingleUpdate(Examples.deleteIgnoreWhereStatement { id eq 2

#### Extension SQL DSL APIs

With these extension APIs, your code becomes more concise, but it might be more difficult when you need to compose statements or edit the code:
With the extension SQL DSL APIs, your code becomes more concise, but it might be more difficult when you need to compose statements or edit the code.

Gradle dependency configuration (only needed since v0.5.0):

```kotlin
implementation("com.huanshankeji:exposed-vertx-sql-client-sql-dsl:$evscVersion")
```

Example code:

```kotlin
databaseClient.insert(Examples) { it[name] = "A" }
Expand All @@ -131,10 +170,18 @@ val deleteRowCount2 = databaseClient.deleteIgnoreWhere(Examples) { id eq 2 }
assert(deleteRowCount2 == 1)
```

#### APIs using [Exposed GADT mapping](https://github.com/huanshankeji/exposed-adt-mapping)
#### Extension SQL DSL APIs with [Exposed GADT mapping](https://github.com/huanshankeji/exposed-adt-mapping)

Please read [that library's basic usage guide](https://github.com/huanshankeji/exposed-adt-mapping?tab=readme-ov-file#basic-usage-guide) first. Here are examples of this library that correspond to [that library's CRUD operations](https://github.com/huanshankeji/exposed-adt-mapping?tab=readme-ov-file#crud-operations).

Gradle dependency configuration (only needed since v0.5.0):

```kotlin
implementation("com.huanshankeji:exposed-vertx-sql-client-sql-dsl-with-mapper:$evscVersion")
```

Example code:

```kotlin
val directorId = 1
val director = Director(directorId, "George Lucas")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ package com.huanshankeji.exposedvertxsqlclient

import kotlin.annotation.AnnotationTarget.*

@RequiresOptIn("This API is experimental in the Exposed Vert.x SQL Client library.", RequiresOptIn.Level.WARNING)
@RequiresOptIn("This API is experimental. It may be changed in the future without notice.", RequiresOptIn.Level.WARNING)
@Retention(AnnotationRetention.BINARY)
// The ones commented out are what I think may be used in very few use cases.
@Target(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
package com.huanshankeji.exposedvertxsqlclient

@RequiresOptIn("This API is internal in the Exposed Vert.x SQL Client library.")
@RequiresOptIn("This API is internal in the Exposed Vert.x SQL Client library. It may be changed in the future without notice.")
@Retention(AnnotationRetention.BINARY)
annotation class InternalApi

0 comments on commit 90dc927

Please sign in to comment.