LICENSE Documentation

1. Project Overview & Quickstart (cockroachdb/LICENSE) Copy Chapter

LICENSE

Open-source repository cockroachdb/LICENSE

Repository Details Copy Section

• Repository: cockroachdb/LICENSE
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (cockroachdb/docs) Copy Chapter

File: README.md Copy Chapter

CockroachDB Docs

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

Suggest Improvements Copy Chapter

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

Resources Copy Chapter

• Code of conduct

File: CODE_OF_CONDUCT.md Copy Chapter

CockroachDB Docs

Code of Conduct Copy Chapter

We value the participation of everyone in the CockroachDB community and want to create an environment that is welcoming, enjoyable, and fulfilling.
When posting or participating in a community event or online forum, please use the following guidelines:

• Be specific and detailed. Include relevant details in your inquiries (eg. versions, error messages, deployment environment, etc.), and
  avoid asking off-topic questions in existing discussion threads.

• Share experiences and knowledge publicly. Everyone can benefit from the exchange of knowledge, so we encourage all community members to
  share their experience in public channels (at events, on the forum, GitHub, StackOverflow, Slack, etc.).

• Collaborate and help each other. If someone lacks knowledge in a particular area, help to educate and collaborate with them.

• Have patience. Many community members are volunteers, and it may take some time to get a response to your question.

• Be kind and respectful. Communication should be positive and constructive. Every design or implementation choice carries a trade-off and numerous costs, and there is seldom a right answer.

• Be good to each other. We will exclude you from interaction if you insult, demean, or harass anyone.
  Likewise any spamming, trolling, or baiting is not welcome.

• Finally, if you notice or are experiencing violations of this code of conduct or harassment of any kind, please reach out to @jseldess on GitHub or email [email protected] to help resolve the situation.

  Thank you for helping make this a helpful and a welcoming community.

  Adapted from the MongoDB Code of Conduct and the Rust Code of Conduct.

File: final-real-test.md Copy Chapter

Final real test with workflow on main

File: final-test-fixed.md Copy Chapter

Final test - workflow should work now

File: LOCAL_DEVELOPMENT.md Copy Chapter

Local Development

Prerequisites: Rancher Desktop (Docker Desktop is not supported)

cd src/current
make docker-pull
make docker-serve

File: MarkdownGuide.md Copy Chapter

Markdown Guide

This guide covers Markdown-specific syntax and formatting conventions used in CockroachDB documentation. For general style guidelines, refer to the Style Guide.

Table of Contents Copy Chapter

• Site structure
  • Docs repository
  • Page headings
  • Sidebar
• Title
• Headings
• Text formatting
  • Bold
  • Italics
• Links
  • Between pages
  • From non-versioned directories
  • From Technical Advisories
  • Custom anchor links
  • External links
• Code
  • Inline code
  • Code block
  • Language highlighting
  • Copy to clipboard
  • Placeholders
  • Escaping special characters
• Lists
  • Ordered lists
  • Unordered lists
  • Nesting lists
  • Nesting paragraphs and code blocks
• Tables
  • Markdown tables
  • HTML tables
  • Markdown vs. HTML
• Images
• Videos
• Versioning
  • Version tags
  • Version references
• Include files
  • Basic include file usage
  • Advanced include file usage
  • Filter tabs
  • Technical limitations of include files
• Tabs
  • Linking into tabbed content
• Comments
  • TODOs

Site structure Copy Chapter

Docs repository Copy Section

Documentation for each CockroachDB version is organized in dedicated directories. For example, CockroachDB v23.1 docs are in src/current/v23.1 and src/current/_includes/v23.1, while CockroachDB API docs are in src/api.

Each page must be a .md file written in Redcarpet Markdown. Use lowercase file names with dashes between words.

Example: name-of-your-file.md

Page headings Copy Section

All Markdown pages require YAML front matter:

---
title: Title of Page
summary: Short description of page for SEO
---

Required fields:

Optional fields:

Sidebar Copy Section

Each CockroachDB version uses a JSON file to define sidebar navigation. The file is located at _includes/vXX.Y/sidebar-data/{section}.json.

JSON structure:

Example structure:

[
  {
    "title": "Get Started",
    "items": [
      {
        "title": "Install CockroachDB",
        "urls": ["/${VERSION}/install-cockroachdb.html"]
      },
      {
        "title": "Start a Local Cluster",
        "items": [
          {
            "title": "From Binary",
            "urls": ["/${VERSION}/start-a-local-cluster.html"]
          }
        ]
      }
    ]
  }
]

Title Copy Chapter

Set the page title in the title: metadata. The title should be in title case. Heading 1 (#) is reserved for page titles and should not be used in pages.

Headings Copy Chapter

A heading is denoted by one or more number signs (#) followed by one space: Heading 2 (##), Heading 3 (###) and Heading 4 (####). Denote anything under Heading 4 by bolded text.

Use headings to establish a content hierarchy. When the page is rendered, the first two heading levels appear in the page TOC at the right of the page.

Add a line break between a heading and its content.

Examples:

• ## Heading 2
• ### Heading 3
• ## Step 2. A step in a tutorial

Text formatting Copy Chapter

Bold Copy Section

Use bold text to emphasize a UI element, important word or phrase, or to create visual separation and callouts. Do not combine bold with italic.

Examples:

• The Overview dashboard is displayed. Hover over the SQL Queries graph at the top.
• Default: NULL

Italics Copy Section

Use italics to introduce a new term or concept. To emphasize a word or phrase, use bold formatting instead.

Examples:

• This is the basis of potential write skew anomalies.
• Every table in a multi-region database has a "table locality setting" that configures one or more home regions at the table or row level.

Links Copy Chapter

Links between CockroachDB docs pages Copy Section

To link to pages in the docs repo, use the Jekyll link syntax.

If the page is versioned, use {{ page.version.version }} rather than the hardcoded version. Exceptions apply when linking to versioned pages from non-versioned pages and technical advisory pages.

Examples:

• [Foreign Key Constraint]({% link {{ page.version.version }}/foreign-key.md %})
• [Foreign Key Constraint]({% link cockroachcloud/quickstart.md %})

To include an anchor link, place it outside of the Liquid tag.

Examples:

• [Rules for creating foreign keys]({% link {{ page.version.version }}/foreign-key.md %}#rules-for-creating-foreign-keys)
• [Multi-active availability]({% link {{ page.version.version }}/architecture/glossary.md %}#multi-active-availability)

Links to versioned docs pages from a non-versioned directory Copy Section

When linking to a versioned page from a non-versioned page (such as cockroachcloud or molt), use {{ site.current_cloud_version }} in place of {{ page.version.version }}. This is because the page.version.version variable can't be accessed from the non-versioned directories.

Example: [FLOAT]({% link {{ site.current_cloud_version }}/float.md %})

Links to CockroachDB docs from technical advisories Copy Section

When linking to a versioned page from a Technical Advisory (in advisories), hardcode the page version.

Example: [debug.zip]({% link v25.1/cockroach-debug-zip.md %})

Custom anchor links Copy Section

To link to a specific location on a page that is not a heading (for example, a specific command-line flag in a table), add a manual anchor and use the id parameter:

Example:

# Anchor:
<a id="flags-max-offset"></a>`--max-offset`

# Link:
[--max-offset](#flags-max-offset)

External links Copy Section

To link to an external page, use the standard Markdown syntax.

Example: Refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/index.html).

For websites that automatically localize pages, avoid using localization elements, such as en, directly within the URL.

Examples:

• Instead of https://docs.github.com/en/graphql/overview/explorer, use https://docs.github.com/graphql/overview/explorer.
• Instead of https://en.wikipedia.org/wiki/SQL:2011, use https://www.wikipedia.org/wiki/SQL:2011 or https://wikipedia.org/wiki/SQL:2011.

Code Copy Chapter

Inline code Copy Section

Use inline code when referring to code, commands, values, or other technical syntax within a sentence. Inline code is surrounded by backticks (``).

Example: The CREATE TABLE statement creates a new table in a database.

Code block Copy Section

Use a code block to provide executable code samples. A code block has an opening and closing set of 3 tildes (~~~). There should be one returned line before and after a code block, for better Markdown readability.

This is a sample line of text.

{% include_cached copy-clipboard.html %}
~~~ shell
go get -u github.com/lib/pq
~~~

This is more sample text.

Language highlighting Copy Section

A code block supports syntax highlighting if you add the language name (shell, sql, json, etc.) immediately after the first line of tildes.

~~~sql
SELECT * FROM users;
~~~

~~~shell
cockroach start --insecure
~~~

Multi-line samples Copy Section

For multi-line commands, use a backslash (\) at the end of each line to indicate a line continuation. The backslashes make the command easier to read, but the shell sees it as one line.

~~~shell
cockroach start \
  --insecure \
  --store=node1 \
  --listen-addr=localhost:26257
~~~

Copy to clipboard Copy Section

Many of our code blocks are written so users can copy and paste them directly into a terminal. To make that easier, add the Copy to Clipboard button by placing {% include_cached copy-clipboard.html %} on the line directly preceding the code block:

{% include_cached copy-clipboard.html %}
~~~shell
go get -u github.com/lib/pq
~~~

Notes for usage:

• Copy to Clipboard should be used for every code block that can be executed.
• To render properly, there must be a line break above the {% include_cached copy-clipboard.html %} line.

Escaping special characters Copy Section

Sometimes you may need to escape special characters to achieve proper rendering:

• Jekyll-reserved characters (for example, double {{ ... }}) in code blocks: Wrap the specific line(s) with Liquid tags {% raw %} ... {% endraw %}.

  markdown Copy

  {% raw %}summary: Instance {{ $labels.instance }} has {{ $value }} tripped per-Replica circuit breakers{% endraw %}

• Special characters in front matter: Convert special characters to Unicode. For example, to escape SET {session variable} in the front matter:

  yaml Copy

  title: SET {session variable }

Lists Copy Chapter

CockroachDB docs use two types of lists:

• Numbered (ordered list): Use to list information that should appear in order, like tutorial steps.
• Bulleted (unordered list): Use to list related information in an easy-to-read way.

Introduce a list with a sentence and a colon. Use periods at the end of list items if they are sentences or complete a sentence.

Ordered lists Copy Section

For each item of a numbered list, use 1. followed by a period and a space, for example, 1. This is a numbered list item. The HTML renderer will render the steps in the correct order.

1. This is the first step.
1. This is the second step.
1. This is the third step.

Unordered lists Copy Section

For each item of a bulleted list, use one dash followed by one space, for example, - This is a bulleted list item.

- This is a bullet point.
- This is another bullet point.
- This is a third bullet point.

Nesting lists Copy Section

To nest a list under a list item, start the list on the next line (no empty line), and indent the new list four spaces:

1. This is a step.
    - This is a bullet.
    - This is a bullet.
    - This is a bullet.

1. This is a step.

    This is a nested paragraph.
    - This is a bullet.
    - This is a bullet.

Nested ordered lists work similarly:

1. This is a step.
    1. This is a substep.
    1. This is a substep.
    1. This is a substep.

1. This is a step.

    This is a nested paragraph.
    1. This is a substep.
    1. This is a substep.

Nesting paragraphs and code blocks Copy Section

To nest a paragraph or code block under a list item, insert an empty line and then indent the paragraph or code block 4 spaces:

1. This is a step.

    This is a nested paragraph.

    ~~~shell
    command
    ~~~

Similarly, to nest a paragraph or code block under a nested list item, insert an empty line and then indent the paragraph or code block 8 spaces:

1. This is a step.
    - This is a bullet.

        ~~~shell
        command
        ~~~
    - This is a bullet.

        ~~~shell
        command
        ~~~

Tables Copy Chapter

Use tables to display structured information in an easy-to-read format. We use two types of tables: Markdown and HTML.

Markdown tables Copy Section

If you can keep the table formatting simple (for example, basic text formatting and using <br> tags for paragraph breaks), create a table using Markdown. This is the preferred table format.

To create a table, use pipes (|) between columns and at least 3 dashes (-) separating the header cells from the body cells. A return denotes the start of the next row. The text within each column does not need to align in order to be rendered correctly, and you can inline Markdown or HTML.

Do not use outer pipes.

Example:

Term   |         Description         |     Example
----------|-----------------------------|----------------
 `term_1` | This is a description.      | `3.14`
 `term_2` | This is also a description. | `"lola mcdog"`

You can use the following Markdown formatting within a Markdown table:

• Bold
• Italics
• Inline code
• Links

The following formatting needs to be in HTML to be used within a Markdown table:

• Paragraph breaks (<br>)
• Lists (ol / ul / <li>)

If the formatting becomes too complex, create an HTML table.

The following formatting is not supported within a Markdown table:

• Liquid tags
• Code blocks

HTML tables Copy Section

If it's necessary to include more complex table formatting or if a Markdown table becomes too unwieldy, create a table using HTML. This formatting is not recommended unless necessary, since it is hard for other writers to parse and maintain.

You can use the following HTML formatting within an HTML table:

• Bold (<strong>)
• Italics (<em>)
• Inline code (<code>)
• Links (<a href)
• Paragraph breaks (<p>)
• Lists (<ol> / <ul> / <li>)

Markdown vs. HTML Copy Section

• Prefer Markdown syntax over HTML when possible for better readability and maintainability.
• Use HTML only when Markdown doesn't provide the necessary functionality.
• When mixing Markdown and HTML, ensure proper spacing and formatting. Preview the rendered page locally.

Callouts Copy Chapter

CockroachDB docs use three classes of "callouts," which are highlighted blocks of text: tips, notes, and warnings.

• To insert a tip, use the following code:

  text Copy

  {{site.data.alerts.callout_success}}
  tip text goes here
  {{site.data.alerts.end}}

• To insert a note, use the following code:

  text Copy

  {{site.data.alerts.callout_info}}
  note text goes here
  {{site.data.alerts.end}}

• To insert a warning, use the following code:

  text Copy

  {{site.data.alerts.callout_danger}}
  warning text goes here
  {{site.data.alerts.end}}

Images Copy Chapter

Use the following HTML and Liquid to include an image in a Markdown page:

Videos Copy Chapter

Use the following Liquid to include an embedded video in a Markdown page:

{% include_cached youtube.html video_id="<YouTube ID>" [widescreen=true] %}

The video_id parameter is required and is whatever is after the ?v= portion of the URL. If the URL to the video you wish to embed is https://www.youtube.com/watch?v=5kiMg7GXAsY, for example, then the value of video_id should be 5kiMg7GXAsY. The widescreen parameter is optional and meant for videos with wide banners such as our video on Foreign Key Constraints.

You can optionally pass in a start time to the video_id parameter to make the video start at a specific timestamp. The below example embeds the How to Create Tables with Foreign Keys in SQL video and starts playing it at 25 seconds:

{% include_cached youtube.html video_id="mFQk1VsIkZA?start=25" %}

Versioning Copy Chapter

Use version tags to highlight new features and version references to link to specific CockroachDB versions in documentation.

Version tags Copy Section

Version tags inform users of new and updated features in CockroachDB, and could motivate users to upgrade to the latest major or patch version of CockroachDB. Version tags also help us identify new and updated features that we can call out in our GA release notes.

To add a version tag, use the following Liquid tag:

{% include_cached new-in.html version="v22.1" %}

Note: If using a version tag inside of a Markdown table, use <span class="version-tag">New in vXX.Y:</span> or <span class="version-tag">New in vXX.Y.Z:</span> instead.

Put version tags at the beginning of a paragraph, sentence, or description in a table cell.

If a feature is new in a GA release, use the major release number for the release version tag (e.g., {% include_cached new-in.html version="v21.2" %}).

If a feature has been backported to a previous version in a patch release, use the patch release number for the release version tag (for example, {% include_cached new-in.html version="v21.2.10" %}).

Version tags should only refer to the version of the docset that contains them. For example, the version tag {% include_cached new-in.html version="v21.1.9" %} should only be on pages in v21.1 directories.

Version references Copy Section

To refer to a static version of CockroachDB:

{{site.versions["v22.2"]}}

To dynamically refer to the stable version of CockroachDB, as determined each time the site is built:

{{site.versions["stable"]}}

Warning: If you use a stable link on a versioned page which is for a previous version, the link points to a different version of CockroachDB than the version the page documents. Similarly, if you use a stable link on a page for the current version and then a new version is added, the link points to a different version than the version the page documents. If this is a problem, use one of the following methods instead.

Pages that document CockroachDB itself exist within subdirectories that represent major versions. To refer to a page's major version (for example, v22.2), which matches its top-level subdirectory within the docs repo:

{{page.version.version}}

A patch release version of CockroachDB receives updates as patches. To refer to a page's current patch version (for example, v22.1.7):

{{ page.release_info.name }}

Include files Copy Chapter

There are basic and advanced methods for using include files. Use the basic method unless you are sure you need the advanced.

Basic include file usage Copy Section

The basic method for using an include file is:

1. Find (or create) a block of content that you want to make appear on two or more different pages.
2. Create a new file in the subdirectory of the _includes directory associated with the product you are working on. For example, if you are working on CockroachDB Self-Hosted v22.1, the directory will be _includes/v22.1/. If you are working on CockroachDB Dedicated, it will be _includes/cockroachcloud. If the include text is not version- or product-specific, put it in the common directory.
3. In the pages where you want the included content to appear, add an include tag like one of the following: for CockroachDB Self-Hosted, {% include {{page.version.version}}/some/shared-file.md %}; for CockroachDB Dedicated, {% include cockroachcloud/some/shared-file.md %}.

The contents of shared-file.md will now appear on all of the pages where you added the include tag.

Advanced include file usage Copy Section

Different content depending on page name

There may be cases where the content of the include file will need to vary slightly depending on what pages that content is being shared into. For example, while working on cockroachlabs/docs#12216, I needed a way to:

• Have text be a link on the Known Limitations page.
• Have that same text not be a link on the Cost-Based Optimizer page (since it would be a self-referring link).

The way to do this in Jekyll (with its templating language Liquid) is to add the following content to an include file that is shared into both pages:

{% if page.name == "cost-based-optimizer.md" %} Locality-optimized search {% else %} [Locality-optimized search](cost-based-optimizer.html#locality-optimized-search-in-multi-region-clusters) {% endif %} only works for queries selecting a limited number of records (up to 10,000 unique keys). Also, it does not yet work with [`LIMIT`](limit-offset.html) clauses.

The syntax is a little hard to read inline, but based on some experimenting it appears that it must be written as one line so as not to introduce line breaks in the resulting text.

Formatted for easier reading, the template code looks like:

{% if page.name == "cost-based-optimizer.md" %}
Locality-optimized search
{% else %}
[Locality-optimized search](cost-based-optimizer.html#locality-optimized-search-in-multi-region-clusters)
{% endif %}

Remote includes

Sometimes, you need to include files that are maintained in other places than the cockroachlabs/docs repo but referenced in our docs. The remote_include tag is used for this. We most often use this tag for code samples, which are maintained in various repos.

For code samples, you usually want to show only part of a larger file to highlight a specific technique, or due to length considerations.

To accomplish this, the remote_include tag lets you pass arguments (usually named START {text} and END {text} by convention) that pull in the text of the remote file between START {text} and END {text}.

For example, the file movr-flask-application.md (which becomes the page Develop a Global Web Application) has the following remote_include:

{% remote_include https://raw.githubusercontent.com/cockroachlabs/movr-flask/v2-doc-includes/dbinit.sql ||-- START database ||-- END database %}

If you browse to the dbinit.sql file, you will find the following SQL code block that uses those start and end tags:

-- START database
CREATE DATABASE movr PRIMARY REGION "gcp-us-east1" REGIONS "gcp-us-east1", "gcp-europe-west1", "gcp-us-west1";
-- END database

For more information about the remote_include tag, see the README in the jekyll-remote-include repo.

Filter tabs Copy Section

Use filter tabs to create navigation between related pages. The filter-tabs.md include generates tabs that link to different pages.

Note: Filter tabs link to different URLs/pages, not tabs within a single page.

Setup process:

1. Identify pages for filter tabs and note their HTML filenames (for example, install-cockroachdb-mac.html).

2. Create an include file in _includes/<version>/filter-tabs/ with this structure:

   liquid Copy

   {% assign tab_names_html = "Tab 1;Tab 2;Tab 3" %}
   {% assign html_page_filenames = "page1.html;page2.html;page3.html" %}
   {% include filter-tabs.md tab_names=tab_names_html page_filenames=html_page_filenames page_folder=<version> %}

3. Include the filter tabs on each target page: {% include <version>/filter-tabs/<name>.html %}

Technical limitations of include files Copy Section

Include files have the following technical limitations:

• Cannot be used in Markdown tables
• Remote includes cannot reference local includes
• Include files with paragraphs followed by code blocks may not render correctly in all contexts

Tabs Copy Chapter

To allow your reader to select from two or more versions of on-page content, use a tabset. This might be appropriate for:

• Install procedurals with different steps for the different supported platforms (like macOS, Windows, Linux).
• Reference material where the Enterprise and non-Enterprise versions of a feature differ.
• Demonstrating how to connect from an example application in each supported programming language (like Python, C++, Java, etc.).

To add tabs to your copy, you first define the tabset for use later on the page, then you declare each tab's content within each tab.

To define the tabset:

<div class="filters clearfix">
  <button class="filter-button" data-scope="macos-install-steps">macOS</button>
  <button class="filter-button" data-scope="windows-install-steps">Windows</button>
</div>

This example defines two tabs (named macOS and Windows) and defines a unique data-scope for each (macos-install-steps and windows-install-steps respectively).

Then, to declare the content within each tab:

<section class="filter-content" markdown="1" data-scope="macos-install-steps">

1. To install CockroachDB on macOS, first you need to ...
...
</section>

<section class="filter-content" markdown="1" data-scope="windows-install-steps">

1. To install CockroachDB on Windows, first you need to ...
...
</section>

## This section outside of tabs

Now the user can freely switch between the macOS and Windows tabs as needed.

Tip: Do your tabs share a lot of common content betwen them? Tabs are often a great place to make use of include files!

Linking into tabbed content Copy Section

To link to content that is contained within a tab, add the filter component to your link, specifying the data-scope you provided in your tabset definition. You can do this in the following two ways:

• To link to the top of a target page, with a specific tab selected:

  text Copy

  [Core changefeeds](create-and-configure-changefeeds.html?filters=core)

  This takes us to the top of create-and-configure-changefeeds.html and ensures the tab matching data-scope: core is selected. See Create and Configure Changefeeds to see this in action.

• For linking to a header contained within a tabset:

  text Copy

  [Create with column families](changefeeds-on-tables-with-column-families.html?filters=core#create-a-core-changefeed-on-a-table-with-column-families)

  This takes us directly to the create-a-core-changefeed-on-a-table-with-column-families header, within the data-scope: core tab. See Create a Core changefeed on a table with column families to see this in action.

Considerations:

• If you intend to link to a header present on two or more tabsets on the same page, the header targets must be uniquely named. If you require identical header names, use explicit, unique HTML anchor names for each (in form <a name="uniquename"></a> as shown under Links.
• For the first-defined tab, specifying its filter value in a link is functionally the same as omitting it. For all other tabs, the explicit filter name is required. You can think of this first tab as the "default" tab in this context: if not otherwise specificed, Jekyll will always open with the first tab's contents displayed.

Comments Copy Chapter

There may be situations that require adding an explanation below a piece of content or to temporarily suppress content within a page. In those situations, use Liquid comments.

Page source:

This sentence is visible!
{% comment %}
This sentence is not visible!
{% endcomment %}
This sentence is visible except for a single commented word: {% comment %}CockroachDB{% endcomment %}

Final page HTML:

<p>This sentence is visible!</p>
<p>This sentence is visible except for a single commented word: </p>

Do not use HTML comments (``), because HTML comments are visible in the page's HTML source code in production. Additionally, any HTML comment content must be processed by the Liquid parser, so any Liquid within an HTML comment is still processed and can produce errors, such as a broken include or broken link.

TODOS Copy Section

If you have future work to do in a particular file, simply add TODO or a FIXME inside of a comment. A colon after TODO or FIXME is optional.

Examples:

{% comment %}
TODO clean up the style guide
{% endcomment %}

{% comment %}
FIXME: Update example SQL commands
{% endcomment %}

Many popular code editors feature extensions that can highlight TODOs across the repository. One such extension is Todo Highlight.

File: StyleGuide.md Copy Chapter

Style Guide

The following guidance is provided to benefit CockroachDB docs authors and reviewers by reflecting past style decisions, and to benefit readers by promoting consistency and readability across our content.

Included in this guide:

• Style and tone
  • Perspective and voice
  • Prescriptive writing
  • Speculation and feature support
  • Latinisms
• Word usage guidelines
  • CockroachDB products
  • CockroachDB versions
  • Third-party products
  • AI
• Inclusivity
  • Avoid ableist language
  • Avoid unnecessarily gendered language
  • Write diverse and inclusive examples
  • Avoid unnecessarily violent language
  • Write accessible documentation
  • Write about features and users in inclusive ways
• Capitalization and punctuation
  • Capitalization rules
  • Punctuation rules
• Vale
• File conventions
• Content types
  • Concept
  • Task
  • Reference
  • Guide
• Page components
  • Code
  • Callouts
  • Images
  • Videos
  • Include files
  • Links
    • GitHub links
    • External links
• Page sections
  • Before you begin
  • Known limitations
  • See also

For Markdown-specific syntax and formatting guidelines, refer to the Markdown Guide.

Style and tone Copy Chapter

CockroachDB docs should be helpful, humble, positive, friendly, and free from hyperbolic language.

Perspective and voice Copy Section

For instructions, use the imperative present tense, aka "imperative mood." The second-person subject ("you") is implied and can be omitted.

Examples:

• Run cockroach start.
• Click Next.

In tutorials, where a conversational tone is sometimes helpful, use the second person ("you").

Examples:

• In this tutorial, you'll start with a new cluster, so stop and clean up any existing clusters.
• After you create the database, insert some rows.

In page titles and headings, use the imperative mood to name a task. Do not use the gerund form or a noun phrase.

• Avoid: Managing Users
  Avoid: User Management
  Prefer: Manage Users

Do not use "we" to refer to "CockroachDB" or "Cockroach Labs".

• Avoid: We support changefeeds.
  Prefer: CockroachDB supports changefeeds.

• Avoid: We recommend ...
  Prefer: Cockroach Labs recommends ...

Prescriptive writing Copy Section

Write in a prescriptive style that clearly guides the user. The user should feel confident and supported, without having to infer meaning or make too many decisions on their own.

Use active instead of passive voice.

• Avoid: Each parameter should be set explicitly.
  Prefer: Set each parameter explicitly.

• Avoid: Additional options can be specified.
  Prefer: You can specify additional options.

Use concise, direct language. Cut unnecessary words unless a conversational tone is intentional (for example, in tutorials). If a feature or concept is difficult to describe clearly or concisely, consider using an example or image to complement the text.

• Avoid: Be mindful of the possibility that you might encounter a different result, depending on the specifics of your configuration, so you might want to do some testing first to see what happens.
  Prefer: Run tests to verify that you get the expected result for your configuration.

• Avoid: table_name: This parameter is used to specify the name of the table you want to modify.
  Prefer: table_name: The name of the table to modify.

Provide guidance rather than leave decisions to the user. For example, phrases like "change what you need" or "modify the relevant settings" may raise questions like "What would I need to change?" and "Which settings are relevant?". When user discretion is required, be as explicit as possible to reduce ambiguity and cognitive load.

• Avoid: Increase the threshold as needed.
  Prefer: Increase the threshold until you see a performance improvement.

• Avoid: Define additional settings as desired.
  Prefer: Depending on your configuration, you may need to define additional settings. For example, ...

• Avoid: Edit the profile using your preferred text editor.
  Prefer: Edit the profile in a text editor.

Avoid vague time estimates. Provide a specific timeframe when possible.

• Avoid: You should set the grace period to at least a few minutes.
  Prefer: Set the grace period to at least 5 minutes.

• Avoid: This should take a few moments. When finished, click Next.
  Prefer: When finished, click Next.

Do not use contractions when giving a technical description or instruction.

• Example: You cannot change primary key using ALTER TABLE.
• Example: If you leave versioned binaries on your servers, you do not need to do anything.

Do not use "please" when giving an instruction, except when asking the user to go outside the scope of the task (for example, contacting Cockroach Labs or filing a support issue).

• Example: If you need assistance, please contact support.

• Avoid: Please click on the Next button.
  Prefer: Click Next.

Do not use language that could be read as presumptuous or condescending.

• Avoid: If you aren't willing to do this for some reason, ...
  Prefer: If this is not possible, ...

• Avoid: Monitoring the cluster is simple.
  Prefer: Monitor the cluster with the following tools:

Speculation and feature support Copy Section

Avoid forward-looking language when writing about supported syntax and behavior. Do not suggest that a feature may or may not be added in a future release. Avoid words like "yet" and "currently", and do not reference the internal product roadmap.

• Avoid: CockroachDB does not yet support column-level privileges. This is planned for a future release.
  Prefer: CockroachDB does not support column-level privileges.

Latinisms Copy Section

For readability, avoid Latinisms.

• Avoid: Select a deployment option, e.g., {{ site.data.products.standard }} or {{ site.data.products.advanced }}.
  Prefer: Select a deployment option such as {{ site.data.products.standard }} or {{ site.data.products.advanced }}.

Word usage guidelines Copy Chapter

This section logs decisions about dictionary words to use and avoid. Add specific guidelines we decide as a team to this section. Refer also to Technical terminology for technical terms that may not be in a dictionary.

CockroachDB products Copy Section

• Use the following combinations of CockroachDB and Liquid variables to display product names on docs pages. Liquid variables cannot be used in Markdown front-matter, file names, or non-Markdown files. In those cases, write the product names manually.

  • CockroachDB Cloud : CockroachDB {{ site.data.products.cloud }}
  • CockroachDB Basic : CockroachDB {{ site.data.products.basic }}
  • CockroachDB Standard : CockroachDB {{ site.data.products.standard }}
  • CockroachDB Advanced : CockroachDB {{ site.data.products.advanced }}
  • CockroachDB self-hosted cluster : CockroachDB {{ site.data.products.core }} cluster

• Use the full product name on its first occurrence on a page. You may subsequently shorten product names to "Basic", "Advanced", or "Cloud", unless this would introduce ambiguity (for example, on long pages where product names might be separated by multiple paragraphs).

• Do not shorten "CockroachDB" to "CRDB".

• Use "cockroach" to refer to the CockroachDB binary.

  • Avoid: Cockroach process
    Prefer: cockroach process

CockroachDB versions Copy Section

Refer to CockroachDB versions as vxx.x.x (for example, v21.1.8). Do not use version xx.x.x.

For version ranges, use to between numbers (for example, v22.1.0 to v22.1.4). Do not use a dash. Refer to Punctuation rules.

Refer to "earlier" and "later" versions, rather than "lower" and "higher" versions. For example, CockroachDB v25.3 and earlier.

Third-party products Copy Section

In general, align third-party branding with that brand's usage. Do not use the shortened versions of product names.

"Directory" vs. "folder" Copy Section

• Use "directory" to refer to a filesystem directory, either locally or in a VM. For example, Compress the directory into a .zip archive.
• Use "folder" to refer to a folder within a UI, such as a web UI or an IDE. For example, Create a folder in your CockroachDB Cloud organization.

"Legacy" vs. "deprecated" Copy Section

• Use "legacy" only for our own earlier products, features, or workflows to signal that a newer option is preferred. Avoid using "legacy" as a pejorative; if no preference is intended, say "earlier" or "previous". Do not use "legacy" to refer to competitors' products.
• Prefer "deprecated" when there is an approved plan for end of support and removal. If deprecation is not approved but guidance is needed, you may call the previous option "legacy".

"In" vs. "on" a cluster Copy Section

Use "in a cluster" when referring to elements that form the cluster itself.

Examples:

• Nodes in the cluster
• Ranges in the cluster

Use on a cluster when referring to workloads, services, or databases that run on the cluster's infrastructure.

Examples:

• Databases on the cluster
• Jobs running on the cluster

AI Copy Section

Write "AI" without periods. Not "A.I."

You don't need to precede the usage of the term "AI" with its elaboration (e.g. "Artificial Intelligence (AI).") Any reader will know what AI is.

When describing "AI tools," "AI agents," or "AI assistants" (etc.) in the context of integrating with CockroachDB, precede introductory instances of these terms with the word "your."

• Avoid: The MCP server enables AI tools to access a cluster.
• Prefer: The MCP server enables your AI tools to access a cluster.

This is a request from Cockroach Labs' legal team. The idea is to remind the reader that these tools are not Cockroach Labs', and so any mistaken/detrimental use of these tools is not Cockroach Labs' responsibility. Not every instance of these terms needs to be preceded with the word "your." This is mainly meant for early instances of these terms on the page (i.e. in introductory paragraphs), to establish this idea.

Inclusivity Copy Chapter

Use inclusive language that reflects a diverse readership. Avoid terms that inherently exclude, stereotype, or cause confusion.

Avoid ableist language Copy Section

An informal tone can allow for problematic ableist language due to figures of speech and colloquial language. Ableist language includes words like "crazy", "insane", "blind", "dummy", "cripple", and more.

Examples:

• Replace dummy with placeholder, sample.
• Replace sanity-check with final check, confirm.

Avoid unnecessarily gendered language Copy Section

Be aware of personal pronouns in examples and outdated gendered terms.

Best practices:

• Avoid personal pronouns (i.e., use proper nouns, "the user", etc.).
• If a personal pronoun is needed for clarity or conciseness, default to gender-neutral pronouns (they/them).

Examples:

• Replace man hours with one of: work hours, staff hours, person hours.
• Replace manning with staffing.
• Replace man-in-the-middle attack with machine-in-the-middle attack.

Write diverse and inclusive examples Copy Section

Avoid examples that are U.S.-specific or centric.

Best practices:

• Avoid U.S.-specific holidays, sports, figures of speech, etc.
• Use a diverse set of names in examples.

Avoid unnecessarily violent language Copy Section

Avoid terms that imply violence or harm.

Examples:

• Replace "kill" with terminate.
• Replace "hit Enter" with press Enter.
• Replace "hit your resource limits" with reach your resource limits
• Replace "hit an error" with experience an error.
• Replace "performance hit" with reduced performance.
• Replace "want to hit up" with want to visit.

Terminology around "kill" vs. "stop" vs. "terminate" is nuanced, as described in this GitHub comment. Use your best judgement.

Write accessible documentation Copy Section

• Don't use directional terms as the only clue to location within a page. "Left", "right", "up", "down", "above", and "below" aren't useful for people who use screen-reading software. Good replacements are "preceding" and "following". If you must use a directional term, provide additional text about the location, such as in the Save As dialog box, on the Standard toolbar, or in the title bar.
• Replace "see" with refer to.
• Provide alt text that adequately summarizes the intent of each image.
• Link text should be the same as or summarize the title of the link target. Avoid here and this documentation.

Write about features and users in inclusive ways Copy Section

Avoid using socially-charged terms for features and technical concepts.

Examples:

• Replace blacklist / whitelist with denylist / allowlist.
• Replace master / slave with main/principal/primary/manager and secondary/subordinate/worker.
• Replace native with core, built-in, top-level, integrated, "built for" or omit.
• Replace old with existing, previous, first, original.

Capitalization and punctuation Copy Chapter

Capitalization rules Copy Section

• Use title case for titles.
• Use sentence case for all headings.
• Capitalize proper nouns, CockroachDB product terms, and the names of UI features.
  • Examples: CockroachDB, Cockroach Labs, the Overview dashboard, the SQL Queries graph
• Follow SQL capitalization standards for SQL syntax.

For links to CockroachDB docs, match the capitalization of the linked content:

• Use title case when referring to the linked doc by its page title (for example, Refer to [Migration Strategy](https://www.cockroachlabs.com/docs/molt/migration-strategy) for more information.).
• Use sentence case when referring to the linked doc by one of its headers (for example, Refer to [Capacity planning](https://www.cockroachlabs.com/docs/molt/migration-strategy#capacity-planning) for further guidance.).

Punctuation rules Copy Section

• Use the Oxford (aka serial) comma.
• Use straight ' rather than curved ‘ quotes.
• Limit semicolon usage. Instead, use two simple sentences.
  • Avoid: CockroachDB is a distributed database; it scales horizontally across multiple nodes.
    Prefer: CockroachDB is a distributed database. It scales horizontally across multiple nodes.
• Do not end headings with punctuation (for example, periods or colons).
• Use periods on either all list items or none. If some items are sentences or complete a sentence, use periods.
• Use colons instead of dashes.
  • Avoid: Default - true
    Prefer: Default: true
• When listing a range of versions, do not use a dash. Instead, separate the first and last versions with to (for example, v22.1.0 to v22.1.4).
• For singular proper nouns ending in s, form the possessive with 's.
  • Example: Postgres's syntax
• For plural words or names ending in s, form the possessive with just an apostrophe.
  • Example: Cockroach Labs' products
• Place commas and periods inside quotation marks (for example, CockroachDB's availability model is described as "Multi-Active Availability."). Place other punctuation outside quotation marks (for example, What is "Multi-Active Availability"?). When any type of punctuation is part of a quote, place it inside the quotation marks (for example, To phrase it in the form of a question: "Who are the top 10 users by number of rides on a given date?").
• Avoid using slashes "/" and ampersands "&" in place of "or" and "and" respectively, unless space is very limited (such as in a table). Similarly, avoid using "and/or" unless space is very limited. Instead, decide whether "and" or "or" can stand alone, or make use of "both" when the inclusivity must be explicit (for example, x or y or both).

Vale Copy Chapter

The CockroachDB documentation uses Vale to identify common spelling mistakes or other patterns that may contradict the guidelines in this style guide. Check for items flagged by Vale in the Files Changed and Checks tabs of the pull request, grouped by file.

Try to address as many of the suggestions as possible. If Vale flags a word that is spelled and used correctly, add the word to netlify/vale/vocab.txt in the PR where the word is introduced. For other failed tests, you can work with your reviewer to correct the error in your PR or to improve the Vale test.

File conventions Copy Chapter

File names in the CockroachDB docs repo should be lowercase with a dash between words. File names for docs pages should match the page title whenever possible.

Examples:

• this-is-a-doc.md
• name-of-your-image.png

Content types Copy Chapter

There are four fundamental content types:

• Concept
• Task
• Reference
• Guide

Concept Copy Section

A concept topic explains how a particular feature works, or how a specific system is designed. Conceptual pages do not provide prescriptive guidance or instruction. For guidance or instruction, refer to Task or Guide.

• The first sentence answers the implicit question "what is a <singular noun>?" in the form A <singular noun> is …..

  Example: An index is a data structure that improves the speed of data retrieval operations on a database table at the cost of additional writes and storage space to maintain the index data structure.

• Provide as much relevant information as you can, and then link to other pages as necessary. If there is a related reference topic, link to it from within the conceptual topic.

For templates that provide a starting point for writing concept topics, refer to the concept templates.

Examples

• Indexes
• Architecture Overview
• SQL Layer

Task Copy Section

A task topic provides step-by-step instructions to complete a specific goal. Tasks are discrete and action-based. Tasks have the following properties:

• Answers the question "how do I do <an action>?" by describing precisely what to do and the order in which to do it.

• Corresponds to a specific user journey as defined by Product.

• The title or heading should state an actionable goal for the user, ideally of the form **\ [<article>|<conjunction>] <noun> or **.

  Example: Create an Index

• The verb ideally should be specific. Avoid generic verbs such as Use, Manage unless naming a page containing specific tasks.

• Avoid Your because you may be using an object that you don't "own".

  Example: Connect to a Cluster, not Connect to Your Cluster

• Lead with the verb. Don't bury it at the end of the heading.

  Example: Access DB Console, not DB Console Access.

• Present the steps as a list of numbered headings, e.g., "Step 1. ...".

Tasks should not include concept or reference information; instead, a task should link to Concept and Reference topics as needed.

For templates that provide a starting point for writing task topics, refer to the task templates.

Examples

• Create a CockroachCloud Cluster
• Upgrade to CockroachDB vXY.Z
• Stream a Changefeed to Snowflake

Reference Copy Section

Reference topics provide information about a specific CockroachDB function, feature, or interface. Reference topics are detail-oriented, and should include all of the information available on a specific topic, without providing prescriptive guidance. Prescriptive guidance is reserved for Guide topics.

Reference topics typically document programming constructs, interface parameters, or facts about a product, but do not provide explanations of concepts or tasks.

Reference topics help users understand the precise meaning and effect of CockroachDB SQL language constructs, platforms, configuration options, API parameter values, etc.

• The content should be comprehensive and accurate. This principle might apply to other page types, but it is especially important for reference, as it is the ultimate source of truth for a particular feature or interface.
• The content should be succinct. Details are often presented in table format. Prose is better suited for Concept topics.

For templates that provide a starting point for writing reference topics, refer to the reference templates.

Examples

• SQL reference: CREATE TABLE
• CLI reference: cockroach sql
• API reference: Cluster API

Guide Copy Section

Guides offer the reader a perspective on how to decide between a number of different ways of accomplishing a goal. They are meant to provide "guidance" (it's in the name) and should eventually lead the user to perform one or more Tasks.

To accomplish this goal, guides often link to several different Concept topics and compare and contrast them. They can also link to multiple Task topics.

For templates that provide a starting point for writing guide topics, refer to the guide templates.

Examples

• Migration Strategy
• Disaster Recovery Overview
• Multi-region Survival Goals

Page components Copy Chapter

This section describes how to approach page elements other than body text. For Markdown syntax and formatting, refer to the Markdown Guide.

Code Copy Section

Code blocks

Use separate code blocks for input and output. For example, rather than place both a SQL command and its resulting output within a single code block, place the SQL command inside one code block, followed by its output in another code block.

When you use multiple code blocks to demonstrate a task, interleave the code blocks with text that explains the content of each code block and clarifies where it stands in the overall flow.

Example:

1. To view all virtual clusters on the standby, run:

    {% include_cached copy-clipboard.html %}
    ~~~ sql
    SHOW VIRTUAL CLUSTERS;
    ~~~

    The standby cluster will show the `main` virtual cluster is in a `replicating` state.

    ~~~
      id |  name  | data_state  | service_mode
    -----+--------+-------------+---------------
       1 | system | ready       | shared
       3 | main   | replicating | none
    (2 rows)
    ~~~

Placeholders

Code samples often include placeholder values, to be replaced by values specific to a user's environment. To denote that a value in a code sample is a placeholder value that should be replaced, use curly brackets ({}).

• Example: SELECT * FROM TABLE {mytable};.

When you use placeholders, you usually need to define the value within the brackets, if the placeholder value isn't clear. Define placeholder values immediately following the code sample:

• For a single placeholder value, use a follow-up sentence.
• For multiple placeholder values, use a bulleted list.
• For many placeholder values (10+), use a table.
• For large code blocks, define the placeholder values inside the code block with an inline code comment.

Ensure that placeholders are placed within backticks: SET {session variable}. This signifies that placeholder values are code.

If the code sample is sensitive to curly bracket characters (as in JavaScript), you can use <> instead.

For code block syntax and formatting, refer to the Markdown Guide.

Callouts Copy Section

CockroachDB docs use three classes of "callouts," which are highlighted blocks of text: tips, notes, and warnings.

• Use a tip to highlight nice-to-know pieces of information.

  For example, you might use a tip to link to our GitHub repo's Terraform scripts on the Google Cloud Engine deployment page. It's nice to know it's there, but doesn't clarify anything nor is it critical.

• Use a note to call attention to a piece of clarifying information. This information should not be crucial to accomplishing the task in the document.

  For example, you might use a note to let users know that the DELETE statement only deletes rows and that to delete columns you must use ALTER TABLE. This helps clarify DELETE's purpose and point users to the right place.

• Use a warning to express that a piece of information is critical to understand to prevent data loss, security vulnerabilities, or unexpected behavior.

  For example, you might include a warning that using CASCADE in DROP INDEX drops dependent objects without warning. This is critical to prevent users from unexpectedly losing constraints or additional indexes.

Best practices:

• Avoid placing callouts next to each other.
• Do not overuse callouts. Most documentation belongs in the body of a page rather than in a callout.

For code block syntax and formatting, refer to the Markdown Guide.

Images Copy Section

Use images to clarify a topic, but only use them as needed. Images are either:

• Screenshots: Depict a UI element. Screenshots should only show enough of the UI that the user can easily orient themselves and understand what they are being shown. Exclude UI elements that are not relevant to the screenshot's purpose. If a screenshot needs an annotation, use a red box.

  Note: Screenshots are difficult to keep current, and impact accessibility. Use a screenshot only if it is necessary for the user to accomplish a task or understand a feature. For example, in a page on troubleshooting cluster performance, a screenshot of a Contention metric graph in the DB Console might be used to depict a cluster with high contention. The same screenshot would not be necessary in a reference topic about the DB Console user interface.

  To optimize accessibility and SEO, a screenshot should be accompanied by text and alt-text describing its contents.

• Diagrams: Visualize a complicated mechanism. Diagrams should not reproduce such complexity, and can simplify a process. A diagram should be easy to follow.

  The Docs team uses the following tools to compose diagrams:

  • Monodraw: useful for abstract concept diagrams
  • Omnigraffle: useful for diagrams with branded elements like logos and colors

  Icons for diagrams can be sourced from the cockroach-studios repo. The .gstencil file in the icons directory is an Omnigraffle template listing our branded primary/secondary/extended color palette.

For image syntax and embedding, refer to the Markdown Guide.

Videos Copy Section

Like images, use videos to clarify a topic, but only use them as needed. Typically, videos should be hosted on the official CockroachDB YouTube page and are surfaced by our Marketing team.

Place videos under their own page heading. For video embedding syntax, refer to the Markdown Guide.

Include files Copy Section

Sometimes content needs to be duplicated across two or more pages in the documentation. For example, there may be several pages that need the same cluster setup, but describe how to use different features. Or a callout needs to be added to several different pages.

In these situations, use an include file. An include file is a separate Markdown file (stored in _includes/some/shared-file.md) whose content is shared across multiple pages.

Note: Using include files adds complexity to the docs site architecture and build process. Consider linking to an existing page or subheading rather than using an include file.

For include file syntax, refer to the Markdown Guide.

Links Copy Section

GitHub links

Release notes, technical advisories, and known limitations contain links to individual GitHub issues and pull requests.

Reference issues and pull requests by their corresponding number, prepended with #.

Example: [#1](https://github.com/cockroachlabs/docs/pull/1)

External links

When linking to third-party documentation, consider the purpose and maintenance implications. Link to third-party sources for integration workflows, official API references, and tool configurations that change frequently.

Best practices:

• Link to stable, official documentation pages when possible and ensure links point to the appropriate version of the external product.
• Avoid linking to blog posts or unofficial sources.
• Consider whether a brief explanation in our docs would be more reliable than an external link.

For link syntax, refer to the Markdown Guide.

Page sections Copy Chapter

For page headings, refer to the Markdown Guide.

Before you begin Copy Section

A Before you begin section describes prerequisites for following the page content. These may be setup requirements or contextual information that's helpful to the task. Place this section immediately after the page introduction.

Best practices:

• Keep prerequisites specific and actionable.
• Link to relevant setup or configuration pages.
• Use a bulleted list for multiple prerequisites.
• Avoid generic statements like "Have CockroachDB installed" unless the page specifically requires a fresh installation.

Known limitations Copy Section

A Known limitations section describes unexpected database behaviors that differ from SQL standards, PostgreSQL behavior, or expected functionality. Document all known limitations on the Known Limitations page and on feature-specific pages under a dedicated "Known limitations" header.

Document limitations during GA release weeks or when discovered post-release. For detailed procedures, refer to the documentation wiki.

See also Copy Section

A See also section contains links to related pages. This is always the last section in a page.

File: src/api/_config_base.yml Copy Chapter

baseurl: /docs/api defaults: Copy Chapter

scope:
  path: "" # an empty string here means all files in the project
values:
  layout: "tutorial"

destination: _site/docs/api
exclude:

• tests
• build
• scripts
• vendor
• archived
• package.json
• package-lock.json
• build-netlify.sh
  include:
• _redirects
  jekyll-minifier:
  compress_css: 'false'
  compress_javascript: 'true'
  compress_js_templates: 'false'
  compress_json: 'true'
  exclude:
  • '**.html'
  • js/rapidoc-min.js
    preserve_line_breaks: 'false'
    preserve_php: 'true'
    remove_comments: 'true'
    remove_form_attributes: 'false'
    remove_http_protocol: 'false'
    remove_https_protocol: 'false'
    remove_input_attributes: 'false'
    remove_intertag_spaces: 'false'
    remove_javascript_protocol: 'false'
    remove_link_attributes: 'false'
    remove_multi_spaces: 'false'
    remove_quotes: 'false'
    remove_script_attributes: 'false'
    remove_spaces_inside_tags: 'false'
    remove_style_attributes: 'false'
    simple_boolean_attributes: 'false'
    simple_doctype: 'false'
    uglifier_args:
    harmony: 'true'
    jekyll_get_json:
• data: cloud_api_releases
  json: https://cockroachlabs.cloud/assets/docs/api/manifest.json
  main_url: https://www.cockroachlabs.com
  plugins:
• jekyll-include-cache
• jekyll-last-modified-at
• jekyll-minifier
• jekyll-get-json
  site_title: CockroachDB Docs

File: src/api/package.json Copy Chapter

{
"name": "cockroachdb-docs",
"version": "2.0.0",
"devDependencies": {
"@netlify/plugin-lighthouse": "^4.0.7",
"jest": "^26",
"jest-cli": "^26"
},
"dependencies": {
"front-matter": "^4.0.2",
"redoc-cli": "^0.11.4",
"snippet-enricher-cli": "^0.0.8",
"swagger2openapi": "^7.0.5",
"yaml": "^1.10.2"
}
}

File: src/api/.htmltest.yml Copy Chapter

DirectoryPath: "_site"
ExternalTimeout: 30
IgnoreDirs:

• ^docs/stable
• ^docs/dev
• ^docs/v1.0
• ^docs/v1.1
• ^docs/v1.2
• ^docs/v2.0
• ^docs/v2.1
• ^docs/v19.1
• ^docs/v19.2
• ^docs/v20.1
• ^docs/v20.2
• ^docs/v21.1
  IgnoreURLs:
• "http://localhost:*"
• "http://roach-single/*"
• "https://roach-single/*"
• "https://github.com/*"
• "https://raw.github.com/*"
• "https://docs.github.com/*"
• "https://movr.cloud"
• "https://support.cockroachlabs.com/*"
• "https://www.cockroachlabs.com/*"
• "https://www.php.net/*"
• "https://crates.io/*"
• "https://docs.pipenv.org/*"
• "https://arxiv.org/*"
• "https://fonts.googleapis.com/*"
• "https://fonts.gstatic.com/*"
• "https://typeorm.io/*"
• "https://www.googleadservices.com/*"
  IgnoreInternalEmptyHash: true
  TestFilesConcurrently: true
  DocumentConcurrencyLimit: 16

File: src/api/cloud/v1.md Copy Chapter

title: CockroachDB Cloud API summary: Learn about the CockroachDB Cloud API layout: api docs_area: reference.api Copy Chapter

{% assign releases = site.data.cloud_api_releases.specs %}

**nav-logo** slot 


  Version: 
  <select class="dropdown" id="versionSelector" onchange="changeVersion()">
    {% for r in site.data.cloud_api_releases.specs %}
      <option value="{{ r.path }}" label="{{ r.id }}{% if r.type == "PRIVATE_PREVIEW" %} (Private Preview){% endif %}">{{ r.id }}</option>
    {% endfor %}
  </select>

File: src/api/cluster/v2.md Copy Chapter

title: CockroachDB v2 API summary: Learn about the CockroachDB v2 API (2.0.0). layout: api docs_area: reference.api Copy Chapter

File: src/archived/README.md Copy Chapter

Archived Pages

This directory contains pages that we are not building into our docs site but that we want to keep around for potential resurrection.

File: src/archived/demo-follow-the-workload.md Copy Chapter

title: Follow-the-Workload summary: CockroachDB can dynamically optimize read latency for the location from which most of the workload is originating. toc: true Copy Chapter

"Follow-the-workload" refers to CockroachDB's ability to dynamically optimize read latency for the location from which most of the workload is originating. This page explains how "follow-the-workload" works and walks you through a simple demonstration using a local cluster.

{{site.data.alerts.callout_info}}
In practice, follow-the-workload is most useful when a CockroachDB cluster is running across multiple regions, with high latency between them, but other patterns are often preferable. For more details, see Multi-Region Topology Patterns.
{{site.data.alerts.end}}

Before you begin Copy Chapter

Basic concepts Copy Section

To understand how "follow-the-workload" works, it's important to start with some basic concepts:

How it works Copy Section

"Follow-the-workload" is based on the way range leases handle read requests. Read requests bypass the Raft consensus protocol, accessing the range replica that holds the range lease (the leaseholder) and sending the results to the client without needing to coordinate with any of the other range replicas. Bypassing Raft, and the network round trips involved, is possible because the leaseholder is guaranteed to be up-to-date due to the fact that all write requests also go to the leaseholder.

This increases the speed of reads, but it doesn't guarantee that the range lease will be anywhere close to the origin of requests. If requests are coming from the US West, for example, and the relevant range lease is on a node in the US East, the requests would likely enter a gateway node in the US West and then get routed to the node with the range lease in the US East.

However, you can cause the cluster to actively move range leases for even better read performance by starting each node with the --locality flag. With this flag specified, the cluster knows about the location of each node, so when there's high latency between nodes, the cluster will move active range leases to a node closer to the origin of the majority of the workload. This is especially helpful for applications with workloads that move around throughout the day (e.g., most of the traffic is in the US East in the morning and in the US West in the evening).

{{site.data.alerts.callout_success}}
To enable "follow-the-workload", you just need to start each node of the cluster with the --locality flag, as shown in the tutorial below. No additional user action is required.
{{site.data.alerts.end}}

Example Copy Section

In this example, let's imagine that lots of read requests are going to node 1, and that the requests are for data in range 3. Because range 3's lease is on node 3, the requests are routed to node 3, which returns the results to node 1. Node 1 then responds to the clients.

However, if the nodes were started with the --locality flag, after a short while, the cluster would move range 3's lease to node 1, which is closer to the origin of the workload, thus reducing the network round trips and increasing the speed of reads.

Step 1. Install prerequisites Copy Chapter

In this tutorial, you'll use CockroachDB, the comcast network tool to simulate network latency on your local workstation, and the tpcc workload built into CockroachDB to simulate client workloads. Before you begin, make sure these applications are installed:

• Install the latest version of CockroachDB.
• Install Go version 1.9 or higher. If you're on a Mac and using Homebrew, use brew install go. You can check your local version by running go version.
• Install the comcast network simulation tool: go get github.com/tylertreat/comcast

Also, to keep track of the data files and logs for your cluster, you may want to create a new directory (e.g., mkdir follow-workload) and start all your nodes in that directory.

Step 2. Start the cluster Copy Chapter

Use the cockroach start command to start 3 nodes on your local workstation, using the --locality flag to pretend that each node is in a different region of the US.

1. Start a node in the "US West":

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach start \
    --insecure \
    --locality=region=us-west \
    --store=follow1 \
    --listen-addr=localhost:26257 \
    --http-addr=localhost:8080 \
    --join=localhost:26257,localhost:26258,localhost:26259 \
    --background

2. Start a node in the "US Midwest":

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach start \
    --insecure \
    --locality=region=us-midwest \
    --store=follow2 \
    --listen-addr=localhost:26258 \
    --http-addr=localhost:8081 \
    --join=localhost:26257,localhost:26258,localhost:26259 \
    --background

3. Start a node in the "US East":

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach start \
    --insecure \
    --locality=region=us-east \
    --store=follow3 \
    --listen-addr=localhost:26259 \
    --http-addr=localhost:8082 \
    --join=localhost:26257,localhost:26258,localhost:26259 \
    --background

4. Use the cockroach init command to perform a one-time initialization of the cluster:

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach init \
    --insecure \
    --host=localhost:26257

Step 3. Simulate network latency Copy Chapter

"Follow-the-workload" only kicks in when there's high latency between the nodes of the CockroachDB cluster. In this tutorial, you'll run 3 nodes on your local workstation, with each node pretending to be in a different region of the US. To simulate latency between the nodes, use the comcast tool that you installed earlier.

1. Start comcast as follows:

   {% include copy-clipboard.html %}

   shell Copy

   $ comcast --device lo0 --latency 100

   For the --device flag, use lo0 if you're on Mac or lo if you're on Linux. If neither works, run the ifconfig command and find the interface responsible for 127.0.0.1 in the output.

   This command causes a 100 millisecond delay for all requests on the loopback interface of your local workstation. It will only affect connections from the machine to itself, not to/from the Internet.

2. To verify the delay between nodes, check the Network Latency page of the Admin UI:

Step 4. Simulate traffic in the US East Copy Chapter

Now that the cluster is live, use CockroachDB's built-in version the tpcc benchmark to simulate multiple client connections to the node in the "US East".

1. Load the initial schema and data, pointing it at port 26259, which is the port of the node with the us-east locality:

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach workload init tpcc \
    'postgresql://root@localhost:26259?sslmode=disable'

2. Let the workload run to completion.

Step 5. Check the location of the range lease Copy Chapter

The load generator created a tpcc database with several tables that map to underlying key-value ranges. Verify that the range lease for the customer table moved to the node in the "US East" as follows.

1. Run the cockroach node status command against any node:

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach node status --insecure --host=localhost:26259

   text Copy

   id |     address     |   sql_address   |                  build                  |            started_at            |            updated_at            |     locality      | is_available | is_live
    +----+-----------------+-----------------+-----------------------------------------+----------------------------------+----------------------------------+-------------------+--------------+---------+
       1 | localhost:26257 | localhost:26257 | v19.2.0-alpha.20190606-2491-gfe735c9a97 | 2019-09-28 03:14:20.566372+00:00 | 2019-09-28 03:18:41.866604+00:00 | region=us-west    | true         | true
       2 | localhost:26259 | localhost:26259 | v19.2.0-alpha.20190606-2491-gfe735c9a97 | 2019-09-28 03:14:21.353188+00:00 | 2019-09-28 03:18:38.165272+00:00 | region=us-east    | true         | true
       3 | localhost:26258 | localhost:26258 | v19.2.0-alpha.20190606-2491-gfe735c9a97 | 2019-09-28 03:14:21.862969+00:00 | 2019-09-28 03:18:38.577831+00:00 | region=us-midwest | true         | true
    (3 rows)

2. In the response, note the ID of the node running on port 26259 (in this case, node 2).

3. Connect the built-in SQL shell to any node:

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach sql --insecure --host=localhost:26259

4. Check where the range lease is for the tpcc.customer table:

   {% include copy-clipboard.html %}

   sql Copy

   > SHOW RANGES FROM TABLE tpcc.customer;

   text Copy

   start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas |                replica_localities
    +-----------+---------+----------+---------------+--------------+-----------------------+----------+---------------------------------------------------+
      NULL      | NULL    |       28 |     19.194141 |            2 | region=us-east        | {1,2,3}  | {region=us-west,region=us-east,region=us-midwest}
    (1 row)

   lease_holder and replicas indicate the node IDs. As you can see, the lease for the range holding the customer table's data is on node 2, which is the same ID as the node on port 26259.

5. Exit the SQL shell:

   {% include copy-clipboard.html %}

   sql Copy

   > \q

Step 6. Simulate traffic in the US West Copy Chapter

1. Run the cockroach workload run tpcc command to generate more load, this time pointing it at port 26257, which is the port of the node with the us-west locality:

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach workload run tpcc \
    --duration=5m \
    'postgresql://root@localhost:26257?sslmode=disable'

   You'll see per-operation statistics print to standard output every second.

2. Let the workload run to completion. This is necessary since the system will still "remember" the earlier requests to the other locality.

   {{site.data.alerts.callout_info}}
   The latency numbers printed by the workload will be over 200 milliseconds because the 100 millisecond delay in each direction (200ms round-trip) caused by the comcast tool also applies to the traffic going from the tpcc process to the cockroach process. If you were to set up more advanced rules that excluded the tpcc process's traffic or to run this on a real network with real network delay, these numbers would be down in the single-digit milliseconds.
   {{site.data.alerts.end}}

Step 7. Check the location of the range lease Copy Chapter

Verify that the range lease for the customer table moved to the node in the "US West" as follows.

1. Connect the built-in SQL shell to any node:

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach sql --insecure --host=localhost:26257

2. Check where the range lease is for the tpcc.customer table:

   {% include copy-clipboard.html %}

   sql Copy

   > SHOW RANGES FROM TABLE tpcc.customer;

   text Copy

   start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas |                replica_localities
    +-----------+---------+----------+---------------+--------------+-----------------------+----------+---------------------------------------------------+
      NULL      | NULL    |       28 |     19.194141 |            1 | region=us-west        | {1,2,3}  | {region=us-west,region=us-east,region=us-midwest}
    (1 row)

   As you can see, the lease for the range holding the customer table's data is now on node 1, which is the same ID as the node on port 26257.

Step 8. Clean up Copy Chapter

1. Once you're done with this tutorial, you will not want a 100 millisecond delay for all requests on your local workstation, so stop the comcast tool:

   {% include copy-clipboard.html %}

   shell Copy

   $ comcast --device lo0 --stop

2. Use the cockroach quit command to gracefully shut down each node:

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach quit --insecure --host=localhost:26257

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach quit --insecure --host=localhost:26258

   {{site.data.alerts.callout_info}}
   For the last node, the shutdown process will take longer (about a minute each) and will eventually force the node to stop. This is because, with only 1 of 3 nodes left, a majority of replicas are not available, and so the cluster is no longer operational.
   {{site.data.alerts.end}}

   {% include copy-clipboard.html %}

   shell Copy

   $ cockroach quit --insecure --host=localhost:26259

3. To restart the cluster at a later time, run the same cockroach start commands as earlier from the directory containing the nodes' data stores.

   If you do not plan to restart the cluster, you may want to remove the nodes' data stores:

   {% include copy-clipboard.html %}

   shell Copy

   $ rm -rf follow1 follow2 follow3

What's next? Copy Chapter

Explore other core CockroachDB benefits and features:

{% include {{ page.version.version }}/misc/explore-benefits-see-also.md %}

File: src/archived/detailed-sql-support.md Copy Chapter

title: Detailed SQL Standard Comparison summary: Details of CockroachDB's conformance to the SQL standard and which common extensions it supports. Copy Chapter

This page lists which SQL standard features are supported, partially-supported, and unsupported by CockroachDB.

To understand the extent to which we support the standard SQL features, use the table below.

• Feature ID is the SQL Standard feature identification number.
• Description provides details about the feature.
• CockroachDB Support indicates whether the feature is supported, unsupported, or partially-supported by CockroachDB.

Features Copy Chapter

File: src/archived/sidebar-data-training.json Copy Chapter

[
{
"title": "Training Home",
"urls": [
"/${VERSION}/training/"
]
},
{
"title": "Introduction",
"items": [
{
"title": "Why CockroachDB?",
"urls": [
"/${VERSION}/training/why-cockroachdb.html"
]
},
{
"title": "Architecture Overview",
"urls": [
"/${VERSION}/training/architecture-overview.html"
]
}
]
},
{
"title": "Key Capabilities",
"items": [
{
"title": "Cluster Startup and Scaling",
"urls": [
"/${VERSION}/training/cluster-startup-and-scaling.html"
]
},
{
"title": "Fault Tolerance and Automated Repair",
"urls": [
"/${VERSION}/training/fault-tolerance-and-automated-repair.html"
]
},
{
"title": "Locality and Replication Zones",
"urls": [
"/${VERSION}/training/locality-and-replication-zones.html"
]
},
{
"title": "Geo-Partitioning",
"urls": [
"/${VERSION}/training/geo-partitioning.html"
]
},
{
"title": "Orchestration with Kubernetes",
"urls": [
"/${VERSION}/training/orchestration-with-kubernetes.html"
]
},
{
"title": "Performance Benchmarking",
"urls": [
"/${VERSION}/training/performance-benchmarking.html"
]
}
]
},
{
"title": "Ops Basics",
"items": [
{
"title": "Data Import",
"urls": [
"/${VERSION}/training/data-import.html"
]
},
{
"title": "SQL Basics",
"urls": [
"/${VERSION}/training/sql-basics.html"
]
},
{
"title": "Users and Privileges",
"urls": [
"/${VERSION}/training/users-and-privileges.html"
]
},
{
"title": "Security",
"urls": [
"/${VERSION}/training/security.html"
]
},
{
"title": "Production Deployment",
"urls": [
"/${VERSION}/training/production-deployment.html"
]
},
{
"title": "Monitoring and Alerting",
"urls": [
"/${VERSION}/training/monitoring-and-alerting.html"
]
},
{
"title": "Debug Logs",
"urls": [
"/${VERSION}/training/logs.html"
]
}
]
},
{
"title": "Troubleshooting",
"items": [
{
"title": "Node Startup",
"urls": [
"/${VERSION}/training/node-startup-troubleshooting.html"
]
},
{
"title": "Client Connection",
"urls": [
"/${VERSION}/training/client-connection-troubleshooting.html"
]
},
{
"title": "Under-Replication",
"urls": [
"/${VERSION}/training/under-replication-troubleshooting.html"
]
},
{
"title": "Cluster Unavailability",
"urls": [
"/${VERSION}/training/cluster-unavailability-troubleshooting.html"
]
},
{
"title": "Data Unavailability",
"urls": [
"/${VERSION}/training/data-unavailability-troubleshooting.html"
]
},
{
"title": "Data Corruption",
"urls": [
"/${VERSION}/training/data-corruption-troubleshooting.html"
]
},
{
"title": "Software Panic",
"urls": [
"/${VERSION}/training/software-panic-troubleshooting.html"
]
},
{
"title": "Network Partition",
"urls": [
"/${VERSION}/training/network-partition-troubleshooting.html"
]
},
{
"title": "How Cockroach Labs Debugs",
"urls": [
"/${VERSION}/training/how-cockroach-labs-debugs.html"
]
},
{
"title": "How to Get Support",
"urls": [
"/${VERSION}/training/how-to-get-support.html"
]
}
]
},
{
"title": "Maintenance",
"items": [
{
"title": "Planned Maintenance",
"urls": [
"/${VERSION}/training/planned-maintenance.html"
]
},
{
"title": "Node Decommissioning",
"urls": [
"/${VERSION}/training/node-decommissioning.html"
]
},
{
"title": "Backup and Restore",
"urls": [
"/${VERSION}/training/backup-and-restore.html"
]
},
{
"title": "Cluster Upgrade",
"urls": [
"/${VERSION}/training/cluster-upgrade.html"
]
}
]
},
{
"title": "Wrap Up",
"items": [
{
"title": "Give Us Feedback",
"urls": [
"https://goo.gl/forms/UmtasgsYrBgQrrKl1"
]
},
{
"title": "Explore Our Docs",
"urls": [
"/${VERSION}/"
]
}
]
}
]

/*
{
"title": "Introduction",
"items": [
{
"title": "Why CockroachDB?",
"urls": [
"/${VERSION}/training/why-cockroachdb.html"
]
},
{
"title": "Architecture Overview",
"urls": [
"/${VERSION}/training/architecture-overview.html"
]
}
]
},
{
"title": "Ops Basics",
"items": [
{
"title": "Cluster Startup and Scaling",
"urls": [
"/${VERSION}/training/cluster-startup-and-scaling.html"
]
},
{
"title": "Fault Tolerance and Automated Repair",
"urls": [
"/${VERSION}/training/fault-tolerance-and-automated-repair.html"
]
},
{
"title": "Locality and Replication Zones",
"urls": [
"/${VERSION}/training/locality-and-replication-zones.html"
]
},
]
},
{
"title": "More Training?",
"urls": [
"https://www.surveymonkey.com/r/5TGPWRJ"
]
}
] */

File: src/current/404.md Copy Chapter

title: Page Not Found summary: The requested CockroachDB documentation page was not found. sitemap: false search: exclude related_pages: none toc: false docs_area: 404 Copy Chapter

{%comment%}

{%endcomment%}

File: src/current/_config_base.yml Copy Chapter

algolia:
application_id: 7RXZLDVR5F
files_to_exclude:
- index.html
- index.md
- search.html
- src/current/v23.1/**
- v23.1/**
index_name: stage_cockroach_docs
search_api_key: 372a10456f4ed7042c531ff3a658771b
settings:
attributesForFaceting:
- searchable(categories)
- searchable(collection)
- docs_area
- searchable(tags)
- searchable(title)
- type
defaults:

• scope:
  path: ''
  type: pages
  values:
  layout: page
  exclude:
• tests
• build
• scripts
• vendor
• jekyll-algolia-dev
• archived
• package.json
• package-lock.json
  include:
• _redirects
  jekyll-minifier:
  compress_css: 'false'
  compress_javascript: 'true'
  compress_js_templates: 'false'
  compress_json: 'true'
  exclude:
  • '**.html'
  • js/rapidoc-min.js
    preserve_line_breaks: 'false'
    preserve_php: 'true'
    remove_comments: 'true'
    remove_form_attributes: 'false'
    remove_http_protocol: 'false'
    remove_https_protocol: 'false'
    remove_input_attributes: 'false'
    remove_intertag_spaces: 'false'
    remove_javascript_protocol: 'false'
    remove_link_attributes: 'false'
    remove_multi_spaces: 'false'
    remove_quotes: 'false'
    remove_script_attributes: 'false'
    remove_spaces_inside_tags: 'false'
    remove_style_attributes: 'false'
    simple_boolean_attributes: 'false'
    simple_doctype: 'false'
    jekyll_get_json:
• data: cloud_api_releases
  json: https://cockroachlabs.cloud/assets/docs/api/manifest.json
  keep_files:
• _internal
  main_url: https://www.cockroachlabs.com
  markdown: Redcarpet
  plugins:
• jekyll-include-cache
• jekyll-last-modified-at
• jekyll-minifier
• jekyll-get-json
  sass:
  quiet_deps: 'true'
  sass_dir: css
  style: compressed
  site_title: CockroachDB Docs

File: src/current/_config_cockroachdb.yml Copy Chapter

baseurl: /docs
current_cloud_version: v26.2
destination: _site/docs
homepage_title: CockroachDB Docs
versions:
stable: v26.2
dev: v26.2

File: src/current/_config_cockroachdb_local.yml Copy Chapter

exclude:

• "v1.0"
• "v1.1"
• "v2.0"
• "v2.1"
• "v19.1"
• "v19.2"
• "v20.1"
• "ci"
• "scripts"
• "vendor"
• "archived"

File: src/current/_config_cockroachdb_no_remote_cache.yml Copy Chapter

this option turns off local caching of remote_include files

remote_include:
use_cache: false

File: src/current/AGENTS.md Copy Chapter

AGENTS.md for CockroachDB docs

Hello! We're working together on docs for CockroachDB, a distributed SQL database. The docs are located in Markdown files (with Liquid templates) in various subdirectories of this one.

This file has instructions and general info for working with us on these docs. Please pay close attention to things written here.

Docs for each released version are in subdirectories named for the version, e.g., v25.4.

Docs specific to the CockroachDB Cloud product are in cockroachcloud.

Docs related to release notes and other release-related matters are in releases.

Style guide Copy Chapter

Our style guide lives in StyleGuide.md in the root of this repository. Please follow the guidance there carefully when writing docs.

Include files Copy Chapter

To avoid repeating text across different files, we use shared "include files" (or just: "includes") which are referenced using the following syntax.

For includes that apply across versions or products:

{% include common/define-watched-cdc.md %}

For includes that pertain to the CockroachDB Cloud product:

{% include cockroachcloud/metrics-time-interval-selection.md %}

For includes that we can assume only apply to specific versions, though in some cases, their content may be identical across all versions where the file exists:

{% include vXX.Y/misc/cert-auth-using-x509-subject.md %}

Note: The Liquid variable {{page.version.version}} resolves to the major version in the path of the page where it is used (e.g. v25.4). References to version-specific includes often use this, allowing the same page content that's used across versions to show different versions of an include, based on the current version being rendered. For example, {% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %}.

The includes are all located in subdirectories of the _include directory, i.e.,

• _include/common for widely shared things
• _include/cockroachcloud for Cloud
• _include/v25.4 for v25.4-specific content

File: src/current/README_ALGOLIA_MIGRATION.md Copy Chapter

CockroachDB Documentation Algolia Migration

This repository contains the complete Algolia search migration system for CockroachDB documentation, replacing the Jekyll Algolia gem with a custom Python-based indexing solution.

📋 Overview Copy Chapter

What This Migration Provides Copy Section

• 🎯 Smart Indexing: Intelligent content extraction with bloat removal
• 🔄 Incremental Updates: Only index changed content, with deletion support
• 📏 Dynamic Version Detection: Automatically detects and indexes the current stable version
• 🏢 TeamCity Integration: Production-ready CI/CD deployment
• ⚡ Performance: ~90% size reduction vs naive indexing while maintaining quality

Migration Benefits Copy Section

🏗️ System Architecture Copy Chapter

Core Components Copy Section

┌─────────────────────────────────────────────────┐
│                TeamCity Job                     │
├─────────────────────────────────────────────────┤
│ 1. Jekyll Build (creates _site/)               │
│ 2. algolia_indexing_wrapper.py                 │
│    ├── Smart Full/Incremental Decision         │
│    ├── Version Detection                       │
│    └── Error Handling & Logging                │
│ 3. algolia_index_intelligent_bloat_removal.py  │
│    ├── Content Extraction                      │
│    ├── Intelligent Bloat Filtering             │
│    ├── Stable Object ID Generation             │
│    └── Algolia API Updates                     │
└─────────────────────────────────────────────────┘

📁 Files Overview Copy Chapter

Production Files (Essential) Copy Section

Development/Testing Files Copy Section

🚀 TeamCity Deployment Copy Chapter

Build Configuration Copy Section

# Build Steps
1. "Build Documentation Site"
   - bundle install
   - bundle exec jekyll build --config _config_cockroachdb.yml

2. "Index to Algolia"  
   - python3 algolia_indexing_wrapper.py

Environment Variables Copy Section

# Required (TeamCity Secure Variables)
ALGOLIA_APP_ID=7RXZLDVR5F
ALGOLIA_ADMIN_API_KEY=<encrypted_key>

# Configuration
ALGOLIA_INDEX_ENVIRONMENT=staging  # or 'production'
ALGOLIA_STATE_DIR=/opt/teamcity-data/algolia_state
ALGOLIA_FORCE_FULL=false  # Set to 'true' to force full reindex

Server Setup Copy Section

# On TeamCity agent machine
sudo mkdir -p /opt/teamcity-data/algolia_state
sudo chown teamcity:teamcity /opt/teamcity-data/algolia_state
sudo chmod 755 /opt/teamcity-data/algolia_state

🎯 Smart Indexing Logic Copy Chapter

Automatic Full vs Incremental Decision Copy Section

The wrapper automatically decides between full and incremental indexing:

Full Indexing Triggers:

1. First Run: No state file exists
2. Force Override: ALGOLIA_FORCE_FULL=true
3. Corrupted State: Invalid state file
4. Stale State: State file >7 days old
5. Content Changes: Git commits affecting source files
6. Config Changes: _config_cockroachdb.yml modified
7. Incomplete Previous: <100 files tracked (indicates failure)

Incremental Indexing (Default):

• Recent valid state file
• No source file changes
• No configuration changes
• Previous indexing was complete

Version Detection Copy Section

Dynamically reads from _config_cockroachdb.yml:

versions:
  stable: v25.3  # ← Automatically detected and used
  dev: v25.3

Indexing Rules:

• ✅ Always include: /releases/, /cockroachcloud/, /advisories/, /molt/
• ✅ Include stable version files: Files containing v25.3
• ❌ Exclude old versions: v24.x, v23.x, etc.
• 🔄 Smart dev handling: Only exclude dev if stable equivalent exists

🧠 Intelligent Bloat Removal Copy Chapter

What Gets Removed Copy Section

• 85K+ Duplicate Records: Content deduplication using MD5 hashing
• UI Spam: Navigation elements, dropdowns, version selectors
• Table Bloat: Repetitive headers, "Yes/No" cells
• Download Spam: "SQL shell Binary", "Full Binary" repetition
• Grammar Noise: "referenced by:", "no references"
• Version Clutter: Standalone version numbers, dates

What Gets Preserved Copy Section

• ✅ All SQL commands and syntax
• ✅ Technical documentation content
• ✅ Error messages and troubleshooting
• ✅ Release notes and changelogs
• ✅ Important short technical terms
• ✅ Complete page coverage (no artificial limits)

📊 Performance Metrics Copy Chapter

Size Optimization Copy Section

Production Index: 157,471 records
Naive Indexing:  ~350,000 records  
Size Reduction:  55% smaller
Quality:         Maintained/Improved

Speed Improvements Copy Section

Jekyll Gem Full Rebuild: ~15-20 minutes
Python Incremental:      ~2-3 minutes  
Python Full Rebuild:     ~8-10 minutes

🧪 Testing & Validation Copy Chapter

Comprehensive Test Coverage Copy Section

Run the full test suite:

# Test wrapper decision logic (10 scenarios)
python3 test_wrapper_scenarios.py

# Test incremental indexing functionality  
python3 test_incremental_indexing.py

# Verify production parity
python3 check_ranking_parity.py

# Test all file processing
python3 test_all_files.py

Test Scenarios Copy Section

1. ✅ First Run Detection - Missing state file → Full indexing
2. ✅ Force Full Override - ALGOLIA_FORCE_FULL=true → Full indexing
3. ✅ Corrupted State Handling - Invalid JSON → Full indexing
4. ✅ Stale State Detection - >7 days old → Full indexing
5. ✅ Git Change Detection - Source commits → Full indexing
6. ✅ Config Change Detection - _config*.yml changes → Full indexing
7. ✅ Incomplete Recovery - <100 files tracked → Full indexing
8. ✅ Normal Incremental - Healthy state → Incremental indexing
9. ✅ Error Recovery - Graceful handling of all failure modes
10. ✅ State Persistence - File tracking across runs

🔧 Configuration Options Copy Chapter

Environment Variables Copy Section

# Core Configuration
ALGOLIA_APP_ID="7RXZLDVR5F"                    # Algolia application ID
ALGOLIA_ADMIN_API_KEY="<secret>"               # Admin API key (secure)
ALGOLIA_INDEX_NAME="staging_cockroach_docs"    # Target index name

# Smart Wrapper Configuration  
ALGOLIA_INDEX_ENVIRONMENT="staging"            # Environment (staging/production)
ALGOLIA_STATE_DIR="/opt/teamcity-data/algolia_state"  # Persistent state directory
ALGOLIA_FORCE_FULL="false"                     # Force full reindex override

# Indexer Configuration
ALGOLIA_INCREMENTAL="false"                    # Set by wrapper automatically
ALGOLIA_TRACK_FILE="/path/to/state.json"       # Set by wrapper automatically
SITE_DIR="_site"                               # Jekyll build output directory

📈 Monitoring & Logging Copy Chapter

Comprehensive Logging Copy Section

The system provides detailed logging for monitoring:

{
  "timestamp": "2025-09-09T16:20:00Z",
  "environment": "staging", 
  "index_name": "staging_cockroach_docs",
  "mode": "INCREMENTAL",
  "reason": "State file exists and is recent",
  "success": true,
  "duration_seconds": 142.5,
  "state_file_exists": true,
  "state_file_size": 125430
}

Log Locations Copy Section

# Wrapper execution logs
/opt/teamcity-data/algolia_state/indexing_log_<environment>.json

# State tracking file
/opt/teamcity-data/algolia_state/files_tracked_<environment>.json

# TeamCity build logs (stdout/stderr)

🚨 Troubleshooting Copy Chapter

Common Issues Copy Section

❌ "State file not found"

• Cause: First run or state file was deleted
• Solution: Normal - will do full indexing automatically

❌ "Git commits detected"

• Cause: Source files changed since last indexing
• Solution: Normal - will do full indexing automatically

❌ "Missing ALGOLIA_ADMIN_API_KEY"

• Cause: Environment variable not set in TeamCity
• Solution: Add secure variable in TeamCity configuration

❌ "Too few files tracked"

• Cause: Previous indexing was incomplete
• Solution: Normal - will do full indexing to recover

❌ "Indexer script not found"

• Cause: Missing algolia_index_intelligent_bloat_removal.py
• Solution: Ensure all files are deployed with the wrapper

Manual Override Copy Section

Force a full reindex:

# In TeamCity, set parameter:
ALGOLIA_FORCE_FULL=true

State File Management Copy Section

# View current state
cat /opt/teamcity-data/algolia_state/files_tracked_staging.json

# Reset state (forces full reindex next run)
rm /opt/teamcity-data/algolia_state/files_tracked_staging.json

# View recent run logs
cat /opt/teamcity-data/algolia_state/indexing_log_staging.json

🔄 Migration Process Copy Chapter

Phase 1: Validation (Complete) Copy Section

• ✅ Built and tested Python indexing system
• ✅ Validated against production index (96%+ parity)
• ✅ Comprehensive test coverage (100% pass rate)
• ✅ Performance optimization and bloat removal

Phase 2: Staging Deployment (Next) Copy Section

• Deploy to TeamCity staging environment
• Configure environment variables and state persistence
• Monitor performance and validate incremental updates
• Compare search quality against production

Phase 3: Production Deployment Copy Section

• Deploy to production TeamCity environment
• Switch from Jekyll Algolia gem to Python system
• Monitor production search quality and performance
• Remove Jekyll Algolia gem dependency

💡 Key Innovations Copy Chapter

1. **Intelligent Bloat Detection** Copy Section

Instead of naive content extraction, the system uses pattern recognition to identify and remove repetitive, low-value content while preserving technical documentation.

2. **Stable Object IDs** Copy Section

Object IDs are based on URL + position, not content. This enables true incremental updates - only records with structural changes get new IDs.

3. **Smart Decision Logic** Copy Section

The wrapper uses multiple signals (git history, file timestamps, state analysis) to automatically choose the optimal indexing strategy.

4. **Production Parity** Copy Section

Field mapping, content extraction, and ranking factors match the existing production index exactly.

5. **Zero-Downtime Deployment** Copy Section

Incremental indexing allows continuous updates without search interruption.

📞 Support Copy Chapter

For questions or issues:

1. Development: Check test failures and logs
2. Staging Issues: Review TeamCity build logs and state files
3. Production Issues: Check monitoring logs and consider manual override
4. Search Quality: Run parity testing scripts for analysis

🎯 Success Metrics Copy Chapter

• ✅ 100% test pass rate
• ✅ 96%+ production parity
• ✅ 55% index size reduction
• ✅ 3x faster incremental updates
• ✅ Zero git commits from state management
• ✅ Full TeamCity integration ready

File: src/current/.htmltest.yml Copy Chapter

DirectoryPath: "_site"
ExternalTimeout: 30
IgnoreDirs:

• ^docs/stable
• ^docs/dev
• ^docs/v1.0
• ^docs/v1.1
• ^docs/v1.2
• ^docs/v2.0
• ^docs/v2.1
• ^docs/v19.1
• ^docs/v19.2
• ^docs/v20.1
• ^docs/v20.2
• ^docs/v21.1
  IgnoreURLs:
• "http://localhost:*"
• "http://roach-single/*"
• "https://roach-single/*"
• "https://github.com/*"
• "https://raw.github.com/*"
• "https://docs.github.com/*"
• "https://movr.cloud"
• "https://support.cockroachlabs.com/*"
• "https://www.php.net/*"
• "https://crates.io/*"
• "https://docs.pipenv.org/*"
• "https://arxiv.org/*"
• "https://fonts.googleapis.com/*"
• "https://fonts.gstatic.com/*"
• "https://typeorm.io/*"
• "https://www.googleadservices.com/*"
  IgnoreInternalEmptyHash: true
  TestFilesConcurrently: true
  DocumentConcurrencyLimit: 16

File: src/current/_data/alerts.yml Copy Chapter

tip: ' **Tip: **'
note: ' **Note: **'
important: ' **Important: **'
warning: ' **Warning: **'
version: ''
end: ''

callout_danger: 'Warning:'
callout_success: 'Tip:'
callout_info: 'Note:'
callout_version: ''

hr_faded: '

File: src/current/_data/cards.yml Copy Chapter

develop:

• link: "/cockroachcloud/quickstart.html"
  title: "Create a new cluster"
  text: "Create and connect to a new CockroachDB cluster."
• link: "/PREFIX/install-client-drivers.html"
  title: "Install drivers"
  text: "Install client drivers for your application."
• link: "/PREFIX/connect-to-the-database.html"
  title: "Connect to a cluster"
  text: "Get details on how to connect to a CockroachDB cluster using your favorite language and framework."
• link: "/PREFIX/developer-basics.html"
  title: "Developer basics"
  text: "A quick overview of key concepts developers need to know about CockroachDB."
  text: "Submit SQL queries to retrieve data from your cluster."
• link: "/PREFIX/schema-design-overview.html"
  title: "Design a schema"
  text: "Details and best practices about designing schemas for your data."
• link: "/PREFIX/insert.html"
  title: "Write data"
  text: "How to insert data into your cluster."
• link: "/PREFIX/query-behavior-troubleshooting.html"
  title: "Troubleshoot your application"
  text: "Handle errors and solve problems with your application."
• link: '/PREFIX/make-queries-fast.html'
  title: "Optimize performance"
  text: "How to make your queries run as fast as possible."

File: src/current/_data/constants.yml Copy Chapter

cockroach_range_lease_duration: 6s
cockroach_range_lease_acquisition_timeout: 4s

cockroach_network_timeout: 2s
cockroach_network_connection_timeout: 4s

cockroach_network_client_ping_interval: 1s
cockroach_network_client_ping_timeout: 6s

cockroach_raft_election_timeout_ticks: 4
cockroach_raft_reproposal_timeout_ticks: 6

cockroach_raft_tick_interval: 500ms

File: src/current/_data/menus.yml Copy Chapter

---

serverless:

- identifier: product

name: Product

url: https://www.cockroachlabs.com/product/

weight: 100

params:

image: /images/menu-product.png

text: A distributed SQL datatabase designed for speed, scale,and survival

product_caps:

# Left

- identifier: product-capabilities

name: Elastic Scale

url: https://www.cockroachlabs.com/product/scale/

weight: 100

- name: Cloud-Native & Kubernetes

url: https://www.cockroachlabs.com/product/kubernetes/

- name: Built-in Survivability

url: https://www.cockroachlabs.com/product/resilience/

# Right

- name: Familiar, Consistent SQL

url: https://www.cockroachlabs.com/product/sql/

- name: Global Data

url: https://www.cockroachlabs.com/product/geo-partitioning/

solutions:

- identifier: solutions

name: Solutions

url: https://www.cockroachlabs.com/solutions/

weight: 110

params:

# image: /img/menu-product.png

text: See how our customers use CockroachDB to handle their critical workloads.

solutions_industries:

- name: Finance

url: https://www.cockroachlabs.com/solutions/verticals/financialservices/

weight: 100

- name: Gaming

url: https://www.cockroachlabs.com/solutions/verticals/gaming/

weight: 100

- name: Manufacturing & Logistics

url: https://resources.cockroachlabs.com/manufacturing-logistics

weight: 100

- name: Media & Streaming

url: https://www.cockroachlabs.com/solutions/verticals/media/

- name: Real-Money Gaming

url: https://www.cockroachlabs.com/solutions/verticals/gambling/

weight: 100

- name: Retail & eCommerce

url: https://www.cockroachlabs.com/solutions/verticals/retail-ecommerce/

weight: 100

- name: SaaS

url: https://www.cockroachlabs.com/solutions/verticals/saas

weight: 100

- name: Startups

url: https://resources.cockroachlabs.com/startups

weight: 100

solutions_usecase:

- name: Cloud-Native & Kubernetes

url: https://resources.cockroachlabs.com/cloud-native-kubernetes

weight: 600

- name: Scale & Resilience

url: https://resources.cockroachlabs.com/scale-resilience

weight: 700

- name: Data Privacy & Security

url: https://resources.cockroachlabs.com/privacy-compliance

weight: 800

- name: Distributed Apps

url: https://resources.cockroachlabs.com/distributed-apps

weight: 900

resources:

- identifier: resources

name: Resources

url: https://www.cockroachlabs.com/resources/

weight: 120

params:

# image: /img/menu-product.png

text: "

Cockroach University

resources_learn:

- name: Resource center

url: https://www.cockroachlabs.com/resources/

weight: 100

- name: Blog

url: https://www.cockroachlabs.com/blog/

weight: 200

- name: Developers

url: https://www.cockroachlabs.com/developers/

weight: 200

- name: Webinars

url: https://www.cockroachlabs.com/community/webinars/

weight: 200

- name: Podcast

url: https://www.cockroachlabs.com/big-ideas-podcast/

weight: 200

resources_support:

- name: Slack

url: https://www.cockroachlabs.com/join-community/

- name: Support Portal

url: https://support.cockroachlabs.com/hc/en-us?__hstc=181257784.2bc4222d759d3d555572287e7b610f03.1579111962927.1604502276741.1604544514798.361&__hssc=181257784.63.1604544514798&__hsfp=407609322

docs:

- identifier: docs

name: Docs Hub

url: https://www.cockroachlabs.com/docs/

weight: 120

params:

# image: /img/menu-product.png

text: "

Docs Hub

docs_items:

- name: Quickstart

url: https://www.cockroachlabs.com/docs/cockroachcloud/quickstart.html

weight: 100

- name: FAQ

url: https://www.cockroachlabs.com/docs/stable/frequently-asked-questions.html

weight: 200

- name: Example applications

url: https://www.cockroachlabs.com/docs/stable/example-apps.html

weight: 300

- name: Architecture Overview

url: https://www.cockroachlabs.com/docs/stable/architecture/overview.html

weight: 400

company:

- identifier: company

name: Company

url: https://www.cockroachlabs.com/company/

weight: 110

params:

# image: /img/menu-product.png

text: CockroachDB is trusted by innovators around the world, big and small. Take a look at how they use CockroachDB to build future-proofed applications.

company_items:

- name: Company News & Culture

url: https://www.cockroachlabs.com/blog/culture/

- name: Our Story

url: https://www.cockroachlabs.com/about/

- name: Partners

url: https://www.cockroachlabs.com/partners/

- name: Work at Cockroach Labs

url: https://www.cockroachlabs.com/careers/

# End New Serverless Nav

main_right:

- identifier: contact

pre: ""

name: Contact Us

url: https://www.cockroachlabs.com/contact/

weight: 100

- identifier: sign_in

pre: ""

name: Sign In

url: https://cockroachlabs.cloud/

weight: 110

- identifier: get_started

pre: ""

name: Get CockroachDB

url: https://www.cockroachlabs.com/get-started-cockroachdb/

weight: 120

blog_sub:

- identifier: blog

pre: ""

name: Blog

url: https://www.cockroachlabs.com/blog/

weight: -100

- identifier: culture

pre: ""

name: Company + Culture

url: https://www.cockroachlabs.com/blog/culture/

weight: -100

- identifier: engineering

pre: ""

name: Engineering

url: https://www.cockroachlabs.com/blog/engineering/

weight: -100

- identifier: product

pre: ""

name: Product

url: https://www.cockroachlabs.com/blog/product/

weight: -100

- identifier: customer-stories

pre: ""

name: Customer Stories

url: https://www.cockroachlabs.com/blog/customer-stories/

weight: -100

careers_sub:

- identifier: careers

pre: ""

name: Careers

url: https://www.cockroachlabs.com/careers/

weight: -100

- identifier: open-positions

pre: ""

name: Open Positions

url: https://www.cockroachlabs.com/careers/open-positions/

weight: -100

- identifier: meet-the-team

pre: ""

name: Meet The Team

url: https://www.cockroachlabs.com/careers/meet-the-team/

weight: -100

solutions_sub:

- identifier: solutions

pre: ""

name: Solutions

url: https://www.cockroachlabs.com/solutions/

weight: -200

- identifier: initiatives

pre: ""

name: Initiatives

url: https://www.cockroachlabs.com/solutions/initiatives/

weight: -100

- identifier: use-cases

pre: ""

name: Use Cases

url: https://www.cockroachlabs.com/solutions/use-cases/

weight: -100

- identifier: verticals

pre: ""

name: Verticals

url: https://www.cockroachlabs.com/solutions/Verticals/

weight: -100

File: src/current/_data/menuwhy.yml Copy Chapter

• identifier: familiar_sql
  pre: "Build fast & build to last"
  name: Familiar SQL
  url: /product/sql/
  weight: 100
• identifier: elastic_sql
  pre: "Elastic Scale"
  name: Grow locally and/or globally
  url: /product/scale/
  weight: 110

File: src/current/_data/products.yml Copy Chapter

serverless: Serverless

dedicated: Dedicated

dedicated-advanced: Dedicated advanced

core: self-hosted

enterprise: Enterprise

cloud: Cloud

basic: Basic

standard: Standard

advanced: Advanced

public-operator: Public operator

cockroachdb-operator: CockroachDB operator

File: src/current/_data/redirects.yml Copy Chapter

############################################################

How to use this file:

Add a new block like this in alphabetical order based on its category:

Here’s the sample syntax of the file:

- destination: new-file-name-with-md-extension.md#optional-anchor

sources:

- old-file-name-with-md-extension.md

- other-old-file-name.md

temporary: true|false # (optional, default = false

force: true|false # optional, default = false

versions: ['v22.1', 'v22.2'] # optional

- destination is the final page where each source should land.

Each destination must have the .md file extension.

- sources is an array of pages you wish to route to the

destination page. Even if you only have one source, it must use

YML’s array syntax (full spec here: https://yaml.org/).

Each source must have the .md extension.

- temporary is an optional boolean field that dictates whether

you return a 301 (false, default) or a 302 (true).

- force is an optional boolean field that dictates whether a

force redirect should occur. This is equivalent to adding an

exclamation point (!) to the end of the status code. docs:

https://docs.netlify.com/routing/redirects/redirect-options/#force-redirects

- versions is an optional array of strings containing the

versions to which a redirect should apply. If there is an item

in the list of versions that matches a major version in

versions.csv, Jekyll will automatically add a redirect

for the dev and stable aliases for that page. versions.csv:

https://github.com/cockroachlabs/docs/blob/main/src/current/_data/versions.csv

Each redirect added in redirects.yml generates a redirect

for the page without the .md extension and a redirect for

the page with the .md extension. This helps with making

sure inlinks to our docs don’t 404, which hurts our SEO.

If using versions, redirects will generate as follows:

# for each version in versions:

// //

// //

# if a version exists in versions.csv:

/dev/ /dev/

/dev/ /dev/

/stable/ /stable/

/stable/ /stable/

Our is /docs.

If not using versions, this is how redirects will generate:

/ /

/ /

No dev or stable redirects are added automatically if not using

the versions field. Note that you must manually specify the full

path after .

Using :version as a placeholder includes any string of text between

the forward slashes, including dev, stable, v21.2, and gobbledygook.

You can also name your placeholder anything you like, including

:gobbledygook.

versions, sources, and destination all support the use of

placeholders. Docs here:

https://docs.netlify.com/routing/redirects/redirect-options/#placeholders

sources and destination support splats (* in the source,

:splat in the destination). Docs here:

https://docs.netlify.com/routing/redirects/redirect-options/#splats

############################################################

• destination: advisories/index.md
  sources: ['advisories/advisories.md']

Renamed pages

• destination: admin-ui-overview.md
  sources: ['explore-the-admin-ui.md']
  versions: ['v1.1', 'v2.0', 'v2.1', 'v19.1', 'v20.1']

• destination: architecture/distribution-layer.md#range-merges
  sources: ['range-merges.md']
  versions: ['v21.1']

• destination: architecture/overview.md
  sources: ['architecture/index.md']
  versions: ['v1.1', 'v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: authorization.md
  sources: ['create-and-manage-users.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: authorization.md
  sources: ['roles.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: backup-and-restore.md
  sources:

  • backup-data.md
  • restore-data.md
    versions: ['v2.1', 'v19.1', 'v20.1']

• destination: cdc-queries.md
  sources: ['cdc-transformations.md']
  versions: ['v23.1']

• destination: change-data-capture-overview.md
  sources: ['change-data-capture.md']
  versions: ['v21.2']

• destination: cloud-org-sso.md
  sources: ['cloud-sso.md']
  versions: ['cockroachcloud']

• destination: cockroach-cert.md
  sources: ['create-security-certificates.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-debug-ballast.md
  sources: ['debug-ballast.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-debug-encryption-active-key.md
  sources: ['debug-encryption-active-key.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-debug-merge-logs.md
  sources: ['debug-merge-logs.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-debug-zip.md
  sources: ['debug-zip.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-dump.md
  sources: ['sql-dump.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-gen.md
  sources: ['generate-cockroachdb-resources.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-init.md
  sources: ['initialize-a-cluster.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-node.md
  sources: ['view-node-details.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-quit.md
  sources: ['stop-a-node.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-sql.md
  sources: ['use-the-built-in-sql-client.md']
  versions: ['v20.1', 'v20.2', 'v21.1', 'v21.2', 'v21.2', 'v22.2', 'v23.1', 'v23.2']

• destination: cockroach-sqlfmt.md
  sources: ['use-the-query-formatter.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-start.md
  sources: ['start-a-node.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroach-version.md
  sources: ['view-version-details.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: cockroachdb-feature-availability.md
  sources:

  • experimental-features.md
  • features-in-preview.md
    versions: ['v22.1', 'v22.2', 'v23.1']

• destination: common-errors.md
  sources: ['general-troubleshooting.md']
  versions: [':version']

• destination: connect-to-a-serverless-cluster.md
  sources: ['connect-to-a-free-cluster.md']
  versions: ['cockroachcloud']

• destination: copy.md
  sources: ['copy-from.md']
  versions: ['v23.1', 'v23.2', 'v24.1', 'v24.2', 'v24.3', 'v25.1']

• destination: cost-based-optimizer.md
  sources: ['sql-optimizer.md']
  versions: [':version']

• destination: create-a-serverless-cluster.md
  sources: ['create-a-free-cluster.md']
  versions: ['cockroachcloud']

• destination: demo-cockroachdb-resilience.md
  sources: ['demo-fault-tolerance-and-recovery.md']
  versions: ['v24.2', 'v24.3']

• destination: demo-low-latency-multi-region-deployment.md
  sources: ['demo-geo-partitioning.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: demo-replication-and-rebalancing.md
  sources:

  • demo-automatic-rebalancing.md
  • demo-data-replication.md
    versions: ['v20.1', 'v20.2', 'v21.1']

• destination: v23.2/disaster-recovery-planning.md
  sources: ['v23.2/disaster-recovery.md']

• destination: dev/disaster-recovery-planning.md
  sources: ['dev/disaster-recovery.md']

• destination: example-apps.md
  sources: ['build-an-app-with-cockroachdb.md']
  versions: ['v21.2']

• destination: example-apps.md
  sources: ['tutorials-overview.md']
  versions: ['v23.1']

• destination: example-apps.md#python
  sources: ['build-a-python-app-with-cockroachdb-pony.md']
  versions: ['v20.2', 'v21.1', 'v21.2', 'v22.1', 'v22.2', 'v23.1']

• destination: dev/failover-replication.md
  sources: ['cutover-replication.md']
  versions: ['24.3', '24.1']

• destination: failover-replication.md
  sources: ['cutover-replication.md']
  versions: ['24.3', '24.1']

• destination: fips.md
  sources: ['fips-compliance.md']
  versions: ['v23.1']

• destination: global-tables.md
  sources: ['topology-duplicate-indexes.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2', 'v23.1']

• destination: grant.md
  sources: ['grant-roles.md']
  versions: ['v21.1']

• destination: how-does-a-changefeed-work.md
  sources: ['how-does-an-enterprise-changefeed-work.md']
  versions: ['v25.2', 'v25.1', 'v24.3']

• destination: kubernetes-overview.md
  sources: ['operate-cockroachdb-kubernetes.md']
  versions: ['v21.2']

• destination: log-sql-activity-to-datadog.md
  sources: ['log-sql-statistics-to-datadog.md']
  versions: ['v23.1', 'v23.2', 'v24.1', 'v24.2', 'v24.3', 'v25.1']

• destination: logging-overview.md
  sources: ['debug-and-error-logs.md']
  versions: ['v21.1']

• destination: managing-access.md
  sources:

  • console-access-management.md
  • user-authorization.md
    versions: ['cockroachcloud']

• destination: manual-deployment.md
  sources: ['cloud-deployment.md']
  versions: ['v1.1', 'v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: plan-your-cluster-serverless.md
  sources:

  • 'planning-your-serverless-cluster.md'
  • 'learn-about-pricing.md'
  • 'learn-about-request-units.md'
    versions: ['cockroachcloud']

• destination: provision-a-cluster-with-terraform.md
  sources:

  • 'migrate-from-free-to-dedicated.md'
  • 'migrate-from-serverless-to-dedicated.md'
    versions: ['cockroachcloud']

• destination: molt/migrate-data-load-and-replication.md?filters=oracle
  sources: [':version/migrate-from-oracle.md']

• destination: molt/migrate-data-load-and-replication.md?filters=mysql
  sources: [':version/migrate-from-mysql.md']

• destination: molt/migrate-data-load-and-replication.md
  sources: [':version/migrate-from-postgres.md']

• destination: molt/migrate-load-replicate.md
  sources: ['molt/migrate-data-load-replicate-only.md']

• destination: molt/migrate-resume-replication.md
  sources: ['molt/migrate-replicate-only.md']

• destination: molt/migration-overview.md
  sources: [':version/migration-overview.md']

• destination: molt/migration-overview.md
  sources: ['molt/molt-overview.md']

• destination: molt/migration-overview.md
  sources: ['import-data.md']
  versions: ['v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: molt/migration-overview.md
  sources:

  • molt/live-migration-service.md
  • :version/live-migration-service.md

• destination: molt/molt-fetch.md
  sources: [':version/molt-fetch.md']

• destination: molt/molt-verify.md
  sources: [':version/molt-verify.md']

• destination: node-shutdown.md
  sources: ['cockroach-quit.md']
  versions: ['v21.2']

• destination: node-shutdown.md?filters=decommission
  sources: ['remove-nodes.md']
  versions: ['v21.2']

• destination: orchestrate-cockroachdb-with-kubernetes-multi-cluster.md
  sources: ['orchetrate-cockroachdb-with-kubernetes-multi-region.md']
  versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: performance-benchmarking-with-tpc-c-1k-warehouses.md
  sources: ['performance-benchmarking-with-tpc-c.md']
  versions: ['v20.1']

• destination: performance-benchmarking-with-tpcc-large.md
  sources: ['performance-benchmarking-with-tpc-c-100k-warehouses.md']
  versions: ['v20.2', 'v21.1']

• destination: performance-benchmarking-with-tpcc-local.md
  sources: ['performance-benchmarking-with-tpc-c-10-warehouses.md']
  versions: ['v20.2', 'v21.1']

• destination: performance-benchmarking-with-tpcc-medium.md
  sources: ['performance-benchmarking-with-tpc-c-10k-warehouses.md']
  versions: ['v20.2', 'v21.1']

• destination: performance-benchmarking-with-tpcc-small.md
  sources: ['performance-benchmarking-with-tpc-c-1k-warehouses.md']
  versions: ['v20.2', 'v21.1']

• destination: postgresql-compatibility.md
  sources: ['porting-postgres.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: regional-tables.md
  sources:

  • topology-geo-partitioned-leaseholders.md
  • topology-geo-partitioned-replicas.md
    versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2', 'v23.1']

• destination: revoke.md
  sources: ['revoke-roles.md']
  versions: ['v21.1']

• destination: scalar-expressions.md
  sources: ['sql-expressions.md']
  versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: select-clause.md
  sources: ['select.md']
  versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: selection-queries.md
  sources: ['selection-clauses.md']
  versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: serverless-faqs.md
  sources: ['free-faqs.md']
  versions: ['cockroachcloud']

• destination: set-vars.md
  sources:

  • set-application-name.md
  • set-database.md
  • set-time-zone.md
    versions: [':version']

• destination: show-create.md
  sources:

  • show-create-sequence.md
  • show-create-table.md
  • show-create-view.md
    versions: ['v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: show-experimental-ranges.md
  sources: ['show-testing-ranges.md']
  versions: ['v2.0', 'v2.1', 'v19.1']

• destination: show-ranges.md
  sources: ['show-experimental-ranges.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: show-statements.md
  sources: ['show-queries.md']
  versions: ['v21.1']

• destination: show-vars.md
  sources:

  • show-all.md
  • show-time-zone.md
  • show-transaction.md
    versions: [':version']

• destination: stable/build-a-python-app-with-cockroachdb-psycopg3
  sources:

  • v20.1/build-a-python-app-with-cockroachdb-pony.md

• destination: stable/install-client-drivers.md
  sources: ['install-client-drivers.md']

• destination: stable/licensing-faqs.md
  sources: [':version/licensing.md']

• destination: start-a-local-cluster-in-docker-mac.md
  sources: ['start-a-local-cluster-in-docker.md']
  versions: ['v20.1', 'v20.2', 'v21.1']

• destination: stream-data-out-of-cockroachdb-using-changefeeds.md
  sources: ['change-data-capture.md']
  versions: ['v20.2', 'v21.1']

• destination: take-and-restore-self-managed-backups.md
  sources: ['run-bulk-operations.md', 'take-and-restore-customer-owned-backups.md']
  versions: ['cockroachcloud']

• destination: take-full-and-incremental-backups.md
  sources:

  • back-up-data.md
  • backup-and-restore-advanced-options.md
  • backup-and-restore.md
  • restore-data.md
    versions: ['v20.2', 'v21.1']

• destination: tools-page.md
  sources: ['monitoring-page.md']
  versions: ['cockroachcloud']

• destination: topology-patterns.md
  sources: ['cluster-topology-patterns.md']
  versions: ['v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: ui-cdc-dashboard.md
  sources: ['admin-ui-cdc-dashboard.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-cluster-overview-page.md
  sources: ['admin-ui-cluster-overview-page.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-custom-chart-debug-page.md
  sources: ['admin-ui-custom-chart-debug-page.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-databases-page.md
  sources: ['admin-ui-databases-page.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-debug-pages.md
  sources: ['admin-ui-debug-pages.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-hardware-dashboard.md
  sources: ['admin-ui-hardware-dashboard.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-jobs-page.md
  sources: ['admin-ui-jobs-page.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-network-latency-page.md
  sources: ['admin-ui-network-latency-page.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-overview-dashboard.md
  sources: ['admin-ui-overview-dashboard.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-overview.md
  sources:

  • admin-ui-access-and-navigate.md
  • admin-ui-overview.md
  • explore-the-admin-ui.md
    versions: ['v20.2', 'v21.1']

• destination: ui-replication-dashboard.md
  sources: ['admin-ui-replication-dashboard.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-runtime-dashboard.md
  sources: ['admin-ui-runtime-dashboard.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-sessions-page.md
  sources: ['admin-ui-sessions-page.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-sql-dashboard.md
  sources: ['admin-ui-sql-dashboard.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-statements-page.md
  sources: ['admin-ui-statements-page.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-storage-dashboard.md
  sources: ['admin-ui-storage-dashboard.md']
  versions: ['v20.2', 'v21.1']

• destination: ui-top-ranges-page.md
  sources: ['ui-hot-ranges-page.md']
  versions: ['v25.4']

• destination: use-a-local-file-server-for-bulk-operations.md
  sources: ['create-a-file-server.md']
  versions: ['v20.2', 'v21.1']

• destination: use-a-local-file-server.md
  sources: ['use-a-local-file-server-for-bulk-operations.md']
  versions: ['v22.2', 'v23.1']

• destination: use-cloud-storage.md
  sources: ['use-cloud-storage-for-bulk-operations.md']
  versions: ['v22.2', 'v23.1']

• destination: managed-backups.md
  sources: ['backups-page.md', 'use-managed-service-backups.md']
  versions: ['cockroachcloud']

• destination: use-userfile-storage.md
  sources: ['use-userfile-for-bulk-operations.md']
  versions: ['v22.2', 'v23.1']

Removed Pages

• destination: ../releases/v25.4.md#known-limitations
  sources: ['known-limitations.md']
  versions: ['v25.4']

• destination: licensing-faqs.md
  sources: ['enterprise-licensing.md']
  versions: ['v23.1', 'v23.2', 'v24.1', 'v24.2', 'v24.3']

• destination: :version/licensing-faqs.md
  sources: [':version/get-started-with-enterprise-trial.md']

• destination: movr.md#develop-and-deploy-a-global-application
  sources: ['movr-flask-overview.md']
  versions: ['v23.1']

• destination: :version/collate.md
  sources: [':version/collatedstring.md']

• destination: :version/sql-feature-support.md
  sources: [':version/detailed-sql-support.md']

• destination: admission-control.md
  sources: ['architecture/admission-control.md']
  versions: ['v22.1']

• destination: alter-database.md
  sources: ['convert-to-schema.md']
  versions: ['v22.1']

• destination: alter-database.md#add-region
  sources: ['add-region.md']
  versions: ['v22.2']

• destination: alter-database.md#add-super-region
  sources: ['add-super-region.md']
  versions: ['v22.2']

• destination: alter-database.md#alter-locality
  sources: ['alter-locality.md']
  versions: ['v22.2']

• destination: alter-database.md#alter-super-region
  sources: ['alter-super-region.md']
  versions: ['v22.2']

• destination: alter-database.md#drop-region
  sources: ['drop-region.md']
  versions: ['v22.2']

• destination: alter-database.md#drop-secondary-region
  sources: ['drop-secondary-region.md']
  versions: ['v22.2']

• destination: alter-database.md#drop-super-region
  sources: ['drop-super-region.md']
  versions: ['v22.2']

• destination: alter-database.md#placement
  sources: ['placement-restricted.md']
  versions: ['v22.2']

• destination: alter-database.md#rename-to
  sources: ['rename-database.md']
  versions: ['v22.2']

• destination: alter-database.md#set-primary-region
  sources: ['set-primary-region.md']
  versions: ['v22.2']

• destination: alter-database.md#set-secondary-region
  sources: ['set-secondary-region.md']
  versions: ['v22.2']

• destination: alter-database.md#survive-zone-region-failure
  sources: ['survive-failure.md']
  versions: ['v22.2']

• destination: alter-index.md#rename-to
  sources: ['rename-index.md']
  versions: ['v22.2']

• destination: alter-range.md#relocate
  sources: ['alter-range-relocate.md']
  versions: ['v22.2']

• destination: alter-sequence.md
  sources: ['rename-sequence.md']
  versions: ['v21.1']

• destination: alter-table.md#add-column
  sources: ['add-column.md']
  versions: ['v22.2']

• destination: alter-table.md#add-constraint
  sources: ['add-constraint.md']
  versions: ['v22.2']

• destination: alter-table.md#alter-column
  sources: ['alter-column.md']
  versions: ['v22.2']

• destination: alter-table.md#alter-primary-key
  sources: ['alter-primary-key.md']
  versions: ['v22.2']

• destination: alter-table.md#drop-column
  sources: ['drop-column.md']
  versions: ['v22.2']

• destination: alter-table.md#drop-constraint
  sources: ['drop-constraint.md']
  versions: ['v22.2']

• destination: alter-table.md#experimental_audit
  sources: ['experimental-audit.md']
  versions: ['v22.2']

• destination: alter-table.md#owner-to
  sources: ['owner-to.md']
  versions: ['v22.2']

• destination: alter-table.md#rename-column
  sources: ['rename-column.md']
  versions: ['v22.2']

• destination: alter-table.md#rename-constraint
  sources: ['rename-constraint.md']
  versions: ['v22.2']

• destination: alter-table.md#rename-to
  sources: ['rename-table.md']
  versions: ['v22.2']

• destination: alter-table.md#reset-storage-parameter
  sources: ['reset-storage-parameter.md']
  versions: ['v22.2']

• destination: alter-table.md#set-locality
  sources: ['set-locality.md']
  versions: ['v22.2']

• destination: alter-table.md#set-storage-parameter
  sources: ['set-storage-parameter.md']
  versions: ['v22.2']

• destination: alter-table.md#split-at
  sources: ['split-at.md']
  versions: ['v22.2']

• destination: alter-table.md#unsplit-at
  sources: ['unsplit-at.md']
  versions: ['v22.2']

• destination: alter-table.md#validate-constraint
  sources: ['validate-constraint.md']
  versions: ['v22.2']

• destination: architecture/glossary.md
  sources: ['spatial-glossary.md']
  versions: ['v23.1']

• destination: change-data-capture-overview.md
  sources: ['stream-data-out-of-cockroachdb-using-changefeeds.md']
  versions: ['v21.2', 'v22.1', 'v22.2', 'v23.1']

• destination: changefeed-messages.md
  sources: ['use-changefeeds.md']
  versions: ['v22.1']

• destination: cockroachcloud/cmek.md#faq
  sources: ['cockroachcloud/cmek-faq.md']

• destination: cockroachcloud/managing-cmek.md
  sources: ['cockroachcloud/cmek-ops-*.md']

• destination: cockroachcloud/connect-to-your-cluster.md
  sources: ['cockroachcloud/stable/cockroachcloud-connect-to-your-cluster.md']

• destination: cockroachcloud/create-your-cluster.md
  sources: ['cockroachcloud/stable/cockroachcloud-create-your-cluster.md']

• destination: cockroachcloud/quickstart.md
  sources:

  • :version/deploy-a-test-cluster.md
  • :version/hello-world-go-gorm.md
  • :version/hello-world-go-pgx.md
  • :version/hello-world-java-jdbc.md
  • :version/hello-world-node-postgres.md
  • :version/hello-world-python-sqlalchemy.md

• destination: cockroachcloud/serverless-resource-usage.md
  sources: ['cockroachcloud/serverless-benchmarking.md']

• destination: upgrade-cockroach-version.md
  sources: 'upgrade-to-v*.md'
  versions: ['cockroachcloud']

• destination: community-tooling.md
  sources:

  • build-a-c++-app-with-cockroachdb.md
  • build-a-clojure-app-with-cockroachdb.md
  • build-a-php-app-with-cockroachdb.md
    versions: ['v20.2', 'v21.1', 'v21.2']

• destination: configure-replication-zones.md
  sources: ['configure-zone.md']
  versions: ['v22.2']

• destination: create-schema.md
  sources: ['convert-to-schema.md']
  versions: ['v22.1']

• destination: example-apps.md
  sources: ['hello-world-example-apps.md']
  versions: ['v20.2', 'v21.1', 'v21.2', 'v22.1', 'cockroachcloud']

• destination: frequently-asked-questions.md
  sources:

  • automated-scaling-and-repair.md
  • distributed-transactions.md
  • go-implementation.md
  • high-availability.md
  • open-source.md
  • simplified-deployment.md
  • sql.md
  • strong-consistency.md
    versions: ['v19.1', 'v20.1', 'v20.2', 'v21.1']

• destination: https://docs.peewee-orm.com/en/latest/peewee/playhouse.html
  sources: [':version/build-a-python-app-with-cockroachdb-peewee.md']

• destination: https://wiki.crdb.io/wiki/spaces/CRDB/pages/73204033/Contributing+to+CockroachDB
  sources: [':version/contribute-to-cockroachdb.md']
  force: true

• destination: make-queries-fast.md
  sources: ['performance-tuning.md']
  versions: ['v21.1']

• destination: make-queries-fast.md
  sources: ['performance-features-overview.md']
  versions: ['v23.1']

• destination: movr.md#develop-and-deploy-a-global-application
  sources: ['movr-flask-overview.md']
  versions: ['v23.1']

• destination: multiregion-survival-goals.md
  sources: ['when-to-use-zone-vs-region-survival-goals.md']
  versions: ['v23.1']

• destination: partitioning.md
  sources: ['partition-by.md']
  versions: ['v22.2']

• destination: query-behavior-troubleshooting.md
  sources: ['error-handling-and-troubleshooting.md']
  versions: ['v23.1']

• destination: query-spatial-data.md
  sources: ['spatial-data.md']
  versions: ['v23.1']

• destination: schema-design-update.md
  sources: ['set-schema.md']
  versions: ['v22.2']

• destination: show-create.md
  sources: ['cockroach-dump.md']
  versions: ['v21.2', 'v22.1']

• destination: spatial-data-overview.md
  sources: ['spatial-features.md']
  versions: ['v23.1']

• destination: stable/build-a-python-app-with-cockroachdb.md
  sources: ['tutorials/build-a-python-app-with-cockroachdb-interactive.md']

• destination: stable/cockroach-sql.md
  sources: ['use-the-built-in-sql-client.md']

• destination: stable/column-families.md
  sources: ['column-families.md']

• destination: stable/configure-replication-zones.md
  sources: ['configure-replication-zones.md']

• destination: stable/frequently-asked-questions.md
  sources:

  • automated-scaling-and-repair.md
  • frequently-asked-questions.md
  • sql.md

• destination: stable/kubernetes-overview.md
  sources:

  • v21.1/orchestrate-cockroachdb-with-docker-swarm.md
  • v21.2/orchestrate-cockroachdb-with-docker-swarm.md
  • v22.1/orchestrate-cockroachdb-with-docker-swarm.md
  • dev/orchestrate-cockroachdb-with-docker-swarm.md
  • orchestrate-cockroachdb-with-docker-swarm.md
  • stable/orchestrate-cockroachdb-with-docker-swarm.md
  • :version/orchestrate-cockroachdb-with-mesosphere-insecure.md

• destination: stable/performance-recipes.md
  sources: ['performance-recipes.md']

• destination: stable/show-vars.md
  sources: ['show-database.md']

• destination: stable/start-a-local-cluster.md
  sources: ['start-a-local-cluster.md']

• destination: table-localities.md
  sources: ['when-to-use-regional-vs-global-tables.md']
  versions: ['v23.1']

• destination: topology-follow-the-workload.md
  sources: ['demo-follow-the-workload.md']
  versions: ['v20.1', 'v20.2']

• destination: tutorials/sql-playground.md
  sources:

  • :version/sql-playground.md
  • sql-playground.md

• destination: v21.1/interleave-in-parent.md#deprecation
  sources:

  • dev/interleave-in-parent.md
  • interleave-in-parent.md
  • stable/interleave-in-parent.md

Cloud 2.0 updates (Serverless/Dedicated to Basic/Standard/Advanced)

• destination: cockroachcloud/cockroachdb-advanced-on-azure.md
  sources: ['cockroachcloud/cockroachdb-dedicated-on-azure.md']

• destination: cockroachcloud/create-a-basic-cluster.md
  sources: ['cockroachcloud/create-a-serverless-cluster.md']
  versions: ['cockroachcloud']

• destination: cockroachcloud/basic-cluster-management.md
  sources: ['cockroachcloud/serverless-cluster-management.md']
  versions: ['cockroachcloud']

• destination: cockroachcloud/advanced-cluster-management.md
  sources: ['cockroachcloud/cluster-management-advanced.md']
  versions: ['cockroachcloud']

• destination: cockroachcloud/connect-to-a-basic-cluster.md
  sources: ['cockroachcloud/connect-to-a-serverless-cluster.md']

• destination: cockroachcloud/resource-usage.md
  sources: ['cockroachcloud/serverless-resource-usage.md']

• destination: plan-your-cluster-basic.md
  sources:

  • 'plan-your-cluster-serverless.md'
  • 'planning-your-serverless-cluster.md'
  • 'learn-about-pricing.md'
  • 'learn-about-request-units.md'
    versions: ['cockroachcloud']

• destination: index.md
  sources:

  • 'serverless-faqs.md'
  • 'choose-a-deployment-option.md'

Cloud releases

• destination: releases/cloud.md#january-22-2021
  sources: ['releases/cockroachcloud-01222021.md']

• destination: releases/cloud.md#january-10-2022
  sources: ['releases/cockroachcloud-01102022.md']

• destination: releases/cloud.md#february-09-2021
  sources: ['releases/cockroachcloud-02092021.md']

• destination: releases/cloud.md#february-02-2020
  sources: ['releases/cockroachcloud-03022020.md']

• destination: releases/cloud.md#march-08-2021
  sources: ['releases/cockroachcloud-03082021.md']

• destination: releases/cloud.md#april-05-2021
  sources: ['releases/cockroachcloud-04052021.md']

• destination: releases/cloud.md#april-06-2020
  sources: ['releases/cockroachcloud-04062020.md']

• destination: releases/cloud.md#may-03-2021
  sources: ['releases/cockroachcloud-05032021.md']

• destination: releases/cloud.md#may-04-2020
  sources: ['releases/cockroachcloud-05042020.md']

• destination: releases/cloud.md#june-07-2021
  sources: ['releases/cockroachcloud-06072021.md']

• destination: releases/cloud.md#june-11-2020
  sources: ['releases/cockroachcloud-06112020.md']

• destination: releases/cloud.md#july-06-2021
  sources: ['releases/cockroachcloud-07062021.md']

• destination: releases/cloud.md#july-06-2020
  sources: ['releases/cockroachcloud-07062020.md']

• destination: releases/cloud.md#august-09-2021
  sources: ['releases/cockroachcloud-08092021.md']

• destination: releases/cloud.md#september-07-2021
  sources: ['releases/cockroachcloud-09072021.md']

• destination: releases/cloud.md#october-04-2021
  sources: ['releases/cockroachcloud-10042021.md']

• destination: releases/cloud.md#november-08-2021
  sources: ['releases/cockroachcloud-11082021.md']

• destination: releases/cloud.md#november-19-2020
  sources: ['releases/cockroachcloud-11192020.md']

• destination: releases/cloud.md#december-06-2021
  sources: ['releases/cockroachcloud-12062021.md']

• destination: releases/cloud.md#december-11-2020
  sources: ['releases/cockroachcloud-12112020.md']

• destination: releases/cloud.md
  sources: ['releases/index-cockroachcloud.md']

Redirects for Homebrew

• destination: stable/secure-a-cluster.md
  sources: ['secure-a-cluster.md']

Redirects for Dockerhub

• destination: stable/deploy-cockroachdb-with-kubernetes.md
  sources: ['orchestrate-cockroachdb-with-kubernetes.md']

• destination: stable/install-cockroachdb.md
  sources: ['install-cockroachdb.md']

• destination: stable/install-cockroachdb-mac
  sources: ['stable/install-cockroachdb/install-cockroachdb-mac']

• destination: stable/install-cockroachdb-windows
  sources: ['stable/install-cockroachdb/install-cockroachdb-windows']

• destination: stable/install-cockroachdb-linux
  sources: ['stable/install-cockroachdb/install-cockroachdb-linux']

• destination: stable/start-a-local-cluster-in-docker-linux.md
  sources: ['start-a-local-cluster-in-docker.md']

Redirects from jekyll-redirect-from gem

• destination: deploy-cockroachdb-with-kubernetes.md
  sources: ['orchestrate-cockroachdb-with-kubernetes.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: deploy-cockroachdb-with-kubernetes-insecure.md
  sources: ['orchestrate-cockroachdb-with-kubernetes-insecure.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: import-into.md
  sources:

  • import.md
  • cockroach-import.md
    versions: ['v24.1', 'v24.2']

• destination: kubernetes-overview.md
  sources: ['orchestration.md']
  versions: ['v21.1', 'v21.2', 'v22.1']

• destination: movr-flask-application.md
  sources: ['multi-region-application.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: movr-flask-database.md
  sources: ['multi-region-database.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: movr-flask-deployment.md
  sources: ['multi-region-deployment.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: movr-flask-overview.md
  sources: ['multi-region-overview.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: movr-flask-setup.md
  sources: ['multi-region-setup.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: movr-flask-use-case.md
  sources: ['multi-region-use-case.md']
  versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']

• destination: serverless-resource-usage.md
  sources: ['optimize-serverless-workload.md']
  versions: ['cockroachcloud']

• destination: https://www.cockroachlabs.com/compare/
  sources:

  • stable/cockroachdb-in-comparison.md
  • v23.1/cockroachdb-in-comparison.md
  • v23.2/cockroachdb-in-comparison.md
  • v24.1/cockroachdb-in-comparison.md
  • v24.2/cockroachdb-in-comparison.md
  • v24.3/cockroachdb-in-comparison.md
  • v25.1/cockroachdb-in-comparison.md