Merge pull request #528 from scylladb/schema_doc

docs: add an entry about inspecting schema

Author: piodul

docs/source/SUMMARY.md

@@ -63,3 +63,5 @@
     - [Tracing a batch query](tracing/batch.md)
     - [Tracing a paged query](tracing/paged.md)
     - [Tracing `Session::prepare`](tracing/prepare.md)
+
+- [Database schema](schema/schema.md)

docs/source/contents.rst

@@ -14,7 +14,4 @@
    metrics/metrics
    logging/logging
    tracing/tracing
-
-
-
-
+   schema/schema

docs/source/index.md

@@ -21,3 +21,4 @@ Although optimized for Scylla, the driver is also compatible with [Apache Cassan
 * [Driver metrics](metrics/metrics.md) - Statistics about the driver - number of queries, latency etc.
 * [Logging](logging/logging.md) - Viewing and integrating logs produced by the driver
 * [Query tracing](tracing/tracing.md) - Tracing query execution
+* [Database schema](schema/schema.md) - Fetching and inspecting database schema

docs/source/schema/schema.md

@@ -0,0 +1,68 @@
+# Schema
+
+The driver is capable of fetching database schema and presenting it to its users.
+
+## Fetching schema
+
+Fetching database schema occurs periodically, but it can also be done on-demand. In order to fetch the newest database schema, one can call `refresh_metadata()` on a Session instance: 
+```rust
+# extern crate scylla;
+# extern crate tokio;
+# use std::error::Error;
+# use scylla::{Session, SessionBuilder};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let uri = std::env::var("SCYLLA_URI")
+        .unwrap_or_else(|_| "127.0.0.1:9042".to_string());
+
+    let session: Session = SessionBuilder::new().known_node(uri).build().await?;
+    // Schema metadata will be fetched below
+    session.refresh_metadata().await?;
+    Ok(())
+}
+```
+
+## Inspecting schema
+
+Once fetched, a snapshot of cluster's schema can be examined. The following information can be obtained:
+ - keyspace
+   - tables belonging to the keyspace
+   - materialized views belonging to the keyspace
+   - replication strategy
+   - user-defined types
+ - table/view
+   - primary key definition
+   - columns
+   - partitioner type
+
+Example showing how to print obtained schema information:
+
+```rust
+# extern crate scylla;
+# extern crate tokio;
+# use std::error::Error;
+# use scylla::{Session, SessionBuilder};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let uri = std::env::var("SCYLLA_URI")
+        .unwrap_or_else(|_| "127.0.0.1:9042".to_string());
+
+    let session: Session = SessionBuilder::new().known_node(uri).build().await?;
+    // Schema metadata will be fetched below
+    session.refresh_metadata().await?;
+
+    let cluster_data = &session.get_cluster_data();
+    let keyspaces = &cluster_data.get_keyspace_info();
+
+    for (keyspace_name, keyspace_info) in keyspaces.iter() {
+        println!("Keyspace {}:", keyspace_name);
+        println!("\tTables: {:#?}", keyspace_info.tables);
+        println!("\tViews: {:#?}", keyspace_info.views);
+        println!("\tUDTs: {:#?}", keyspace_info.user_defined_types);
+    }
+
+    Ok(())
+}
+```