pg_crdt documentation
pg_crdt adds conflict-free replicated data types (CRDTs) to Postgres, for values that several writers change independently and merge later. The extension is SQL and PL/pgSQL, runs on Postgres 16, 17 and 18, and works with any client, driver or API layer. Version 0.0.1 has two types: the PN-Counter, a counter that goes up and down, and collaborative text, a plain-text document that several people edit at once, in a column of your table (yseq_, experimental) or in the extension’s tables (ydoc_).
New to the project? Read the overview, install the extension and follow the quickstart. The quickstart adds a counter column to a table, counts as two writers and merges a count that arrives from another place.
Build your application
Section titled “Build your application”| Task | Read |
|---|---|
| Understand CRDTs, and decide whether you need one | Overview |
Install with a script, pg_tle or create extension |
Install |
| Add a counter column and count | Quickstart |
| Name your writers, use device ids, recover a lost device | Replicas and identity |
| Write from several clients without losing updates | Update safely |
| Let clients send their own counts without forging each other’s | Accept writes from untrusted clients |
| Index the value, keep counters as deltas, read the benchmarks | Storage and performance |
| Understand the state and its merge | PN-Counter |
| Let several people edit a text, from forms or live editors | Collaborative text for a blog post |
| Choose between a text column and table-backed documents; how text merges, and what it cannot do | Collaborative text |
| Connect a live editor in JavaScript | JavaScript client |
| Understand an error or a limit | Errors, Limits |
Reference
Section titled “Reference”| Page | Contents |
|---|---|
| Shared | Schema and naming, privileges, replica ids, current_replica_id, the settings, the state envelope and versioning |
| PN-Counter functions | pn_empty, pn_increment, pn_decrement, pn_value, pn_merge, pn_merge_agg, pn_is_valid, pn_apply_delta |
| Collaborative text column functions | The crdt.yseq domain (experimental) and yseq_empty, yseq_new, yseq_value, yseq_length, yseq_version, yseq_insert, yseq_delete, yseq_set, yseq_diff, yseq_ops_since, yseq_merge, yseq_merge_agg, yseq_apply, yseq_is_valid; limits |
| Collaborative text functions | ydoc_create, ydoc_value, ydoc_length, ydoc_version, ydoc_base, ydoc_insert, ydoc_delete, ydoc_set, ydoc_apply, ydoc_merge, ydoc_ops_since, ydoc_compact, ydoc_rejected_purge, ydoc_drop; the tables and their grants; limits |
| JavaScript client | pg-crdt-client for ydoc_ collaborative text: openYdoc, edits at UTF-16 positions, change events, sync, transports, refused ops |
| Errors | Every SQLSTATE the extension raises, and the Postgres errors you can meet |
| Limits | Numeric limits, growth, and what is not built |
Project
Section titled “Project”| Page | Contents |
|---|---|
| Changelog | What each version contains |
| Test suite | How to run the tests, and what each spec file checks |
| Conventions | How these pages are written |
| Research | The architecture, prior art, benchmarks and the build journal. Planned types are described there |
Example conventions
Section titled “Example conventions”The examples are generic Postgres. Run the SQL in psql, or in any client. Where an application does the work, choose JavaScript or SQL: the site remembers your selection. JavaScript examples use plain node-postgres (pg) and assume a connected client, as set up in the quickstart. The SQL uses lowercase keywords, qualifies every extension name with crdt., and shows results as comments.
Each task page states its prerequisites, and its examples run in order unless a block is introduced as a fragment, or ends with an -- ERROR: comment. Roles such as app_writer are examples: grant to your own.