Connection.hs

{- | Schema-resolution helpers for application read-model and projection tables.

Keiro's own framework tables live in the dedicated @keiro@ schema and its
runtime queries are fully qualified there. This module is about the /third/
layer: where an application's read-model /data/ tables live, and how the
application declares and reaches that location.

A PostgreSQL /schema/ is a namespace of tables inside one database. Because
Keiro opens its database pool through kiroku's connection settings — whose
@search_path@ starts with the event store's private @kiroku@ schema — an
unqualified @CREATE TABLE my_read_model (...)@ would land the table inside the
@kiroku@ event-store schema. To place it elsewhere, the application must
qualify at least its @CREATE TABLE@ as @schema.table@ (an unqualified create
always lands in the first @search_path@ entry). Qualifying the read/write SQL
too makes everything correct regardless of @search_path@ — the robust default.

This module gives applications exactly one convention:

* 'qualifyTable' builds a double-quoted, schema-qualified table reference to
  interpolate into projection SQL.
* 'withProjectionSchema' / 'keiroConnectionSettings' wire the store connection
  so a chosen projection schema also /resolves/ on the pool (via kiroku's
  @extraSearchPath@), for applications that also want unqualified SQL to work.
* 'ensureProjectionSchema' is an opt-in @CREATE SCHEMA IF NOT EXISTS@ helper for
  development, tests, and worked examples; Keiro never calls it automatically.

The kiroku store connection's @schema@ field stays @kiroku@ and is never
repointed: it also drives the @<schema>.events@ @LISTEN@/@NOTIFY@ channel, so
changing it would break subscription wake-ups. The projection schema is reached
only by qualification and\/or @extraSearchPath@.
-}
module Keiro.Connection (
    qualifyTable,
    quoteIdentifier,
    withProjectionSchema,
    keiroConnectionSettings,
    ensureProjectionSchema,
)
where

import Data.Text qualified as T
import Data.Text.Encoding qualified as TE
import Effectful (Eff, (:>))
import Keiro.Prelude
import Kiroku.Store.Connection (ConnectionSettings, defaultConnectionSettings)
import Kiroku.Store.Effect (Store)
import Kiroku.Store.Transaction (runTransaction)
import "hasql-transaction" Hasql.Transaction qualified as Tx

{- | Build a double-quoted, schema-qualified table reference @"schema"."table"@,
doubling any embedded double quotes (the same identifier quoting kiroku uses).
Interpolate the result directly into projection SQL, e.g.

@
"SELECT ... FROM " <> qualifyTable "app" "orders" <> " WHERE ..."
@
-}
qualifyTable :: Text -> Text -> Text
qualifyTable schema table = quoteIdentifier schema <> "." <> quoteIdentifier table

{- | Double-quote a single SQL identifier, doubling any embedded double quotes
(the same identifier quoting kiroku uses). Useful for building qualified names
or a @CREATE SCHEMA "<name>"@ statement.
-}
quoteIdentifier :: Text -> Text
quoteIdentifier ident = "\"" <> T.replace "\"" "\"\"" ident <> "\""

{- | Append @projectionSchema@ to a settings value's @extraSearchPath@ so a
pooled connection can /resolve/ (read\/write) application tables in that schema.
Idempotent: the schema is appended only if not already present. The store's
@schema@ field is left untouched (stays @kiroku@).
-}
withProjectionSchema :: Text -> ConnectionSettings -> ConnectionSettings
withProjectionSchema projectionSchema settings =
    settings & #extraSearchPath %~ appendUnique projectionSchema
  where
    appendUnique s xs
        | s `elem` xs = xs
        | otherwise = xs <> [s]

{- | kiroku's default connection settings (@schema = "kiroku"@) with
@projectionSchema@ added to @extraSearchPath@, so unqualified application
data-manipulation SQL resolves on the store pool while the store @schema@ stays
@kiroku@ (honoring the NOTIFY-channel constraint). This does /not/ bake Keiro's
own @keiro@ schema into @extraSearchPath@: Keiro's runtime queries are already
fully qualified and must not depend on @search_path@.
-}
keiroConnectionSettings :: Text -> Text -> ConnectionSettings
keiroConnectionSettings connString projectionSchema =
    withProjectionSchema projectionSchema (defaultConnectionSettings connString)

{- | Run @CREATE SCHEMA IF NOT EXISTS "<schema>"@ in a transaction. This is
opt-in: Keiro never calls it automatically. Use it in development, tests, and
worked examples where the application (not a production migration tool) owns
schema creation.
-}
ensureProjectionSchema :: (Store :> es) => Text -> Eff es ()
ensureProjectionSchema projectionSchema =
    runTransaction $
        Tx.sql (TE.encodeUtf8 ("CREATE SCHEMA IF NOT EXISTS " <> quoteIdentifier projectionSchema))