Datastores

Creating databases and stateful dependencies to be privately allocated to a parent service

Architect makes it easy to allocate private databases and other stateful dependencies with a service by specifying a "datastore" in your service configuration file. Datastores are cited first by a named key followed by the details needed to configure the datastore and run it locally.

Allocating databases

{
  "datastores": {
    "primary-db": {
      "image": "postgres:11",
      "port": 5432,
      "parameters": {
        "POSTGRES_USER": {
          "alias": "username",
          "default": "postgres"
        },
        "POSTGRES_PASSWORD": {
          "alias": "password",
          "default": "architect"
        },
        "POSTGRES_DB": {
          "alias": "name",
          "default": "architect_cloud_api"
        }
      }
    }
  },
}

The above service config snippet indicates that the service requires a private datastore named "primary-db". This datastore is provisioned using the image, postgres:11 (you can specify any image reference accepted by docker pull) which is expected to run on port "5432" by default, and accepts three parameters: POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB. The "image" and "port" fields are required so that Architect can provision the service and broker connectivity, and the parameter syntax is identical to the syntax used to specify service parameters

Connecting to databases

With parameter mapping

Just like with dependencies, key reference information for a datastore can easily be mapped to existing service parameters if an application already has a way of receiving the address for a dependent database. Simply map the parameters, host, or port from a datastore to the parent service and you're off to the races:

{
  "parameters": {
    "DB_HOST": {
      "default": {
        "valueFrom": {
          "datastore": "primary-db",
          "value": "$HOST"
        }
      }
    },
    "DB_PORT": {
      "default": {
        "valueFrom": {
          "datastore": "primary-db",
          "value": "$PORT"
        }
      }
    }
  }
}

Using the SDK

In addition to parameter mapping, Architect also maintains a set of SDKs designed for use with the platform that can aid in brokering connections to datastores. The SDKs don't require parameter mapping in order to connect as they are designed to parse default variables available to all Architect services:

Using in production

It is important that services include references to privately allocated databases to make it easy to provision short-lived environments, but it is not recommended to use databases provisioned this way in production. Due to the complexity with maintaining databases, it is recommended that datastores be provisioned in production out-of-band from Architect and that production environments override the datastore location to ensure Architect brokers the services connection to the existing database instead of provisioning a new one.

// Example environment config
{
  "services": {
    "architect/payments:v1": {
      "datastores": {
        "primary-db": {
          "host": "postgres-instance.123456789012.us-east-1.rds.amazonaws.com"
        }
      }
    }
  }
}

The above is an example of an environment config that cites an external host for the primary-db of the payments service. Deploying this config will tell Architect not to provision a new datastore and to instead whitelist the connection between the payments service and the datastore. You can learn more about environment configs in the operator guides.