What’s New in YugabyteDB Docs – December 2020

Welcome to this latest post on what’s new and improved in YugabyteDB Docs! We’re continually adding to and updating the documentation to give you the information you need to make the most out of YugabyteDB.

As a reminder, YugabyteDB provides two distributed SQL APIs:

• Yugabyte Structured Query Language (YSQL) is a fully-relational, PostgreSQL-compatible API.
• Yugabyte Cloud Query Language (YCQL) is a semi-relational API with document data modeling and has its roots in the Apache Cassandra Query Language (CQL).

Below you will find all the new documentation we’ve been steadily adding into our docs for both of these  APIs, as well as Yugabyte Platform, a browser-based UI for building your own private YugabyteDB-as-a-Service. If you have any questions, comments, or requests for new documentation, let us know in the YugabyteDB Community Slack.

With that, here’s what’s new and improved in YugabyteDB docs …

Multi-Region Deployments

YugabyteDB supports a comprehensive set of multi-region deployment topologies, including these popular deployment models:

• Default synchronous replication across regions
• Geo-partitioning to keep data pinned to different geographic locations based on policy
• xCluster asynchronous replication for unidirectional and bidirectional replication
• Read replicas which internally use asynchronous replication and can only serve reads

We put together an overview of multi-region deployment options, including a comparison table for easy reference. We also introduced new documentation so you can learn more about the newly released (as of YugabyteDB 2.5) row-level geo-partitioning feature in YSQL that allows fine-grained control over pinning data in a user table (at a per-row level) to geographic locations, thereby allowing the data residency to be managed at the database level. Geo-partitioning allows you to move data closer to the user and is beneficial for several use cases, including: achieving lower latency and higher performance, and meeting data residency requirements to comply with regulations such as GDPR. Within the multi-region deployment documentation, we also updated both the synchronous replication (YSQL and YCQL) and asynchronous replication documentation.

Database Security

There have also been a number of additions to the Secure section of the Docs including:

Authentication

YugabyteDB supports a variety of methods to verify that users and clients are who they say they are. We recently added new documentation specifically on these authentication methods:

• LDAP Authentication: In YSQL, you can use an external LDAP service to perform client authentication. Before LDAP can be used for authentication, the user must already exist in the database (and have appropriate permissions).
• SCRAM-SHA-256 Authentication: The SCRAM-SHA-256 method (scram-sh-256) performs SCRAM-SHA-256 authentication, as described in RFC 7677. This challenge-response scheme prevents password sniffing on untrusted connections and supports storing passwords on YugabyteDB clusters in the most secure cryptographically hashed form available. This is the most secure password authentication available and is supported by most of the client drivers for the YSQL API.
• Host-Based Authentication: YugabyteDB fine-grained authentication for YSQL manages access control for localhost, remote hosts, and clients. Using fine-grained authentication, you can define rules for access to localhost and remote clients based on IP addresses, authentication methods, and use of TLS (aka SSL) certificates.
• Trust Authentication: When trust authentication is specified, YugabyteDB assumes that any user trying to connect with the YB-TServer can access the database with the database user name they specify. Warning: trust authentication is only suitable if you trust every user on every machine allowed to connect to the server by the ysql_hba.conf lines that specify trust. It is seldom reasonable to use trust for any TCP/IP connections other than those from localhost (127.0.0.1).

Role-Based Access Control (RBAC)

Role-based access control is a way to restrict users’ access based on their roles within the organization. The RBAC model in YugabyteDB is a collection of permissions (in YCQL) or privileges (in YSQL) on resources given to roles. In YSQL, we added new documentation on two additional ways to restrict user access.

• Row-Level Security (RLS): In addition to database access permissions available through ROLE and GRANT privilege system, YugabyteDB provides a more granular level security where tables can have row security policies that restrict rows users can access.
• Column-Level Security: Column level security in YugabyteDB is used to restrict the users to view a particular column or set of columns in a table.

Column-Level Encryption

YugabyteDB provides column level encryption in YSQL to restrict access to sensitive data like addresses and credit card details. Because the YSQL API is built by reusing the PostgreSQL code (version 11.2) directly, this enables YugabyteDB to use the PostgresQL pgcrypto extension to enable column level encryption, as well as the PGP_SYM_ENCRYPT and PGP_SYM_DECRYPT functions of the pgcrypto extension to encrypt and decrypt column data. Learn more about column-level encryption in YSQL here in the docs.

Audit Logging

The goal of logging is to provide YugabyteDB users with the capability to produce audit logs, which are often required to comply with government, financial, or ISO certifications. Audit logging in YugabyteDB will write the output on each node to the standard logging facility, similar to the design of PostgreSQL. These partial log files can subsequently be merged for a global audit trail. Audit logging is supported for both the YSQL and YCQL APIs, and more details can be found in the audit logging section of the docs.

And because YugabyteDB YSQL uses the PostgreSQL Audit Extension (pgAudit), it can provide detailed session and/or object audit logging via YugabyteDB’s TServer logging. We added documentation on session-level logging for YSQL here in the docs, as well as object-level logging for YSQL.

JSON Support

We introduced a new JSON Support section to help you easily explore the JSON functionality in YugabyteDB (YSQL and YCQL), including how to query and update JSON documents, and more.

Transactions

YugabyteDB is a transactional database that supports distributed transactions. A transaction is a sequence of operations performed as a single logical unit of work and has four key properties—Atomicity, Consistency, Isolation, and Durability—commonly abbreviated as ACID. We introduced new documentation to explain how distributed transactions work in YugabyteDB (YSQL and YCQL), and explain how the two isolation levels supported in YSQL—serializable and snapshot—work.

The WITH Clause (Common Table Expression or CTE)

The WITH clause (sometimes known as the common table expression) can be used as part of a SELECT statement, an INSERT statement, an UPDATE statement, or a DELETE statement. You can explore the CTE functionality within Yugabyte YSQL here in the docs.

Yugabyte Platform

We have also built out a comprehensive collection of documentation for Yugabyte Platform, a browser-based UI that allows you to build your own YugabyteDB-as-a-Service on any cloud or Kubernetes infrastructure. Yugabyte Platform is best fit for mission-critical deployments, such as production or pre-production testing. The console within Yugabyte Platform is used in a highly available mode and orchestrates and manages YugabyteDB universes, or clusters, on one or more regions (across public cloud and private on-premises data centers).

Recently added to the documentation are articles on how to install, configure, deploy, back up, restore, secure, and troubleshoot Yugabyte Platform. You can navigate to all the Platform-related docs starting from the Yugabyte Platform documentation page.

What’s Next?

To help you learn and use YugabyteDB effectively and to get you the answers you need, we constantly update and add new topics to the YugabyteDB documentation. Here are a few ways you can contribute:

• File GitHub issues for the docs. If you discover missing information, incorrect information, unclear explanations, or have new topics you’d like to see, click New issue and add the “area/documentation” label.
• Contribute to the YugabyteDB docs. Share your knowledge and lessons learned with the Yugabyte by contributing to the YugabyteDB Docs. You will get recognition and rewards for your efforts as part of our recently launched Community Heroes program.
• Ask questions and share answers in our Slack community. Your questions in the yugabyte-db Slack community are seen by fellow members and contributors who are there to help you move forward. Additionally, we routinely create new documentation pages based on topics that are of interest to Slack community users.