Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/supabase-community/postgrest-kt
Postgrest Kotlin Client
https://github.com/supabase-community/postgrest-kt
android java jvm kotlin postgresql postgrest supabase
Last synced: about 2 months ago
JSON representation
Postgrest Kotlin Client
- Host: GitHub
- URL: https://github.com/supabase-community/postgrest-kt
- Owner: supabase-community
- Archived: true
- Created: 2021-01-28T18:30:31.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-11-01T17:55:46.000Z (about 1 year ago)
- Last Synced: 2024-10-23T14:13:54.633Z (3 months ago)
- Topics: android, java, jvm, kotlin, postgresql, postgrest, supabase
- Language: Kotlin
- Homepage:
- Size: 103 KB
- Stars: 53
- Watchers: 5
- Forks: 8
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Kotlin Client for PostgREST
> **Warning**
> This repository is archived. Use [supabase-kt](https://github.com/supabase-community/supabase-kt) instead to use Supabase in your Kotlin projects.
Kotlin JVM client for [PostgREST](https://postgrest.org/)
## Installation
Maven
```xml
io.supabase
postgrest-kt
{version}
pom
```
Gradle
```
implementation 'io.supabase:postgrest-kt:{version}'
```
## Usage
### Initializing the client
```kotlin
val postgrestClient = PostgrestDefaultClient(
uri = URI("http://localhost:3111"),
headers = mapOf("Authorization" to "foobar")
)
```
You can also pass in a custom schema using the `schema` parameter.
### Entry points
There are two methods to start any call on the PostgresClient.
#### from
The `from` function is used for querying.
It takes a generic parameter to allow for auto-completion when defining column names.
However, you can always use `Any` if you are unsure about the data type.
```kotlin
postgresClient.from("messages")
.select()
.neq("content", "abc")
.execute()
postgresClient.from("messages")
.select()
.neq(Message::content, "abc")
.execute()
// select item_id AS itemId, age from messages...
postgresClient.from("messages")
.select("itemId:item_id,age")
.neq(Message::content, "abc")
.execute()
// https://postgrest.org/en/stable/api.html#embedding-top-level-filter
postgresClient.from("messages")
.select("name,age,company(name, address, phone)")
.neq(Message::content, "abc")
.execute()
```
#### rpc
The `rpc` function executes a stored procedure.
```kotlin
postgresClient.rpc("get_status", mapOf("foo" to "bar"))
.execute()
```
### Executing requests
There are three ways to execute requests and read the response.
#### execute
The `execute` method returns a [PostgrestHttpResponse](src/main/kotlin/io/supabase/postgrest/http/PostgrestHttpResponse.kt).
The HttpResponse contains the status code, body as string and the count (if you request the count).
```kotlin
val response = postgresClient.from("messages")
.select()
.execute()
println(response.body)
println(response.status)
println(response.count)
```
#### executeAndGetSingle
The `executeAndGetSingle` function returns `T`.
The JSON converter is used to convert the response to the DTO.
```kotlin
data class Message(
val id: Long,
val content: String
)
val message = postgresClient.from("messages")
.select()
.eq(Message::id, 123L)
.limit(1)
.single()
.executeAndGetSingle()
println(message.content)
```
You can also use this function to convert your data to a Map, rather than a separate DTO.
```kotlin
val message = postgresClient.from("messages")
.select()
.eq(Message::id, 123L)
.limit(1)
.single()
.executeAndGetSingle>()
println(message["content"])
```
#### executeAndGetList
The `executeAndGetList` function is pretty much the same as the `executeAndGetSingle` function, however,
this functions returns a list of `T`.
```kotlin
val messages = postgresClient.from("messages")
.select()
.executeAndGetList()
messages.forEach { message ->
println(messege.content)
}
```
### CRUD
#### Selecting data
The `select` function is used for selecting data.
```kotlin
val response = postgresClient.from("messages")
.select(count = Count.EXACT) // will allow accessing data AND count
.eq("content", "foobar")
.execute()
```
#### Inserting data
The `insert` function is used for inserting or upserting data.
```kotlin
val message = Message(
id = 123L,
content = "foobar"
)
val response = postgresClient.from("messages")
.insert(message)
.execute()
val response = postgresClient.from("messages")
.insert(
value = mapOf("id" to 123L, "content" to "foobar"),
upsert = true
)
```
#### Updating data
The `update` function is used for updating data.
```kotlin
val response = postgresClient.from("messages")
.update(mapOf("content" to "hello"))
.eq("id", 123L)
.execute()
```
#### Deleting data
The `delete` function is used for deleting data.
```kotlin
val response = postgresClient.from("messages")
.delete()
.eq("id", 123L)
.execute()
```
## HTTP / (De)-Serialization
The Apache Http-Client (5.x) is used for executing HTTP calls, Jackson is used to convert responses to DTOs.
If you want to change that, you need to implement the `PostgrestHttpClient` and the `PostgrestJsonConverter` interface.
See [PostgrestHttpClientApache](src/main/kotlin/io/supabase/postgrest/http/PostgrestHttpClientApache.kt) and [PostgrestsonConverterJackson](src/main/kotlin/io/supabase/postgrest/json/PostgrestJsonConverterJackson.kt).
```kotlin
val postgrestClient = PostgrestClient(
httpClient = customHttpClient(),
jsonConverter = customConverter()
)
```