@@ -133,6 +133,17 @@ instance Category Definition where
133133CREATE statements
134134-----------------------------------------}
135135
136+{- |
137+`createSchema` enters a new schema into the current database.
138+The schema name must be distinct from the name of any existing schema
139+in the current database.
140+
141+A schema is essentially a namespace: it contains named objects
142+(tables, data types, functions, and operators) whose names
143+can duplicate those of other objects existing in other schemas.
144+Named objects are accessed by `QualifiedAlias`es with the schema
145+name as a prefix.
146+-}
136147createSchema
137148 :: KnownSymbol sch
138149 => Alias sch
@@ -140,6 +151,7 @@ createSchema
140151createSchema sch = UnsafeDefinition $
141152 "CREATE" <+> "SCHEMA" <+> renderSQL sch <> ";"
142153
154+{- | Idempotent version of `createSchema`. -}
143155createSchemaIfNotExists
144156 :: (KnownSymbol sch, Has sch schemas schema)
145157 => Alias sch
@@ -537,7 +549,7 @@ instance RenderSQL OnUpdateClause where
537549DROP statements
538550-----------------------------------------}
539551
540−-- >>> :{
552+-- | >>> :{
541553-- let
542554-- definition :: Definition '["muh_schema" ::: schema, "public" ::: public] '["public" ::: public]
543555-- definition = dropSchema #muh_schema