Datastores

CodeMetrics uses a datastore to persist data such as caching, query results, and configuration. Choosing the right datastore for your environment affects performance, scalability, and operational complexity.

For lightweight or local use, the in-memory or local file implementations require no external infrastructure. For production deployments, a managed datastore such as DynamoDB or MongoDB is recommended to ensure data durability and support multiple application instances running concurrently.

The following datastore implementations are supported:

Name	Details
inmem	In-memory datastore implementation.️ This datastore implementation holds all items in memory for the lifetime of the process. There is no eviction, so growth is infinite with continued insertions. Do not use this in production.
dynamodb	AWS DynamoDB datastore. This datastore implementation holds items in external DynamoDB tables.
mongodb	MongoDB datastore. This datastore implementation holds items in an external MongoDB instance.
nedb	NeDB datastore. This datastore implementation holds items in an external nedb database.

Configuration

Configuration can be set using the DATASTORE_IMPL environment variable in backend, which accepts one of inmem, mongodb as values.

DATASTORE_IMPL=inmem

For a full list of collections used by CodeMetrics, see Datastore collections.

Auto-creation of tables and collections

By default, CodeMetrics automatically creates the required datastore tables (DynamoDB) or collections (MongoDB) on first access if they do not already exist.

Operators who prefer to manage database resources externally (e.g. via Terraform, CloudFormation, or manual provisioning) can disable this behaviour:

DATASTORE_AUTO_CREATE=false

When auto-creation is disabled and a required table or collection does not exist, the application will log an error message identifying the missing resource and guidance on how to resolve it, then throw an error.

This setting applies to DynamoDB and MongoDB datastores only. The in-memory and local file database implementations always create their stores automatically, as they are local/embedded.

Note: For MongoDB, if auto-creation is disabled and the TTL expiry index does not exist on an existing collection, a warning will be logged but the application will continue to operate. TTL-based expiration will not function until the index is created.

Datastore implementations

In-memory implementation

The in-memory implementation is the default, and requires no additional configuration. Because it is in-memory, it does not share data between multiple instances of the application.

This datastore implementation holds all items in memory for the lifetime of the process. There is no eviction, so growth is infinite with continued insertions. Do not use this in production.

The following environment variables apply:

DATASTORE_IMPL=inmem

Local file database implementation

The Local DB implementation uses an external file to store data. It is a lightweight, embedded database. It is a good option for local use, but not recommended for production use.

The following environment variables apply:

DATASTORE_IMPL=localdb
DATASTORE_PATH=/path/to/code-metrics.db

Leaving the DATASTORE_PATH blank will use an in-memory version of the DB.

DynamoDB implementation

The DynamoDB implementation uses an external DynamoDB instance to store data. It requires valid AWS credentials and permissions.

The following environment variables apply:

DATASTORE_IMPL=dynamodb
DATABASE_NAME=CodeMetrics
AWS_REGION=us-east-1

Ensure the CodeMetrics backend has the necessary AWS permissions (e.g. using IAM or AWS configuration files) to read (and optionally create) the relevant tables.

The IAM permissions required are:

dynamodb:CreateTable
dynamodb:DeleteItem
dynamodb:DescribeTable
dynamodb:DescribeTimeToLive
dynamodb:GetItem
dynamodb:PutItem
dynamodb:Scan
dynamodb:UpdateTimeToLive

Example IAM policy document

This example IAM policy scopes access to tables with names in the format `CodeMetrics_*`, but you can be a specific as required by your environment.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1688577177960",
      "Action": [
        "dynamodb:CreateTable",
        "dynamodb:DeleteItem",
        "dynamodb:DescribeTable",
        "dynamodb:DescribeTimeToLive",
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:Scan",
        "dynamodb:UpdateTimeToLive"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:dynamodb:us-east-1:000000000000:table/CodeMetrics_*"
    }
  ]
}

MongoDB implementation

The MongoDB implementation uses an external MongoDB instance to store data. It requires configuration of the connection and authentication details for the MongoDB server.

The following environment variables apply:

DATASTORE_IMPL=inmem
DATABASE_NAME=code-metrics
DATABASE_URI=mongodb://code-metrics:changeme@localhost:27017