Exposed: Missing documentation

[MichaelKofler]

Exposed has a lot of potential and shows a very kotlin way to do databases, but without proper documentation it is simply too frustrating to learn. It's a waste of all the developer work that has gone into this project.
While the wiki examples are helpful, they cannot replace a more systematic reference of concepts, classes and methods. Also, some information is out of date (i.e. regarding handling of dates; it took me a day to find out I had to include exposed-java-time into build.gradle to use java 8 datetime classes).

[Tapac]

Thank you for your interest in Exposed. We already work on new documentation.
If you have something that you want to be highlighted in the documentation please share your thoughts.

[MichaelKofler]

libraries/build.gradle

At https://github.com/JetBrains/Exposed/wiki/LibDocumentation, add
exposed-java-time to Maven/Gradle listings and explain either exposed-jodatime
or exposed-java-time is to be used. I guess, the future is exposed-java-time?

Even better, place this information on:

https://github.com/JetBrains/Exposed/wiki/Getting-Started

Better still, give a more complete gradle-example like this:

repositories {
    // leave existing entries, add jcenter-Repository
    jcenter()
}
dependencies {
    // leave existing entries, add the following as needed

    // always
    compile "org.jetbrains.exposed:exposed-core:0.21.1"
    compile "org.jetbrains.exposed:exposed-dao:0.21.1"
    compile "org.jetbrains.exposed:exposed-jdbc:0.21.1"

    // for date/datetime with Java 8
    compile "org.jetbrains.exposed:exposed-java-time:0.21.1"

    // for date/datetime with Joda Time
    // compile "org.jetbrains.exposed:exposed-jodatime:0.21.1"

    // for SQLite
    compile "org.xerial:sqlite-jdbc:3.30.1"

    // for H2
    compile "com.h2database:h2:1.4.200"

    // for MySQL/MariaDB-Server
    compile "mysql:mysql-connector-java:5.1.48"

    // for other databases ...

    // for logging (StdOutSqlLogger) 
    compile "org.slf4j:slf4j-nop:1.7.30"
}

Connections

Explain connection management. If I understood it correct, the connection is
closed at the end of each transaction and reopened with the next
transaction??

Add a page with driver specific (connection) information. I only tested H2
and SQLite so far, MySQL/MariaDB to follow.

• H2 file: everything is fine

• H2 in-memory: needs parameter DB_CLOSE_DELAY=-1

• SQLite file: needs

  TransactionManager.manager.defaultIsolationLevel = 
    Connection.TRANSACTION_SERIALIZABLE
  

• SQLite in-memory: not useable, because connection is closed (and all data
  lost) with each transaction. (Is there a way around?)

Data types, schema creation with DAO

More details needed at https://github.com/JetBrains/Exposed/wiki/DataTypes,
i.e. for date/time and UUID handling. Type double is missing.

https://github.com/JetBrains/Exposed/wiki/DAO: primaryKey() used in
first example is deprecated. Should probably be:

override val primaryKey = PrimaryKey(id)

Table/IntIdTable singleton: short reference/explanation of column setup methods
like check, clientDefault/default/defaultExpression/defaultValueFun (???),
nullable, index, uniqueIndex etc.

---

Update 2020-03-05:

• What does flushCache in a transaction?

• IntelliJ problem (?): When I use exposed-java-time, IntelliJ
  cannot find the imports for datetime and CurrentDateTime. I
  have to import them manually. Importing date works, however.
  Perhaps recommend:

import org.jetbrains.exposed.sql.`java-time`.*

---

PS: In case you wonder, I am currently writing a book on Kotlin (in german
language). I plan to include a chapter on Exposed. If it is helpful, I can add
more documentation wishes in this issue later.

[AliLozano]

Hi @Tapac, I was looking for how can make pull request to Wiki, and I found this: https://www.growingwiththeweb.com/2016/07/enabling-pull-requests-on-github-wikis.html

Can you enable it?.

I was wanting to add this:

---

## Multiple Table Inheritance (Same table)

Declaring a AbstractTable that can override table name

```kotlin
abstract class AbstractTable : Table() {
lateinit var table: Table
override val tableName: String
get() = table.tableName

operator fun invoke(table: Table) {
    this.table = table
    val columns = table.columns as MutableList<Column<*>>
    columns.addAll(this.columns)
}

}
```

Create interfaces(for delegated classes) and implementation parents

interface AuditTable {
    val AuditTable: AbstractTable

    companion object {
        private class Extend : AbstractTable(), AuditTable {
            override val AuditTable get() = this

            override val createdAt = datetime("createdAt").clientDefault { DateTime.now() }
            override val modifiedAt = datetime("modifiedAt").clientDefault { DateTime.now() }
            override val createdBy = reference("createdBy", AccountTable)
            override val modifiedBy = reference("modifiedBy", AccountTable)

        }
        operator fun invoke() = Extend() as AuditTable
    }

    val createdAt: Column<DateTime>
    val modifiedAt: Column<DateTime>
    val createdBy: Column<EntityID<UUID>>
    val modifiedBy: Column<EntityID<UUID>>
}

interface SoftTable {
    val SoftTable: AbstractTable

    companion object {
        private class Extend : AbstractTable(), SoftTable {
            override val SoftTable get() = this
            override val isDeleted = bool("isDeleted").default(false)

        }
        operator fun invoke() = Extend() as SoftTable
    }

    val isDeleted: Column<Boolean>
}

Use delegate classes for add every parent column to the table.

object AccountTable: UUIDTable() {
    val name = varchar("name", 100)
}
object BookTable: UUIDTable(), SoftTable by SoftTable(), AuditTable by AuditTable() {
    val name = varchar("name", 100)

    init { SoftTable(this); AuditTable(this); } // register columns in BookTable
}

[Tapac]

Hi @AliLozano , sorry, but I can't enable wiki collaboration due to our security policy. I will think about how to workaround this, also thank you for your PR, I will try to include on a wiki.

[kortov]

@Tapac is your security policy concerned about the method AliLozano provided or about wiki collaboration itself? Because as a workaround you can keep wiki in this repo and push changes afterwards , I saw this method here https://github.com/rubenlagus/TelegramBots

Btw I don't like github wikis due it's hard to collaborate on, readmes or github pages are better sometimes

[Tapac]

@kortov , it's about public access to Exposed wiki. I will investigate the possibility to make a separate repo for wiki and setup the synhronozation.

We plan to improve documentation and get rid of github wiki.

[jlengrand]

That would be nice, I also am unable to propose documentation improvements for the same reason :) : https://github.com/JetBrains/Exposed/issues/824

[Tapac]

I have posted a short "how-to" for those who want to improve wiki. Feel free to share PRs.

[jlengrand]

Hey @Tapac , looks good! Thanks for taking the time to provide an alternative :).

I hope this way won't force too much manual work on you. Take care!

[martmists-gh]

IntelliJ problem (?): When I use exposed-java-time, IntelliJ
cannot find the imports for datetime and CurrentDateTime. I
have to import them manually. Importing date works, however.
Perhaps recommend:

Do you have a solution for joda-time too? I'm having the same issue

[Tapac]

@martmists , which Exposed and database versions do you use? Could you share a sample to reproduce?

[timatoe]

@AliLozano does the example of table inheritance you've posted work? Is it ready for others to follow?