Running Elasticsearch in Docker with prorm

prorm reaches Elasticsearch through ElasticsearchStore, a search
implementation of the NoSqlStore interface. Documents are indexed and queried
with Elasticsearch's own DSL rather than SQL.

Start the container

A single node with security disabled is the simplest local setup:

$ docker run -d --name orm-es \
  -e discovery.type=single-node \
  -e xpack.security.enabled=false \
  -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
  -p 9200:9200 \
  docker.elastic.co/elasticsearch/elasticsearch:8.15.0

ES_JAVA_OPTS matters — the default heap is far larger than a laptop or CI
runner wants, and the container is killed by the OOM reaper without it.

With Compose

$ docker compose up -d --wait   # returns once the healthcheck passes
$ docker compose down -v        # tear down, volumes included

Waiting for readiness

Elasticsearch is among the slowest to start. Wait for a usable cluster status,
not just an open port:

$ until curl -sf "http://127.0.0.1:9200/_cluster/health?wait_for_status=yellow&timeout=1s" >/dev/null; do sleep 1; done

A single node cannot allocate replicas, so it reports yellow, not green.
Waiting for green will hang forever.

Dependencies

$ npm install ts-prorm-orm @elastic/elasticsearch

Data model

Elasticsearch keeps JSON documents in indexes; a mapping types each field, and text fields are analysed into an inverted index. Aliases point at indexes, so you can reindex and swap without changing readers.

See search stores for OpenSearch, Meilisearch, Typesense and Solr.

Connect and use the store

import { ElasticsearchStore } from 'ts-prorm-orm/nosql/elasticsearch';

const store = new ElasticsearchStore({ node: 'http://127.0.0.1:9200' });
await store.connect();

try {
  await store.indexDocument('articles', { title: 'Indexes and constraints' }, { id: '1' });
  await store.indexDocument('articles', { title: 'Query optimization' }, { id: '2' });

  // Elasticsearch indexes asynchronously; force visibility in a test.
  await store.refreshIndex('articles');

  const hits = await store.search('articles', {
    query: { match: { title: 'query' } },
  });
  console.log(hits);
} finally {
  await store.disconnect();
}

Elastic Cloud takes the deployment's Cloud ID and an API key; the options are the @elastic/elasticsearch client's own:

import { ElasticsearchStore } from 'ts-prorm-orm/nosql/elasticsearch';

const store = new ElasticsearchStore({
  cloud: { id: process.env.ELASTIC_CLOUD_ID! },
  auth: { apiKey: process.env.ELASTIC_API_KEY! },
});
await store.connect();

That refresh call is the single most common source of flaky Elasticsearch
tests: a document is not searchable the instant indexDocument() resolves. In
production, rely on the default one-second refresh interval instead of forcing
it.

[!WARNING] Known limitations
Documents are searchable only after a refresh (about one second); getDocument by id is realtime.
A field's mapping cannot change once set; create a new index, reindex, and swapAlias.
With security disabled (as above) anyone who can reach port 9200 can read and delete everything; keep it on localhost.
The container needs vm.max_map_count of at least 262144 on Linux hosts, or it exits at startup.

Tear down

$ docker rm -f orm-es

Troubleshooting

Symptom	Cause
Container exits immediately, code 137	OOM-killed. Set `ES_JAVA_OPTS` as above.
`max virtual memory areas vm.max_map_count [65530] is too low`	Linux host needs `sysctl -w vm.max_map_count=262144`.
Health never reaches green	Expected on one node — wait for `yellow`.
`security_exception`	Security is on by default in 8.x; disable it or supply credentials.
Document indexed but not found	Needs a refresh — see above.

NoSQL stores overview — the full store index

elasticsearch — the store's own API notes, in the repository

Running Elasticsearch in Docker with prorm

Start the container#

With Compose#

Waiting for readiness#

Dependencies#

Data model#

Connect and use the store#

Tear down#

Troubleshooting#

Related reading#