Merge pull request #15 from supabase/docs

Update docs

Cargo.toml

@@ -2,6 +2,13 @@
 name = "postgrest"
 version = "0.1.0"
 authors = ["Bobbie Soedirgo <[email protected]>"]
+description = "PostgREST client-side library"
+homepage = "https://github.com/supabase/postgrest-rs"
+repository = "https://github.com/supabase/postgrest-rs"
+readme = "README.md"
+license = "Apache-2.0 OR MIT"
+keywords = ["postgres", "postgrest", "rest", "api"]
+categories = ["development-tools"]
 edition = "2018"
 
 [dependencies]

LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Bobbie Soedirgo
+Copyright (c) 2020 Supabase
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -7,26 +7,122 @@
 
 ## Usage
 
-TODO
+Generally, you want to instantiate a `Postgrest` struct, optionally switch
+schema with `.schema()`, call `.from()` (or `.rpc()` for stored procedures), do
+some filtering and stuff, and then call `.execute()`.
+
+Simple example:
+
+```rust
+use postgrest::Postgrest;
+
+let client = Postgrest::new("https://your-postgrest-endpoint");
+let resp = client
+ .from("your_table")
+ .select("*")
+ .execute()
+ .await?;
+let body = resp
+ .text()
+ .await?;
+```
+
+Using filters:
+
+```rust
+let resp = client
+ .from("your_table")
+ .eq("country", "Germany")
+ .gte("id", "20")
+ .select("*")
+ .execute()
+ .await?;
+```
+
+Updating a table:
+
+```rust
+let resp = client
+ .from("your_table")
+ .eq("username", "soedirgo")
+ .update("{\"organization\": \"supabase\"}")
+ .execute()
+ .await?;
+```
+
+Executing stored procedures:
+
+```rust
+let resp = client
+ .rpc("add", "{\"a\": 1, \"b\": 2}")
+ .execute()
+ .await?;
+```
+
+_Not enough filters_:
+
+```rust
+let resp = client
+ .from("countries")
+ .eq("name", "New Zealand")
+ .gt("id", "20")
+ .lt("id", "20")
+ .gte("id", "20")
+ .lte("id", "20")
+ .like("name", "%United%")
+ .ilike("name", "%United%")
+ .is("name", "null")
+ .in_("name", vec!["China", "France"])
+ .neq("name", "China")
+ .fts("phrase", "The Fat Cats", Some("english"))
+ .plfts("phrase", "The Fat Cats", None)
+ .phfts("phrase", "The Fat Cats", Some("english"))
+ .wfts("phrase", "The Fat Cats", None)
+ .cs("countries", "(10,20)")
+ .cd("countries", "(10,20)")
+ .ov("population_range", (100, 500))
+ .sl("population_range", (100, 500))
+ .sr("population_range", (100, 500))
+ .nxl("population_range", (100, 500))
+ .nxr("population_range", (100, 500))
+ .adj("population_range", (100, 500))
+ .select("*")
+ .execute()
+ .await?;
+```
+
+More examples incoming!
+
+## Limitations
+
+This library doesn't show the full extent of PostgREST, and definitely doesn't
+replace the need to learn PostgREST. Some known limitations are:
+
+- Doesn't support `not`, `and`, and `or` in filtering
+- Many inputs are unsanitized (multi-column select, insert/update body, etc.)
+- Counting (with HEAD verb)
+- Resource embedding (embedded filters, etc.)
+
+That said, if there are any features you want in, feel free to create an issue!
 
 ## Contributing
 
-- Fork the repo on GitHub
-- Clone the project to your own machine
-- Commit changes to your own branch
-- Push your work back up to your fork
-- Submit a Pull request so that we can review your changes and merge
+-  Fork the repo on GitHub
+-  Clone the project to your own machine
+-  Commit changes to your own branch
+-  Push your work back up to your fork
+-  Submit a Pull request so that we can review your changes and merge
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
-dual licensed as above, without any additional terms or conditions.
+dual licensed as below, without any additional terms or conditions.
 
 ## License
 
 Licensed under either of
 
-* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
- http://www.apache.org/licenses/LICENSE-2.0)
-* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+-  Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
+-  MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.

src/lib.rs

@@ -1,3 +1,57 @@
+//! # postgrest-rs
+//!
+//! [PostgREST](https://postgrest.org) client-side library.
+//!
+//! This library brings an ORM-like interface to PostgREST.
+//!
+//! ## Usage
+//!
+//! Simple example:
+//! ```ignore
+//! use postgrest::Postgrest;
+//!
+//! let client = Postgrest::new("https://your-postgrest-endpoint");
+//! let resp = client
+//! .from("your_table")
+//! .select("*")
+//! .execute()
+//! .await?;
+//! let body = resp
+//! .text()
+//! .await?;
+//! ```
+//!
+//! Using filters:
+//! ```ignore
+//! let resp = client
+//! .from("your_table")
+//! .eq("country", "Germany")
+//! .gte("id", "20")
+//! .select("*")
+//! .execute()
+//! .await?;
+//! ```
+//!
+//! Updating a table:
+//! ```ignore
+//! let resp = client
+//! .from("your_table")
+//! .eq("username", "soedirgo")
+//! .update("{\"organization\": \"supabase\"}")
+//! .execute()
+//! .await?;
+//! ```
+//!
+//! Executing stored procedures:
+//! ```ignore
+//! let resp = client
+//! .rpc("add", "{\"a\": 1, \"b\": 2}")
+//! .execute()
+//! .await?;
+//! ```
+//!
+//! Check out the [README](https://github.com/supabase/postgrest-rs) for more examples.
+
 extern crate reqwest;
 
 mod builder;