xomrk/raw-sql-skeleton.kt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[history/serdha] 'Update' -> 'Upgrade' and other minor naming and docs fixes

Browse Source
This commit is contained in:
Andrew Golovashevich 2025-01-03 14:40:00 +03:00
parent 30d3f9a8e4
commit c43c1a2b70
2 changed files with 94 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/CreateModuleScope.kt
View File

@ -26,7 +26,7 @@ public interface CreateModuleScope {
* @see CreateModuleScope.createTable
* @see CreateModuleScope.createSessionScopeTemporaryTable
* @see CreateModuleScope.createTransactionScopeTemporaryTable
* @see CreateModuleScope.UpdateTable
* @see UpgradeModuleScope.TableUpgrade
*/
public interface TableCreator<TableUserExtension : Any> {
/**
@ -38,7 +38,7 @@ public interface CreateModuleScope {
* @see CreateModuleScope.createTable
* @see CreateModuleScope.createSessionScopeTemporaryTable
* @see CreateModuleScope.createTransactionScopeTemporaryTable
* @see CreateModuleScope.UpdateTable
* @see UpgradeModuleScope.TableUpgrade
*/
public fun createTable(creator: ru.landgrafhomyak.serdha.api.v0.ddl.table.TableCreator<TableUserExtension>): TableUserExtension
}
@ -47,7 +47,7 @@ public interface CreateModuleScope {
* Creates table in [specified namespace][namespace] with [specified name][name] and stores it in the database.
* If table was created by previous synchronizations, asserts that table at the specified path in the database is same as table provided by [initializer].
*
* On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] this table must be [kept][CreateModuleScope.updateTable] (or [renamed][CreateModuleScope.renameTable]) or [deleted][CreateModuleScope.deleteTable].
* On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] this table must be [kept][UpgradeModuleScope.upgradeTable] (or [renamed][CreateModuleScope.renameTable]) or [deleted][CreateModuleScope.deleteTable].
*
* @param TableUserExtension User's type for containing table-related descriptors.
* @param namespace Way to group tables if there is a lot.
@ -97,7 +97,7 @@ public interface CreateModuleScope {
* Scope method that uses [creator] to create a query.
*
* @param creator Object with descriptor providers and factories.
* @return User's object with updated descriptors for future access.
* @return User's object with query-related descriptors for future access.
*
* @see CreateModuleScope.createSelectQuery
*/
@ -112,9 +112,25 @@ public interface CreateModuleScope {
* @param QueryUserWrapper User's type for containing query-related descriptors.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createTemporarySelectQuery
*/
public fun <QueryUserWrapper : Any> createSelectQuery(initializer: SelectQueryCreator<QueryUserWrapper>): Select<QueryUserWrapper>
/**
* Creates 'SELECT' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade].
* Using this function instead of [CreateModuleScope.createSelectQuery] may help the driver to optimize caches and runtime indexes.
*
* On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed.
*
* @param QueryUserWrapper User's type for containing query-related descriptors.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createSelectQuery
*/
public fun <QueryUserWrapper : Any> createTemporarySelectQuery(initializer: SelectQueryCreator<QueryUserWrapper>): Select<QueryUserWrapper>
/**
* Functional interface for creating 'INSERT ... VALUES' query.
*
@ -131,7 +147,7 @@ public interface CreateModuleScope {
*
* @param table Descriptor of table to which values will be inserted.
* @param creator Object with descriptor providers and factories.
* @return User's object with updated descriptors for future access.
* @return User's object with query-related descriptors for future access.
*
* @see CreateModuleScope.createInsertParamsQuery
*/
@ -147,9 +163,26 @@ public interface CreateModuleScope {
* @param QueryUserWrapper User's type for containing query-related descriptors.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createTemporaryInsertParamsQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createInsertParamsQuery(table: Table<TableUserExtension, *>, initializer: InsertParamsQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertParams<QueryUserWrapper>
/**
* Creates 'INSERT ... VALUES' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade].
* Using this function instead of [CreateModuleScope.createInsertParamsQuery] may help the driver to optimize caches and runtime indexes.
*
* On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed.
*
* @param TableUserExtension User's type with descriptors related to table to which values will be inserted.
* @param QueryUserWrapper User's type for containing query-related descriptors.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createInsertParamsQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createTemporaryInsertParamsQuery(table: Table<TableUserExtension, *>, initializer: InsertParamsQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertParams<QueryUserWrapper>
/**
* Functional interface for creating 'INSERT ... FROM' query.
*
@ -166,7 +199,7 @@ public interface CreateModuleScope {
*
* @param table Descriptor of table to which values will be inserted.
* @param creator Object with descriptor providers and factories.
* @return User's object with updated descriptors for future access.
* @return User's object with query-related descriptors for future access.
*
* @see CreateModuleScope.createInsertFromQueryQuery
*/
@ -181,9 +214,25 @@ public interface CreateModuleScope {
* @param TableUserExtension User's type with descriptors related to table to which values will be inserted.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createTemporaryInsertFromQueryQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createInsertFromQueryQuery(table: Table<TableUserExtension, *>, initializer: InsertFromQueryQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertFromQuery<QueryUserWrapper>
/**
* Creates 'INSERT ... FROM' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade].
* Using this function instead of [CreateModuleScope.createInsertFromQueryQuery] may help the driver to optimize caches and runtime indexes.
*
* On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed.
*
* @param TableUserExtension User's type with descriptors related to table to which values will be inserted.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createInsertFromQueryQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createTemporaryInsertFromQueryQuery(table: Table<TableUserExtension, *>, initializer: InsertFromQueryQueryCreator<TableUserExtension, QueryUserWrapper>): Insert.InsertFromQuery<QueryUserWrapper>
/**
* Functional interface for creating 'UPDATE' query.
*
@ -200,7 +249,7 @@ public interface CreateModuleScope {
*
* @param table Descriptor of table which rows will be updated.
* @param creator Object with descriptor providers and factories.
* @return User's object with updated descriptors for future access.
* @return User's object with query-related descriptors for future access.
*
* @see CreateModuleScope.createUpdateQuery
*/
@ -215,9 +264,25 @@ public interface CreateModuleScope {
* @param TableUserExtension User's type with descriptors related to table to which values will be inserted.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createTemporaryUpdateQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createUpdateQuery(table: Table<TableUserExtension, *>, initializer: UpdateQueryCreator<TableUserExtension, QueryUserWrapper>): Update<QueryUserWrapper>
/**
* Creates 'UPDATE' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade].
* Using this function instead of [CreateModuleScope.createUpdateQuery] may help the driver to optimize caches and runtime indexes.
*
* On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed.
*
* @param TableUserExtension User's type with descriptors related to table to which values will be inserted.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createUpdateQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createTemporaryUpdateQuery(table: Table<TableUserExtension, *>, initializer: UpdateQueryCreator<TableUserExtension, QueryUserWrapper>): Update<QueryUserWrapper>
/**
* Functional interface for creating 'DELETE' query.
*
@ -234,7 +299,7 @@ public interface CreateModuleScope {
*
* @param table Descriptor of table from which data will be deleted.
* @param creator Object with descriptor providers and factories.
* @return User's object with updated descriptors for future access.
* @return User's object with query-related descriptors for future access.
*
* @see CreateModuleScope.createDeleteQuery
*/
@ -249,9 +314,25 @@ public interface CreateModuleScope {
* @param TableUserExtension User's type with descriptors related to table from which data will be deleted.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createTemporaryDeleteQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createDeleteQuery(table: Table<TableUserExtension, *>, initializer: DeleteQueryCreator<TableUserExtension, QueryUserWrapper>): Delete<QueryUserWrapper>
/**
* Creates 'DELETE' query accessible only while the module is [creating][ModuleTemplate.ModuleCreator] or [updating][ModuleTemplate.ModuleUpgrade].
* Using this function instead of [CreateModuleScope.createDeleteQuery] may help the driver to optimize caches and runtime indexes.
*
* On [module upgrading][ModuleTemplate.CreateModuleTemplatesScope.upgradeTemplate] must be recreated if needed.
*
* @param TableUserExtension User's type with descriptors related to table from which data will be deleted.
* @param initializer Query-related descriptors initializer.
* @return Query descriptor.
*
* @see CreateModuleScope.createDeleteQuery
*/
public fun <TableUserExtension : Any, QueryUserWrapper : Any> createTemporaryDeleteQuery(table: Table<TableUserExtension, *>, initializer: DeleteQueryCreator<TableUserExtension, QueryUserWrapper>): Delete<QueryUserWrapper>
/**
* Replaces [specified namespace][rootNs] with schema provided by [template].
* [This namespace][rootNs] will be root namespace for module and shouldn't contain any other definitions.

10
src/commonMain/kotlin/ru/landgrafhomyak/serdha/api/v0/ddl/module/ModuleTemplate.kt
View File

@ -4,18 +4,18 @@ import ru.landgrafhomyak.serdha.api.v0.runtime.Transaction
public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> {
public interface Provider<UserExtension : Any> {
public fun createModuleTemplates(creator: CreateModuleTemplatesScope): UserExtension
public fun createModuleTemplates(scope: CreateModuleTemplatesScope): UserExtension
}
public interface CreateModuleTemplatesScope {
public fun <NewModuleUserExtension : Any> createTemplate(
versionKey: String,
updater: ModuleCreator<NewModuleUserExtension>,
creator: ModuleCreator<NewModuleUserExtension>,
): ModuleTemplate<NewModuleUserExtension>
public fun <OldModuleUserExtension : Any, NewModuleUserExtension : Any> upgradeTemplate(
versionKey: String,
updater: ModuleUpdater<OldModuleUserExtension, NewModuleUserExtension>,
upgrade: ModuleUpgrade<OldModuleUserExtension, NewModuleUserExtension>,
): ModuleTemplate<NewModuleUserExtension>
}
@ -25,8 +25,8 @@ public interface ModuleTemplate<@Suppress("unused") ModuleUserExtension : Any> {
public suspend fun initData(ext: ModuleUserExtension, transaction: Transaction) {}
}
public interface ModuleUpdater<OldModuleUserExtension : Any, NewModuleUserExtension : Any> {
public fun upgradeSchema(oldModule: Module<OldModuleUserExtension>, rootNs: Namespace, updater: CreateModuleScope): NewModuleUserExtension
public interface ModuleUpgrade<OldModuleUserExtension : Any, NewModuleUserExtension : Any> {
public fun upgradeSchema(oldModule: Module<OldModuleUserExtension>, rootNs: Namespace, upgrader: CreateModuleScope): NewModuleUserExtension
public suspend fun upgradeData(ext: NewModuleUserExtension, transaction: Transaction) {}
}