Whether an exception says the database cannot be reached, rather than that
it refused a statement. One definition, read by `wagoe.platform.database`,
the loops that stop at a lost connection, and devtools' WGE-303 (BOU-970).

Which integrity constraint a database refused a write on, read from what the
driver reports: SQLState, vendor code and message. H2, PostgreSQL, SQLite
and MySQL.

Migration SQL written for PostgreSQL, H2 and SQLite, rewritten for MySQL.

The scaffolder writes one migration for every database (BOU-569). MySQL has
no UUID or zoned TIMESTAMP type, takes no IF NOT EXISTS on an index, and
ignores a REFERENCES written on a column. Only that is rewritten, so SQL
written for MySQL passes through as it is.

Pure functions for SQL query building and transformation.

All functions in this namespace are pure - they take data and return data
without side effects. No I/O, logging, or state mutation.

Pure logic for database seeding.

A seed file is EDN, in either of two shapes.

A map of table -> rows, for the simple case:

  {:tasks [{:title "Try the admin UI" :done false}
           {:title "Read AGENTS.md"   :done true}]}

Or a vector of [table rows] pairs, which is ordered:

  [[:users [{:email "admin@example.com"}]]
   [:tasks [{:title "Owned by that user" :user-id 1}]]]

Insert order matters as soon as one table references another, and EDN maps
only preserve their written order up to 8 entries — a 9th turns the literal
into a PersistentHashMap and the order becomes hash order. Rather than let a
seed file quietly start inserting children before parents once it grows, a
map larger than that is rejected with a pointer to the vector form.

Table and column names are written in kebab-case, like the rest of the
codebase; the conversion to snake_case happens here, at the point where the
data becomes a persistence concern.

`id`, `created-at` and `updated-at` may be left out; see `resolve-seed`. A
child names its parent by a symbolic id, a qualified keyword:

  [[:invoices [{:id :invoice/acme :number "INV-1"}]]
   [:invoice-line-items [{:invoice-id :invoice/acme :description "Work"}]]]

Everything in this namespace is pure. Validation returns typed error values
rather than throwing — the shell decides how to present them.

Executing queries against a configured database — platform's data-access API.

The sanctioned surface for every module's persistence layer. Modules used to
require `wagoe.platform.shell.adapters.database.common.core` instead, which
is platform's shell: 20 sites across tenant, user, admin, workflow and
devtools reaching into another module's internals, carried as the largest
entry in `.wagoe/check-ports.edn` (BOU-303).

Deliberately narrower than what it delegates to. Connection-pool lifecycle,
raw SQL formatting and adapter construction stay internal — a module needs
to run a query, not to build a pool. `wagoe.platform.ports.database` is the
other half: what an adapter must implement.

Not a protocol, and that is the point. There is one way to execute a
HoneySQL map against a JDBC connection, and the differences between engines
live behind the `DBAdapter` port. A second protocol here would name a seam
nothing implements — the mistake ADR-037 removed.

A lease row that replicas take turns holding, timed by the database clock
so replica clock skew cannot split it. A holder paused past `lease-ms` may
overlap the next one until it notices; callers whose work must not run twice
guard it separately.

The database port: what a database adapter must provide.

Lived at `wagoe.platform.ports.database` until BOU-303,
which is where a port cannot live — every module's persistence layer had to
reach into platform's shell to name it, and `.wagoe/check-ports.edn` carried
the 20 sites that did as its largest burn-down entry.

Unlike the router abstraction ADR-037 removed, this seam is real: four
adapters implement it (postgresql, mysql, sqlite, h2), and the differences
between them — dialect, boolean representation, JDBC URL shape — are exactly
what the methods below name.

For executing queries rather than describing a database, see
`wagoe.platform.database`.

Protocol defining the common interface for database adapters.

This protocol abstracts database-specific behavior while allowing 
common database operations to be implemented in a shared core namespace.
Each database type (SQLite, PostgreSQL, MySQL, H2) implements this 
protocol to provide database-specific functionality.

Design Philosophy:
- Keep protocol narrow - prefer common behavior in core
- Only include methods that differ between databases
- Database-agnostic operations belong in core namespace
- Type conversions use shared utilities where possible

One `DBAdapter` implementation, over a per-engine spec.

There used to be four, and they were copies: each `query.clj` was the same
sixty lines turning on two decisions, and each `core.clj` was thirty lines of
delegation. A fix landed in one and not its neighbours — that is how H2 came
to carry a `table-exists?` workaround while SQLite and MySQL reported every
table as absent (BOU-430).

A spec names what the port says may differ between engines, and nothing else:

  :label              for log lines — "MySQL"
  :dialect            what callers dispatch on; nil means PostgreSQL
  :driver             JDBC driver class name
  :jdbc-url           (fn [db-config] -> String)
  :pool               HikariCP defaults
  :session-statements (fn [db-config] -> seq of JDBC param vectors)
  :booleans           :native or :int
  :string-match       :like or :ilike
  :table-exists?      (fn [datasource table-name] -> boolean)
  :table-info         (fn [datasource table-name] -> vector of column maps)
  :unique-keys        optional (fn [datasource table-name] -> vector of column-name
                      vectors); without one, read from the JDBC metadata
  :engine             :postgresql, :mysql, :sqlite or :h2
  :capabilities       a subset of protocols/capability-keywords
  :column-types       {logical-type DDL-type} for protocols/logical-column-types;
                      a string is VARCHAR(length) unless :string names one type for all
  :now-ms-sql         SQL for the database clock in epoch millis
  :on-connect         optional (fn [java.sql.Connection]), run on each new
                      connection after the session statements
  :param->db          optional (fn [value] -> value) for each query parameter;
                      without one, `instant->iso`
  :db->value          optional (fn [value] -> value) for each value read

Common connection pool management utilities.

Common database operations - main coordination module.

This namespace serves as the main coordinator for common database
functionality, bringing together specialized modules for different
aspects of database operations that work across all adapter types.

The common functionality has been refactored into specialized namespaces:
- common.connection: Connection pool management with HikariCP
- common.execution: Query execution with logging and error handling
- common.schema: Schema introspection and DDL execution
- common.utils: Database information and convenience functions
- common.core: Main coordination module (this namespace)

Pure query building functions are now in wagoe.platform.core.database.query

This modular structure provides:
- Better organization with focused responsibilities
- Easier maintenance and testing
- Consistent patterns across all database adapters
- Clear separation of concerns

Query execution with I/O, logging, and error handling.

This is part of the imperative shell - it performs database I/O,
manages transactions, and handles side effects like logging.

Table introspection for every adapter.

PostgreSQL, MySQL and H2 all read `information_schema` and differ only in
which schema predicate identifies "this database", which HoneySQL dialect
formats the query, and whether the table name may be folded to lower case.
SQLite has no `information_schema` and reads `sqlite_master` and
`PRAGMA table_xinfo` instead.

Both forms return the same column maps — `:name` (lower case), `:type`,
`:not-null`, `:default`, `:primary-key`, `:generated`, `:generated-always`,
`:max-length` (a character column's declared length, nil on SQLite) —
which is what the port promises and what the four separate copies did not
consistently deliver.

Common schema management and DDL utilities.

Common database utilities and information functions.

Configuration-driven database adapter management.

This namespace provides functionality to read database configuration from
config.edn and only load adapters that are marked as :active. This allows
for optimized deployments where only required database drivers are loaded.

Key Features:
- Configuration-driven adapter loading
- Environment-specific database configs
- Graceful handling of inactive adapters
- JDBC driver optimization (only load needed drivers)

Usage:
  (require '[wagoe.platform.shell.adapters.database.config :as db-config])
  
  (db-config/get-active-adapters "dev")     ; Get active adapters for dev env
  (db-config/adapter-active? :postgresql)    ; Check if adapter is active

Factory functions for database adapter creation and configuration.

This namespace provides convenient factory functions for creating database
adapters, data sources, and database contexts. It supports multiple database
types (SQLite, PostgreSQL, MySQL, H2) through a unified configuration interface.

Key Features:
- Database adapter creation from configuration
- Connection pool and datasource management
- Database context creation with adapter + datasource
- Resource management with automatic cleanup
- Configuration validation and error handling

Usage:
  (require '[wagoe.platform.shell.adapters.database.factory :as dbf])
  
  (def ctx (dbf/db-context {:adapter :sqlite :database-path "./app.db"}))
  (db/execute-query! ctx {:select [:*] :from [:users]})

H2 connection settings and JDBC URL.

H2 adapter.

Runs in PostgreSQL compatibility mode with DATABASE_TO_LOWER, so identifiers
behave like PostgreSQL's; native booleans; ANSI SQL.

MySQL connection settings and JDBC URL.

MySQL adapter.

LIKE (case-insensitive by MySQL's default collation), booleans as TINYINT(1),
and a table name that is not folded — on a case-sensitive filesystem MySQL
table names are case-sensitive.

PostgreSQL connection settings and JDBC URL.

PostgreSQL adapter.

Case-insensitive matching with ILIKE, native booleans, and session settings
carried on the JDBC URL rather than applied per connection — see
postgresql.connection.

SQLite connection settings and JDBC URL.

SQLite adapter.

Booleans as integers, no information_schema — introspection reads
sqlite_master and PRAGMA table_xinfo — and a set of PRAGMAs applied per
connection, see sqlite.connection.

Dynamic JDBC driver loading based on active database configurations.

This namespace provides configuration-driven driver loading that eliminates
the need to coordinate between configuration files and command-line aliases.
Drivers are loaded dynamically based on which databases are marked as :active
in the configuration files.

Key Features:
- Single source of truth: configuration files control everything
- Clear error messages when drivers are missing
- Automatic driver detection from active databases
- No command-line alias coordination required

Usage:
  (require '[wagoe.platform.shell.adapters.database.utils.driver-loader :as dl])

  ;; Load drivers for active databases in current environment
  (dl/load-required-drivers!)

  ;; Load drivers for specific environment
  (dl/load-drivers-for-environment! "dev")

Schema-to-DDL generation utilities for database adapters.

This namespace provides utilities for generating database DDL statements
from Malli schema definitions. It handles:
- Column types, from the adapter's `column-type`
- Table creation with constraints
- Index generation from schema analysis
- Cross-database compatibility

Key Features:
- Uses Malli schemas as canonical source of truth
- Database-specific column type mapping
- Foreign key and unique constraint generation
- Automatic index creation based on field patterns

Usage:
  (require '[wagoe.platform.shell.adapters.database.utils.schema :as schema])

  (schema/generate-table-ddl ctx "users" some-malli-schema)
  (schema/initialize-tables-from-schemas! ctx schema-map)

CLI commands for database migration management.

Usage:
  clojure -M -m wagoe.platform.shell.database.cli-migrations [command] [options]

Commands:
  migrate         - Run all pending migrations
  rollback        - Roll back the last migration
  status          - Show migration status
  create <name>   - Create a new migration file
  reset           - Drop what the app owns and migrate (dev, test, acc only)
  init            - Initialize migration system

CLI entry point for database seeding.

Usage:
  clojure -M -m wagoe.platform.shell.database.cli-seed [path]

Defaults to resources/seeds/dev.edn. Invoked by `bb db:seed`, which cannot
open a JDBC connection itself (libs/tools is pure Babashka), so it shells out
here — the same arrangement `bb migrate` uses for cli-migrations.

Database migration management using Migratus.

This namespace provides functions to manage database schema migrations:
- Run pending migrations (up)
- Rollback migrations (down)
- Check migration status
- Create new migrations

Migrations are discovered from the application's `migrations/` directory and
from any library manifests published on the classpath.

`db:reset`: drop what the application owns, then migrate.

What the application owns: every migration's objects, through the down
migrations; the tables libraries create at boot, as each declares in
`wagoe/boot-tables/<lib>.edn`; `schema_migrations`; and the schema of each
tenant in the `tenants` table. Nothing else in the database is touched, and
when anything else depends on what would go, nothing is dropped (BOU-585).

Loads a seed file into the active database.

The pure parts — validation, kebab->snake conversion, plan building — live in
`wagoe.platform.core.database.seed`. This namespace owns the I/O: reading the
file, acquiring the datasource, and executing the inserts.

Widen timestamp columns declared without a timezone to ones that carry it.
Text columns holding ISO-8601 instants are converted too; on SQLite, which
has no type to change, their values are rewritten as epoch millis.

A column declared `TIMESTAMP` stores wall-clock time and no zone, so what it
means depends on who reads it. The JVM flag from BOU-431 makes every Wagoe
process agree that the zone is UTC, and this makes the column say so itself —
so a report, a psql session or another service reads the same moment.

Only PostgreSQL and H2 need it. MySQL's `TIMESTAMP` already normalises to UTC
on the way in and out (its zone-less type is `DATETIME`), and SQLite has no
timezone concept at all — its column types are storage-class affinities.

Idempotent: a column that already carries a zone is left alone, so this is
safe to run from a migration and from a boot-time schema check.

Validation functions for database contexts and configurations.

Context validation functions check data structure conformity including
protocol satisfaction, which requires access to the DBAdapter protocol
from the shell adapters layer.

Which library owns each framework module, and which modules a config
switches on. Pure data, here rather than in wagoe-platform so migrations
can skip switched-off modules without depending on it (BOU-934).
`wagoe.platform.shell.modules` re-exports all three.

Transit JSON for values that leave the process and come back as Clojure:
events on the Redis bus and outbox, jobs on the :db and :redis queues. JSON
would turn their keywords, UUIDs and instants into strings (BOU-689).