Expand description
Skytable client
Introduction
This library is the official client for the free and open-source NoSQL database Skytable. First, go ahead and install Skytable by following the instructions here. This library supports all Skytable versions that work with the Skyhash 1.1 Protocol. This version of the library was tested with the latest Skytable release (release 0.7.5).
Features
- Sync API
- Async API
- TLS in both sync/async APIs
- Query pipelining
- Easy conversion from Skyhash types into Rust types
- Connection pooling for sync/async
- Use both sync/async APIs at the same time
- Always up-to-date
Using this library
This library only ships with the bare minimum that is required for interacting with Skytable. Once you have Skytable installed and running, you’re ready to follow this guide!
We’ll start by creating a new binary application and then running actions. Create a new binary application by running:
cargo new skyapp
Tip: You can see a full list of the available actions here.
First add this to your Cargo.toml
file:
skytable = "0.7.0-alpha.4"
Now open up your src/main.rs
file and establish a connection to the server while also adding some
imports:
use skytable::{Connection, Query, Element, SkyResult};
fn main() -> SkyResult<()> {
let mut con = Connection::new("127.0.0.1", 2003)?;
Ok(())
}
Now let’s run a Query
! Change the previous code block to:
use skytable::{error, Connection, Query, Element};
fn main() -> Result<(), error::Error> {
let mut con = Connection::new("127.0.0.1", 2003)?;
let query = Query::from("heya");
let res: String = con.run_query(&query)?;
assert_eq!(res, "HEY!");
Ok(())
}
Running actions
As noted below, the default table is a key/value table with a binary key
type and a binary value type. Let’s go ahead and run some actions (we’re assuming you’re
using the sync API; for async, simply change the import to use skytable::actions::AsyncActions
).
SET
ting a key
use skytable::actions::Actions;
use skytable::sync::Connection;
let mut con = Connection::new("127.0.0.1", 2003).unwrap();
con.set("hello", "world").unwrap();
This will set the value of the key hello
to world
in the default:default
entity.
GET
ting a key
use skytable::actions::Actions;
use skytable::sync::Connection;
let mut con = Connection::new("127.0.0.1", 2003).unwrap();
let x: String = con.get("hello").unwrap();
assert_eq!(x, "world");
Way to go — you’re all set! Now go ahead and run more advanced queries!
Binary data
The default:default
keyspace has the following declaration:
Keymap { data:(binstr,binstr), volatile:false }
This means that the default keyspace is ready to store binary data. Let’s say
you wanted to SET
the value of a key called bindata
to some binary data stored
in a Vec<u8>
. You can achieve this with the RawString
type:
use skytable::actions::Actions;
use skytable::sync::Connection;
use skytable::types::RawString;
let mut con = Connection::new("127.0.0.1", 2003).unwrap();
let mybinarydata = RawString::from(vec![1, 2, 3, 4]);
assert!(con.set("bindata", mybinarydata).unwrap());
Going advanced
Now that you know how you can run basic queries, check out:
- the
actions
module documentation for learning to use actions - the
Pipeline
documentation for using pipelines - the
pool
module documentation for using sync/async connection pools - the
types
module documentation for implementing your own Skyhash serializable types. - the
ddl
module for DDL queries likecreate
anddrop
You can also find some examples here.
Pipelining
Check out the documentation for Pipeline
.
Connection pooling
This library supports using sync/async connection pools. See the pool
module-level documentation for examples
and information.
Async API
If you need to use an async
API, just change your import to:
skytable = { version = "0.7.0-alpha.4", features=["aio"], default-features = false }
You can now establish a connection by using skytable::AsyncConnection::new()
, adding .await
s wherever
necessary. Do note that you’ll the Tokio runtime.
Using both sync
and async
APIs
With this client driver, it is possible to use both sync and async
APIs at the same time. To do
this, simply change your import to:
skytable = { version="0.7.0-alpha.4", features=["sync", "aio"] }
TLS
If you need to use TLS features, this crate will let you do so with OpenSSL.
Using TLS with sync interfaces
skytable = { version="0.7.0-alpha.4", features=["sync","ssl"] }
You can now use the async sync::TlsConnection
object.
Using TLS with async interfaces
skytable = { version="0.7.0-alpha.4", features=["aio","aio-ssl"], default-features=false }
You can now use the async aio::TlsConnection
object.
Packed TLS setup
If you want to pack OpenSSL with your crate, then for sync add sslv
instead of ssl
or
add aio-sslv
instead of aio-ssl
for async. Adding this will statically link OpenSSL
to your crate. Do note that you’ll need a C compiler, GNU Make and Perl to compile OpenSSL
and statically link against it.
MSRV
The MSRV for this crate is Rust 1.39. Need const generics? Add the const-gen
feature to your
dependency!
Contributing
Open-source, and contributions … — they’re always welcome! For ideas and suggestions, create an issue on GitHub and for patches, fork and open those pull requests here!
License
This client library is distributed under the permissive Apache-2.0 License. Now go build great apps!
Re-exports
pub use aio::Connection as AsyncConnection;
aio
pub use sync::Connection;
sync
Modules
Actions
aio
Asynchronous database connections
Data definition Language (DDL) Queries
Errors
Connection pooling
sync
Synchronous database connections
Types
Macros
A macro that can be used to easily create queries with almost variadic properties. Where you’d normally create queries like this:
Structs
A connection builder for easily building connections
Pipeline
This struct represents a single simple query as defined by the Skyhash protocol
Enums
Constants
The default entity
The default host address
The default port
Type Definitions
aio
A special result that is returned when running actions (async)
A result type for queries
A generic result type