New Citus Technical README for distributed PostgreSQL

Written by Onder Kalaci
October 19, 2023

Want to dive right in? Check out this brand new Citus Technical README on our GitHub repo for the open source Citus database extension.

This README is a bit of a deep dive into the Citus concepts, the use cases and design principles, how Citus uses the PostgreSQL extension hooks to distribute Postgres, and more.

Who should check out this new Citus Technical Readme?

Wondering who this new Citus technical readme is aimed at? Well, it's designed to offer something valuable for everyone from Citus open source users to PostgreSQL extension developers. Let's break it down:

  • Citus developers and contributors: For those contributing to the Citus open source extension, this README is your guide. It doesn't just describe what we’ve built; the README explains why we built it that way. You'll learn about key design choices and the architecture, which should help you to contribute more effectively, be it fixing bugs or adding new features.

  • Citus users (and customers of Citus on Azure): If you use Citus—or are a customer of Citus on Azure, aka Azure Cosmos DB for PostgreSQL—and are wondering, "Is this technical document for me?" the answer is yes. Our README is not just a how-to guide; it explains the why behind each feature. Knowing the why helps you not just use Citus to distribute Postgres, but use it well. Understanding the why makes it easier to address your Postgres scalability and performance challenges with Citus.

  • PostgreSQL Extension Developers: This README is also useful if you're working on PostgreSQL extensions. It shows how Citus fits into the PostgreSQL extension framework—and can serve as a useful example for other extensions in the PG ecosystem.

Let us know what you think

If you find our new Citus technical README useful, or you're excited about what the Citus extension can do, don't hesitate to give the project a star on GitHub. Your support means a lot to our engineers and helps new users like you to discover Citus. I would also like to thank Marco Slot for his invaluable contributions to this README.

Your feedback on this README—and Citus more generally—is always welcome. You can file issues on our GitHub repo or ask questions on the Citus Slack.

That's it! We've rolled out our new technical readme and we're excited for you to take a look.

Visual overview of this technical README for Citus

Some of you are likely readers and others are more visual. For those who appreciate visuals, the diagram below gives you a sketch of all the topics covered in this new Citus technical README.

Figure 1: tech doc infogram
Figure 1: Visual overview of all the concepts and components covered in this Citus Technical README.

If you’re ready to kick the tires on Citus, you can find the Citus download instructions online—or use this quickstart to provision a Citus cluster on Azure. There's a useful getting started page too.

Onder Kalaci

Written by Onder Kalaci

Former principal software engineer on the Postgres team at Microsoft. Joined Citus Data to scale out Postgres. Thread level parallelism = perfect topic for dinner conversation.