Self-hosted service
crate/crate avatar
crate/crate

crate/crate: reading CrateDB's Lucene index as a distributed SQL engine

CrateDB is a distributed and scalable SQL database for storing and analyzing massive amounts of data in near real-time, even with complex queries. It is PostgreSQL-compatible, and based on Lucene.

4,453 stars624 forksJavaApache-2.0

At a glance

What is it?
CrateDB puts a Lucene index behind a PostgreSQL wire protocol and calls the result a distributed SQL database. The repository's own quickstart boots a single node, so it does not exercise its cluster claims.
Who is it for?
Adopt CrateDB when the workload is a stream of arriving records queried with search and aggregation, and when running containers across Kubernetes, AWS or Azure is something you already do. Before anything else, run the README's single-node docker command with CRATE_HEAP_SIZE=1g, load a representative slice of your own data, and watch how far the heap gets before you size anything for real.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Java, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • crate/crate4,453 ★ · +17
Star history
Repository2026-09-222026-11-15
crate/crate4.4k4.5k

17 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The wire protocol is Lucene with a SQL grammar bolted on

CrateDB answers queries over the PostgreSQL wire protocol on port 5432 and over an HTTP API on port 4200, and it does that on top of Lucene. That single architectural choice decides most of the trade-offs you will meet later. Standard SQL lands on an index that was designed for inverted indexes and full text scoring, not for row stores. The project describes itself as distributed SQL with the document-oriented features of dynamic table schemas and queryable objects, so it is a relational surface over a search engine rather than a search engine with a SQL veneer bolted on afterwards.

The upside is real and narrow. Geospatial types, real-time full-text search and time-series data are first-class rather than extensions you install later.

Auto-sharding and auto-replication are what you give up control over

Auto-partitioning, auto-sharding and auto-replication appear in the feature list as givens rather than consequences. In practice that is the mechanism, and it cuts both ways. A shard allocation policy decides where every row lives, and a replication policy decides how many copies exist, and the README describes neither.

What the same design buys is the thing the project actually leads with: no shared state, so nodes scale out on ephemeral virtual machines in Kubernetes, AWS or Azure, and self-healing and auto-rebalancing handle a node disappearing. Write to a new node, let it join, and the cluster rebalances. That is a good trade when ingest volume is the problem.

The quickstart boots one node, so it proves nothing about the cluster

The Try CrateDB section gives exactly one command, and it disables clustering outright. Publishing 4200 and 5432 maps the Admin UI and the PostgreSQL port onto the host, CRATE_HEAP_SIZE=1g caps the heap, and the trailing discovery flag pins the node to itself.

bash
sh$ docker run --publish 4200:4200 --publish 5432:5432 --env CRATE_HEAP_SIZE=1g crate '-Cdiscovery.type=single-node'

Read that against the Features list a few lines above, which promises horizontally scalable clusters with no shared state, and the contradiction is plain. The one command a new user is handed turns off the property the project sells. Nothing in that run exercises shard allocation, replication, rebalancing or multi-node query fan-out. After the container starts, the next step points at the Admin UI sql console, the CrateDB shell CLI, and a list of recommended clients and tools. Those are the correct next steps.

The 1g heap is a data volume limit stated as an environment variable

No index-size guidance ships with that command, and nothing downstream says what fits inside one gigabyte. That omission is the sharpest edge for an evaluator. The same paragraph that claims modest clusters ingest tens of thousands of records per second says nothing about the resulting index size per node.

The README sets CRATE_HEAP_SIZE=1g only in its single-node Docker example and points to the installation documentation and the Docker and Kubernetes how-to guides for real deployments. Treat 1g as a smoke test, not a sizing recommendation.

Where PostgreSQL itself is the honest alternative

The difference in approach is not speed, it is where the index lives. PostgreSQL keeps a B-tree index on disk and treats durability, transactions and row-level locking as the contract; adding full-text search means calling out to tsvector, tsquery and GIN or GiST indexes, which are search facilities bolted onto a transactional engine. CrateDB inverts that: the search engine is the substrate, and relational behaviour is layered on top of a Lucene index.

That inversion is worth it when the query is a search plus aggregation over a lot of arriving data. Choosing PostgreSQL means accepting that geospatial and full-text work takes extension setup. Choosing CrateDB means accepting a cluster model built on auto-sharding, auto-replication and auto-rebalancing.

User-defined functions extend SQL, and the README gives no signature

User-defined functions extend CrateDB's SQL surface from inside the database, which is the hook a team reaches for when domain logic cannot be expressed in standard SQL. The capability gets a single line in the feature list and a link out to the documentation. There is no signature, no deployment step and no statement of what a function can reach, so treat the extension surface as documented elsewhere and unverified here.

Crate.io is named as the primary maintainer, and CrateDB Cloud, a fully managed service from the same company, is the option the README offers to people who would rather not operate the cluster themselves.

You own the cluster, not just the schema

A node leaving mid-query is not described anywhere here. Auto-rebalancing and self-healing come as features, but the operational procedure behind them, how to watch a rebalance, how to tell a stalled rebalance from a slow query, is absent. A Jenkinsfile and a GitHub Actions workflow at the repository root show how the project builds itself, not how you run it.

The last push to master was on 2026-11-02 and the repository is not archived, with 6.5.0 cut on 2026-10-13, so the branch is moving.

So the ongoing cost sits with the adopting team rather than with the database. You size a heap, you watch cluster health, and you decide when a version line is safe to move to. The README's own answer for teams that do not want that job is the managed service. Nobody has to license anything extra to run CrateDB yourself, so the real question is operational, not legal.

Editorial conclusion

Adopt CrateDB when the workload is a stream of arriving records queried with search and aggregation, and when running containers across Kubernetes, AWS or Azure is something you already do. Before anything else, run the README's single-node docker command with CRATE_HEAP_SIZE=1g, load a representative slice of your own data, and watch how far the heap gets before you size anything for real. If that test fails, no amount of horizontal scaling in the feature list will save the design.

Frequently asked questions

How do I run CrateDB for the first time?

The README's Try CrateDB section gives one Docker command that publishes ports 4200 and 5432, sets CRATE_HEAP_SIZE=1g, and passes the setting discovery.type=single-node. Once the container runs, use the Admin UI sql console, the CrateDB shell CLI, or a recommended client.

Is CrateDB based on Lucene?

Yes. The repository description states that CrateDB is PostgreSQL-compatible and based on Lucene, which is why full-text search, geospatial types and time-series data are listed among its features.

How does CrateDB scale across nodes?

The README points to scaling horizontally on ephemeral virtual machines such as Kubernetes, AWS and Azure with no shared state, and lists auto-partitioning, auto-sharding, auto-replication, self-healing and auto-rebalancing among its features. Note that the quickstart command sets discovery.type=single-node, so it does not exercise any of that.

Does CrateDB support full-text search and geospatial data?

Both are listed among its features, alongside time-series data. The project description states that CrateDB is PostgreSQL-compatible and based on Lucene, which is the underlying index behind that search capability.

How do I interact with CrateDB once it is running?

Use the Admin UI sql console or the CrateDB shell CLI tool, or pick from the list of recommended clients and tools. The Admin UI itself is served on the published port 4200.

What licence is CrateDB released under?

Apache-2.0, with LICENSE, NOTICE and 3RD-PARTY-NOTICES.md at the top level of the repository. The README names Crate.io as the primary maintainer and points to CrateDB Cloud as a fully managed option.

Official sources

  1. crate/crate on GitHub
  2. License: Apache-2.0
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/crate-crate.svg)](https://hysenlabs.com/projects/crate-crate)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/crate-crate.svg)](https://hysenlabs.com/projects/crate-crate)

Was this useful?