arbiter-migrations-0.1.0.0
arbiter-migrations
Safe HaskellNone
LanguageGHC2024

Arbiter.Migrations

Description

Versioned, tracked migrations for job queue schemas, run once in order. History lives in a schema_migrations table inside the target schema.

Synopsis

Registry

#data QueueSpec

A queue's table name, payload type, and handler result type. A type data constructor. It takes no promotion tick.

Instances

Instances details
RegistryTables ('[] :: [QueueSpec]) # 
Instance details

Defined in Arbiter.Core.QueueRegistry

Methods

#registryTableNames :: Proxy ('[] :: [QueueSpec]) -> [Text]

#registryQueueKinds :: Proxy ('[] :: [QueueSpec]) -> [(Text, [Text])]

RegistryPolicies ('[] :: [QueueSpec]) p # 
Instance details

Defined in Arbiter.Core.Admission

(HasKind (SpecPayload spec), KnownSymbol (SpecName spec), NotInPayloads (SpecPayload spec) rest, NotInTables (SpecName spec) rest, RegistryTables rest) => RegistryTables (spec ': rest) # 
Instance details

Defined in Arbiter.Core.QueueRegistry

Methods

#registryTableNames :: Proxy (spec ': rest) -> [Text]

#registryQueueKinds :: Proxy (spec ': rest) -> [(Text, [Text])]

(CollectFor (SpecPayload spec) p, KnownSymbol (SpecName spec), RegistryPolicies rest p) => RegistryPolicies (spec ': rest) p # 
Instance details

Defined in Arbiter.Core.Admission

#type Queue (table :: Symbol) payload = 'QueueWithResult table payload ()

A queue whose handlers store no result. A module with its own Queue type needs import Arbiter.Core hiding (Queue) or a qualified import.

Configuration

Source #data MigrationConfig

The desired state reconciled after a schema's tracked migrations run.

Constructors

MigrationConfig 

Fields

  • enableNotifications :: Bool

    Whether LISTEN/NOTIFY triggers for reactive job claiming should be installed. Re-running migrations reconciles existing schemas in either direction. Default: True.

  • enableEventStreaming :: Bool

    Whether event-streaming triggers for the admin UI should be installed. When enabled, every INSERT/UPDATE/DELETE on job tables fires an enriched JSON event via pg_notify. Re-running migrations with this disabled drops the triggers and shared function. Default: False.

  • rateLimitDurability :: Durability

    WAL-logging for the rate-limit bucket table in this schema. Unlogged (default) resets buckets on crash/failover. Durable preserves them at a throughput cost.

  • migrationLockTimeout :: Maybe NominalDiffTime

    How many seconds to wait for the schema's migration lock. The lock serializes replicas that migrate at the same time. Nothing (default) waits indefinitely.

Source #defaultMigrationConfig :: MigrationConfig

Notify triggers on, event streaming off, unlogged rate-limit buckets.

Source #validateRegistryNames :: SchemaName -> [TableName] -> Either Text ()

Reject queue names that generate a schema-wide arbiter table, or that generate object or channel names PostgreSQL truncates into each other. The length limit is where two of a queue's generated names collide.

Source #maxQueueNameBytes :: Int

The longest queue name whose generated identifiers survive PostgreSQL's 63-byte truncation distinct. Derived by rendering a probe queue's own DDL at each length.

Tracked Migrations

Source #runMigrationsForRegistry :: forall (registry :: JobPayloadRegistry). (RegistryAdmissionPolicies registry, RegistryTables registry) => Proxy registry -> ByteString -> SchemaName -> MigrationConfig -> IO (MigrationResult String)

Arguments

:: forall (registry :: JobPayloadRegistry). (RegistryAdmissionPolicies registry, RegistryTables registry) 
=> Proxy registry

Proxy for the job payload registry

-> ByteString

Database connection string

-> SchemaName

Schema name

-> MigrationConfig

Migration configuration

-> IO (MigrationResult String)

Migration results

Migrate every queue in a registry into one schema. The schema itself is created first, outside migration tracking.

type AppRegistry =
  '[ Queue "email_jobs" EmailPayload
   , Queue "order_jobs" OrderPayload
   ]

main :: IO ()
main = do
  result <- runMigrationsForRegistry
              (Proxy @AppRegistry)
              "host=localhost dbname=mydb"
              "arbiter"
              defaultMigrationConfig

Source #runMigrationsTrackedForTables :: ByteString -> SchemaName -> [(TableName, TableAdmission)] -> MigrationConfig -> AdmissionSeeds -> IO (MigrationResult String)

Run migrations for multiple tables within a single schema, seeding the given rate-limit policies. On migration success, reconciles the policy and bucket tables on the same connection. The table list must be the schema's whole queue set. Reconciliation treats an omitted queue as removed and drops its notify and event-streaming objects.

Source #jobQueueMigrationsForTable :: SchemaName -> TableName -> TableAdmission -> [MigrationCommand]

Arguments

:: SchemaName

Schema name

-> TableName

Table name

-> TableAdmission

Which admission trigger kinds to install

-> [MigrationCommand]

List of migration commands

One queue's tracked migrations, each under its own version identifier. reconcileOptionalTriggers owns the optional notify and event-streaming objects.

Source #schemaLevelMigrations :: SchemaName -> [MigrationCommand]

The schema-level migrations, run once per schema. Exposed for the golden suite. reconcileOptionalTriggers owns the optional notification and event-streaming objects.

Source #data AdmissionSeeds

Admission policy rows to seed after a successful migration.

Source #noAdmissionSeeds :: AdmissionSeeds

Seeds for a deployment with no admission policies.

Source #data TableAdmission

Which admission trigger kinds a table's payload declares. Trigger migrations are install-only. A kind removed from a payload keeps its triggers.

Instances

Instances details
Eq TableAdmission Source # 
Instance details

Defined in Arbiter.Migrations

Show TableAdmission Source # 
Instance details

Defined in Arbiter.Migrations

Source #allTableAdmission :: TableAdmission

Install every admission trigger kind.

Rate-limit reconciliation

Source #conflictingPolicyPrefixes :: [PolicyRow] -> [Text]

conflictingPrefixes specialized to policy rows.

Re-exports

#data MigrationResult a

A sum-type denoting the result of a migration.

Constructors

MigrationError a

There was an error in script migration.

MigrationSuccess

All scripts have been executed successfully.

Instances

Instances details
Functor MigrationResult # 
Instance details

Defined in Database.PostgreSQL.Simple.Migration

Methods

#fmap :: (a -> b) -> MigrationResult a -> MigrationResult b

#(<$) :: a -> MigrationResult b -> MigrationResult a

Foldable MigrationResult # 
Instance details

Defined in Database.PostgreSQL.Simple.Migration

Methods

#fold :: Monoid m => MigrationResult m -> m

#foldMap :: Monoid m => (a -> m) -> MigrationResult a -> m

#foldMap' :: Monoid m => (a -> m) -> MigrationResult a -> m

#foldr :: (a -> b -> b) -> b -> MigrationResult a -> b

#foldr' :: (a -> b -> b) -> b -> MigrationResult a -> b

#foldl :: (b -> a -> b) -> b -> MigrationResult a -> b

#foldl' :: (b -> a -> b) -> b -> MigrationResult a -> b

#foldr1 :: (a -> a -> a) -> MigrationResult a -> a

#foldl1 :: (a -> a -> a) -> MigrationResult a -> a

#toList :: MigrationResult a -> [a]

#null :: MigrationResult a -> Bool

#length :: MigrationResult a -> Int

#elem :: Eq a => a -> MigrationResult a -> Bool

#maximum :: Ord a => MigrationResult a -> a

#minimum :: Ord a => MigrationResult a -> a

#sum :: Num a => MigrationResult a -> a

#product :: Num a => MigrationResult a -> a

Traversable MigrationResult # 
Instance details

Defined in Database.PostgreSQL.Simple.Migration

Methods

#traverse :: Applicative f => (a -> f b) -> MigrationResult a -> f (MigrationResult b)

#sequenceA :: Applicative f => MigrationResult (f a) -> f (MigrationResult a)

#mapM :: Monad m => (a -> m b) -> MigrationResult a -> m (MigrationResult b)

#sequence :: Monad m => MigrationResult (m a) -> m (MigrationResult a)

Eq a => Eq (MigrationResult a) # 
Instance details

Defined in Database.PostgreSQL.Simple.Migration

Ord a => Ord (MigrationResult a) # 
Instance details

Defined in Database.PostgreSQL.Simple.Migration

Read a => Read (MigrationResult a) # 
Instance details

Defined in Database.PostgreSQL.Simple.Migration

Show a => Show (MigrationResult a) # 
Instance details

Defined in Database.PostgreSQL.Simple.Migration