Catalogue / Data

SQL database

datasql-database

Relational datastore, usually the system of record.

Category
Data
Properties
16
Components
76
Rules
6
Properties · 16 defined by this kind

A node of this kind resolves each property from its own props, then the component's defaults, then the default below.

propertytypevaluesrequireddefault
appendOnly · advancedboolean—nofalse
backupEnabledboolean—nofalse
backupRetentionDaysinteger—no—
commitProtocol · advancedenumsingle | two-phasenosingle
concurrencyControl · advancedenumpessimistic | optimistic | constraintno—
distributedboolean—nofalse
encryptionAtRestboolean—nofalse
idEncodesShard · advancedboolean—nofalse
instancesinteger—no—
managedboolean—nofalse
multiWriterboolean—nofalse
replicaFanout · advancedinteger—no—
replicaOfref—no—
replicationenumnone | async | syncnonone
shardKeystring—no—
shardedboolean—nofalse
Rules for this kind · 6
business-updates-without-index-propagation

Application servers write this database and the design keeps a search index, but nothing captures the database's changes. The index then depends on the application writing to both places, and the two drift apart silently.

  • — all of these hold:
  • — the node has at least one synchronous incoming edge from an app-server
  • — the design contains a node of kind search-index
  • — this does not hold:
  • — the node has at least one outgoing edge to a change-data-capture
datastore-missing-backup

A system of record with backups off, or with no retention period stated, cannot be restored. The loss is discovered on the day it matters.

  • — any of these hold:
  • — the node's `backupEnabled` is false
  • — the node's `backupRetentionDays` has no value
datastore-single-region

The design promises multi-region availability, but this datastore sits in one region and does not replicate. A region outage takes the system of record with it.

  • — all of these hold:
  • — the design requirement `availability.multiRegion` is true
  • — the node sits inside exactly 1 region group
  • — the node's `replication` is "none"
read-heavy-path-without-cache

The design states a read-heavy workload and application servers read this datastore directly, yet the design has no cache anywhere. Every read pays a database round trip.

  • — all of these hold:
  • — the design requirement `traffic.readWriteRatio` is a number greater than 10
  • — the node has at least one synchronous incoming edge from an app-server
  • — this does not hold:
  • — the design contains a node of kind cache
read-replica-as-sole-scaling

Asynchronous read replicas scale reads only. When the store is neither sharded nor distributed the writes still land on one primary, so the replicas add nothing at the declared peak.

  • — all of these hold:
  • — the node's `replication` is "async"
  • — the node's `sharded` is false
  • — the node's `distributed` is false
  • — the node's declared requests per second is more than 5000
single-writer-primary-at-peak-qps

A single-writer, unsharded relational primary has a throughput ceiling. Declaring more than five thousand requests per second against it means the peak finds that ceiling in production.

  • — all of these hold:
  • — the node's `multiWriter` is false
  • — the node's `sharded` is false
  • — the node's declared requests per second is more than 5000
Components · 76
Source
# yaml-language-server: $schema=../schema/kind.schema.json
# Relational datastore, usually the system of record.
# multiWriter and sharded default false so single-writer-primary-at-peak-qps can fire on the common case.
schemaVersion: "1"
type: "kind"
id: "sql-database"
category: "data"
properties:
  backupEnabled:
    type: "boolean"
    default: false
  backupRetentionDays:
    type: "integer"
  replication:
    type: "enum"
    values: ["none", "async", "sync"]
    default: "none"
  replicaOf:
    type: "ref"
    refKind: "sql-database"
  encryptionAtRest:
    type: "boolean"
    default: false
  sharded:
    type: "boolean"
    default: false
  shardKey:
    type: "string"
  multiWriter:
    type: "boolean"
    default: false
  distributed:
    type: "boolean"
    default: false
  replicaFanout:
    type: "integer"
    advanced: true
  idEncodesShard:
    type: "boolean"
    default: false
    advanced: true
  concurrencyControl:
    type: "enum"
    values: ["pessimistic", "optimistic", "constraint"]
    advanced: true
  commitProtocol:
    type: "enum"
    values: ["single", "two-phase"]
    default: "single"
    advanced: true
  appendOnly:
    type: "boolean"
    default: false
    advanced: true
  instances:
    type: "integer"
  managed:
    type: "boolean"
    default: false

The same page as markdown, for an agent: /catalogue/kinds/sql-database.md