🥮 mooncakes.io

    moonckdb

    CockroachDB for moondb — the moonpostgres wire protocol, with the server's own capability report and version detection.

    cockroachdb
    postgres
    distributed
    sql
    driver
    database
    moondb
    moonbit
    Download zip
    Version
    0.0.1
    License
    Apache-2.0
    Repository
    Last updated
    20 hours ago
    Downloads
    9

    #moonckdb

    CockroachDB for moondb — the same wire protocol as PostgreSQL, the same AsyncDriver, and the one thing a query layer cannot learn from the bytes: which server it is talking to, and what that server does not implement.

    moon add moonbitstack/moonckdb

    async fn run() -> Unit raise {
      let db = @moonckdb.connect("127.0.0.1", 26257, "root", "", "defaultdb")
      let server = @moonckdb.server_of(db)          // Server::Cockroach, asked not assumed
      let plan = @moonckdb.capabilities_for(server) // notifications: false
      db.execute("CREATE TABLE hero (id INT PRIMARY KEY, name TEXT)", []) |> ignore
      db.close()
    }

    #Why this is a package and not a paragraph

    CockroachDB answers PostgreSQL's wire protocol, so moonpostgres already speaks to it — and this package does not contain a second protocol implementation. What it contains is the two questions the protocol cannot answer:

    • Which server is this? server_of(conn) runs SELECT version() and reads the sentence. CockroachDB reports CockroachDB CCL v24.3.0 (…); PostgreSQL reports PostgreSQL 16.4 …. A connection string that works for one may be pointed at the other, and a migration plan that assumes LISTEN works should know before it starts.
    • What does it lack? capabilities_for(Server::Cockroach) clears notifications. LISTEN and NOTIFY do not exist there — the server answers syntax error at or near"listen" — so a subscriber has to poll. Everything else the PostgreSQL driver offers does hold, which is why exactly one flag changes.

    #What holds, and what does not

    Verified against a real CockroachDB v24.3 in this repository's CI, by running the shared conformance matrix through this package's connect: connect, bind and read back every Value case, prepare and re-run, cursor, commit and rollback, savepoint, and the classification of two failures — 12 of 12, no skips.

    CockroachDB v24.3
    Extended query protocol, prepared statementsyes
    Binary result formatyes
    DECLARE / FETCH cursorsyes
    COPY in both directionsyes
    Savepointsyes
    RETURNINGyes
    LISTEN / NOTIFYno
    DROP TYPE … CASCADEno
    Multi-statement COPY … FROM in one query stringno (COPY together with other statements…)

    CockroachDB's SQL is otherwise its own: SERIAL vs INT GENERATED … AS IDENTITY, INTERLEAVE removed in v22, timezone and TIMESTAMPTZ rendering conventions, and information_schema coverage differences. Those are the server's documented dialect, not something a driver can paper over.

    #License

    Apache-2.0 © Leo Cheng.

    Server

    source
    pub(all) enum Server {
      Postgres
      Cockroach
    } derive(Eq)

    Which server is answering on the PostgreSQL wire. The two speak the same protocol and the same dialect, so nothing below this line can tell them apart; a query layer above it has to, because a server that accepts LISTEN and one that answers syntax error at or near "listen" fail in different places.

    Server::equal

    source
    fn Server::equal(Server, Server) -> Bool

    Comparing two server names is the whole point of naming them.

    Server::from_version

    source
    fn Server::from_version(version : String) -> Server

    The server a SELECT version() answer names. CockroachDB reports itself as CockroachDB CCL v24.3.0 (x86_64-…, built …), PostgreSQL as PostgreSQL 16.4 …, and a compatibility layer that borrows the string is still that layer.

    Server::name

    source
    fn Server::name(self : Server) -> String

    Server::not_equal

    source
    fn Server::not_equal(x : Server, y : Server) -> Bool

    Comparing two server names is the whole point of naming them.

    capabilities_for

    source
    fn capabilities_for(server : Server) -> 
    Capabilities

    What this server can do, as opposed to what the driver implements. [@moondb.Capabilities::for_dialect] describes the PostgreSQL implementation; CockroachDB is not PostgreSQL, and the difference that matters to a caller is notifications: LISTEN and NOTIFY do not exist there, so a query layer that plans to wait for a notification has to poll instead.

    The rest of the PostgreSQL surface does hold on CockroachDB — cursors, savepoints, COPY in both directions, RETURNING — which is why this clears one flag and not a row of them.

    connect

    source
    async fn connect(host : String, port : Int, user : String, password : String, database : String, tls? : 
    Client    ) -> 
    PgConn     raise 
    DbError

    Connect the way [@moonpostgres.PgConn::connect] does — the protocol is the same one, and there is nothing to translate.

    server_of

    source

    Which server is behind this connection, asked rather than assumed.

    version

    source

    The server's own version sentence, as it answered.

    Source Files