cockroachdb / docs

CockroachDB user documentation

CockroachDB Docs

This repository contains the source files for the CockroachDB documentation available at cockroachlabs.com/docs.

Suggest Improvements

Want a topic added to the docs? Need additional details or clarification? See an error or other problem? Please open an issue.

Write Docs

Want to contribute to the docs? See CONTRIBUTING for details about setting yourself up and getting started.

Resources

• Code of conduct
• Contributing

docs's Issues

build jekyll theme/styling

• Choose theme
• Customize layout and styling to fit seamlessly with cockroachlabs.com

make it clear which grammar nodes are links

In the grammar diagram it’s not too obvious for me which nodes are links to expansions. Maybe render them blue and underlined?

cloud deployment

Instructions for deploying a multi-node cluster in the cloud (at least AWS).

add google analytics

prevent line-wrapping in code blocks

Currently, when a line of code is longer than than the screen allows, the line wraps. This makes certain samples harder to read.

Adjust the css to prevent line-wrapping; offer a horizontal scrollbar instead.

Add recommendations about file systems

So our product promises to behave nicely assuming the user is storing their files in a properly-behaved filesystem / persistent storage.

However as discussed in this paper: https://www.usenix.org/system/files/conference/osdi14/osdi14-paper-pillai.pdf

operating systems have bugs in how they implement file systems, and sometimes the OS promises that data written by an application is actually written to disk while there is a bug which causes this data to not be saved. Or the OS promises something about the order in which I/O operations issued by the DB are performed on disk, and instead actually does things in a different order. This is Real Bad.

Our docs need to explain what we assume from the underlying storage and make recommendations about which file systems are known to work sufficiently well.

Docs versioning

Figure out how to provide docs for multiple versions of CockroachDB

Add automatic sitemap generation

We need to add a sitemap to make sure Google and other search engines know about the organization of our site.

It might be best to start by having GitHub automatically generate our sitemap: https://help.github.com/articles/sitemaps-for-github-pages/.

Here are the docs for the plugin itself: http://www.rubydoc.info/gems/jekyll-sitemap/0.10.0

data types

Should be part of the SQL Reference section.

Changes to --stores flag

See cockroachdb/cockroach#4577

update install page with link to binaries

For OS X and Linux, Download the Binary needs a valid link.

@bdarnell, @mberhault: When do you think OS X and Linux binaries will be ready, and where will we host them for user download?

HTTPS

We need to get HTTPS working with the entire website. Currently it is returning a bad cert error. One solution would be to put cloudflare in front of the whole thing (my recommendation).

CockroachDB features

Rework features pages to support new website messaging/benefits.

@jess-edwards, @dianasaur323

make roach icons on docs landing page responsive

On mobile and tablet, the critters should stack vertically.

http://www.cockroachlabs.com/docs/

cc: @knz

redirect docs. to /docs

It's pretty common for docs to be at docs.company.com, so we should make sure that when users go to docs.cockroachlabs.com, they get redirected to cockroachlabs.com/docs.

@mberhault, can you help with this at some point?

sql: descriptions of built-in functions

To be part of the SQL Reference section.

• CockroachDB SQL built-in functions: https://github.com/cockroachdb/cockroach/blob/master/sql/parser/builtins.go

Related docs:

• https://drive.google.com/a/cockroachlabs.com/folderview?id=0B5l6NSPOAeQAejliTk0zeEVXUG8&usp=drive_web
• http://www.postgresql.org/docs/9.5/static/functions.html

identifiers

To be part of the SQL reference section. Explain rules for identifiers and keywords.

cockroachdb compared to other dbs

Matrix comparing CockroachDB against other databases. Need to identify the most important points of comparison. Likely to included:

• Horizontal scaling
• Distributed transactions
• ACID semantics
• Strong consistency
• SQL

@spencerkimball, @petermattis, @bdarnell: Can you help me identify other points of comparison as well as the dbs that we want to compare against?

Make all internal links relative

Making the links relative will make it easier to set up a staging environment as well as (automatically) testing before pushing upstream. Any thoughts?

add license

Add creative commons license.

Note from @bdarnell:

• Attribution (CC BY): the most permissive license, and the closest to the apache software license
• Attribution-ShareAlike (CC BY-SA): GPL-like, prevents closed derivatives of the docs
• Attribution-NonCommercial (CC BY-NC): prevents others from e.g. publishing our docs in book form
• Attribution-NoDerivs (CC BY-ND): prevents anything but a verbatim copy of the docs
• Various combinations of ShareAlike, NonCommercial, NoDerivs

For comparison, mongodb's docs are under ShareAlike-NonCommercial; I checked cassandra/datastax and hbase but it was not immediately obvious what license their docs used. Tornado uses Attribution-only.

Note from @petermattis: The CC BY license sounds good to me. If Apache-style restrictions (or lack thereof) are good enough for our code they should be good enough for our docs.

add index usage to Basic SQL Statements

http://www.cockroachlabs.com/docs/basic-sql-statements.html

Generic monitoring options

For users who don't use Prometheus, our 2.0 monitoring docs should probably cover:

• The /health HTTP endpoint for node health.
• The <hostname>:8080/_status/vars HTTP endpoint used by Prometheus. The format is easy-to-parse format, so users could massage the data to work with different monitoring system.
• The raw JSON endpoints listed at <hostname>:8080/#/debug/, thought those pages are under construction and not exposed by default. To access them, you must first run SET CLUSTER SETTING server.remote_debugging.mode = 'any';.

@dianasaur323, any thoughts or comments?

style callouts (tips, notes, warnings)

Work with DivisonOf to establish brand-specific styling for callouts in docs (tips, notes, warnings).

start a local cluster

Instructions for starting a local cluster in various ways:

• single node in dev mode (insecure)
• single node secure
• multi-node secure

Link away for starting up multi-node cluster across machines.

Horizontal scrolling in tables

Need to provide horizontal scroll when screen in narrower than a table,

customize page-level toc

Our Jekyll theme has a built-in function to add a toc to the top of a page; you just add toc:true to the front-matter. Currently, it adds the toc to the very top of the page, above all other content. We should think about:

• customizing the feature so we can control where it gets added (i.e., after an intro).
• customize the styling so it floats to the right of other content, similar to https://www.rethinkdb.com/docs/introduction-to-reql/

cc: @jess-edwards

install client drivers

Call out recommended postgres drivers (those we've tested) for:

• python
• ruby
• go
• c
• javascript (node.js)
• java
• php
• closure

Also mention that any postgres driver should work and suggest getting in touch if any problems.

frequently asked questions

Concise answers to questions we think prospects might be most immediately interested in, such as how does cockroach scale, how does it survive failures, why is is sql, etc.

cleanup bnf simplify/reduce

Currently the BNF generator has a few steps:

1. Parse the sql.y yacc file
2. Print a EBNF from it
3. Parse the EBNF
4. Simplify the EBNF
5. Generate the RR diagrams with simplified EBNF

This is because before we had to use an external program for step 1. Now that we have our own parser, there's no need to convert to EBNF and back. Instead we can simplify the yacc AST in memory and only output an EBNF once.

contributing to cockroachdb

Docs on how to contribute to cockroachdb docs and development.

add search

There needs to be a way to search across all topics in the docs.

Always planned to get it in there, but just occurred to me that this is pretty important for beta, @spencerkimball and @jess-edwards. Will look into options.

cockroach cli reference

Document all options.

Update docs for starting cockroach - insecure and secure

Need to update Start a Local Cluster. See:

#4269 - see below
#4335 - default --stores value for cockroach start
#4352 - remove --dev mode for cockroach start

• If cockroach start is specified then the server only listens on localhost and the server starts in insecure mode. This allows a developer running a local instance to start cockroach with no additional arguments.
• If cockroach start --insecure is specified the server listens on all addresses and starts in insecure mode. This forces a production cockroach cluster composed of multiple nodes to explicitly specify --insecure.
• If cockroach start --cert-file is specified the server listens on all addresses and starts in secure mode.

Try-Us-Out instructions should not use Docker, but binaries

You can't access http:\\<docker ip>:26527 because docker ports/networking something something. I think we need more to the docker invocation than what's documented here. I think @tschottdorf would know.

Also we need to figure out the relationship between the installation instructions we have in the README.md and the docs site.

sql: type conversion

Should be part of the SQL Reference section.

Mobile topnav menu flashes when scrolling on safari

When you scroll down a large page in Safari, the mobile topnav menu flashes along the right margin of the page. @dt mentioned that Safari, unlike Chrome, loads the content as you scroll. We could solve this by limiting that version of the topnav to mobile devices, not just by screen width.

Sample page: https://www.cockroachlabs.com/docs/sql-grammar.html

deploy: recommended ulimit/sysctl settings

Many deployments will need to increase the file descriptor limit, and possibly other ulimit settings. This is true of large deployments on linux and even small ones on OSX. We should have a document explaining this along with other recommended system-level settings.

For comparison, https://docs.datastax.com/en/cassandra/2.0/cassandra/install/installRecommendSettings.html

Improve presentation of search results

Our current docs search opens a Google results page. We should find a way to keep the results within the frame of our docs site, and style the results to be in line with the rest of the site.

Aerospike's search results can serve as an example: http://www.aerospike.com/docs/

cc: @jess-edwards, @bdarnell

complete readme.md

Explain how our docs work (Jekyll, style guide, etc.).

automated testing of html output

We should put in place an automated test on Jekyll output. Ideally, the test would run immediately following jekyll serve or jekyll build. At a minimum, the test should catch broken links and broken images.

This might do the trick: https://github.com/gjtorikian/html-proofer

Add a list of "Videos & talks" to "Learn How It Works"

In the cockroach README there's a talks list. What do you think about adding these as a subsection in the docs?

update to kramdown and rouge

Github Pages will soon support only the kramdown dialect of markdown and rouge as syntax highlighter. We need to make some updates to the configuration file and code block formatting.

https://github.com/blog/2100-github-pages-now-faster-and-simpler-with-jekyll-3-0

cc: @mjibson

install cockroachdb

• Install instructions for Mac, Linux, and Windows.
• Tab-type thing on page to show instructions only for relevant OS.

sql statements

Full reference docs for sql statements. To be part of the SQL Reference section.

Draft page here: http://www.cockroachlabs.com/docs/sql-statements.html

update cluster startup instructions

Cockroach PR 4027 removes --init and changes --gossip to --join. Need to update Start a Local Cluster.

@spencerkimball

certificate and cert command usage

We should at the very least have the following:

• overview of cockroach security settings (insecure vs full certs: both client and server)
• for each cockroach cert command:
  • description of behavior
  • required files (eg: create-node and create-client need ca.crt and ca.key)
  • created files
  • equivalent openssl command and which fields are required for it to work

@mberhault will do a writeup and coordinate with @jseldess for integration into the docs.

build a test app

Show how to connect and perform basic sql commands from various language (python, ruby, c, javascript, go).

basic sql commands

Document most important sql commands for getting up and running with CockroachDB.

horizontal scrolling in code blocks

Right now, lines are wrapping. Instead, we should probably change the css so lines continue with a horizontal scrollbar.

cc: @knz

CockroachDB architecture

Breakdown of architecture - concise, clear, and with diagrams. Based on CockroachDB design doc.