goprisma

README

GoPrisma - a Go wrapper for the Prisma Engines

What's this?

Introspect a database and use it as a GraphQL API using Go.

Supported Databases:

• SQLite
• PostgreSQL
• MySQL
• MongoDB
• MS SQL Server

go get

go get github.com/jensneuse/goprisma

Introspect a database

prismaSchema := "datasource db {provider = \"postgresql\" url = \"postgresql://admin:admin@localhost:54321/example?schema=public&connection_limit=20&pool_timeout=5\"}"
schema, sdl, err := Introspect(prismaSchema)

Make a Query

query := "{\"query\": \"query Messages {findManymessages(take: 20 orderBy: [{id: desc}]){id message users {id name}}}","variables\": {}}"
engine, err := NewEngine(schema)
if err != nil {
	return
}
defer engine.Close()
response := engine.Execute(query)

Why?

GraphQL is a nice abstraction layer on top of other APIs. Making databases available can be a productivity gainer when no direct database access is required and GraphQL clients already exist in the codebase.

How does it work

Prisma is a really powerful ORM. If you look closely, you'll realize that internally, Prisma 2 is powered by a GraphQL Engine to abstract away the database layer.

The GraphQL Engine is written in Rust.

This library is a CGO wrapper to make the Prisma Rust GraphQL Engine available to write Go programs on top of it.

Is it fast?

I've measured ~0.3ms latency (Go -> Rust -> Database -> Go) on my laptop using a database in docker.

goos: darwin
goarch: amd64
pkg: github.com/jensneuse/goprisma/pkg/prisma
cpu: Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz
BenchmarkEngine_Execute
BenchmarkEngine_Execute-16    	   43815	    304507 ns/op	     144 B/op	       3 allocs/op
PASS

You can find the benchmark in the prisma package tests and run it yourself.

What architectures are supported?

• darwin x86_64
• darwin aarch64
• linux x86_64
• windows x86_64 (needs verification)

Other targets can be added.

Where is the Rust wrapper?

https://github.com/jensneuse/prisma-engines/tree/goprisma

Example / How to run the tests?

First, clone the repo.

cd docker-example
docker-compose up

Now you're able to run the tests.

How can you help?

Testing

You can help by running the tests and architectures that need verification. Please report any issues and tell me if it works.

Automate building the C-Wrapper

You might want to increase the level of trust by adding a github action to automate building the Rust C-Wrapper. Currently, I'm building it on my MacBook.

Ideally, this github action would fetch the latest stable of prisma-engines, compile the C-Wrapper and updates the lib folder via PR. A blueprint how to do this can be found here: https://github.com/rogchap/v8go/blob/master/.github/workflows/v8build.yml

If you're interested in adding this, please open a PR.

Considerations

It might be obvious, but I just want to make it clear that you should NOT publicly expose your database with this library. This is only intended for use cases where the GraphQL API is shielded by some other component.

Documentation

Overview

package prisma exposes a CGO wrapper around the prisma introspection- and query engine to make it available to go

Index

• func Introspect(schema string) (prismaSchema, prismaSDL string, err error)
• type Engine
  • func NewEngine(schema string) (*Engine, error)
  • func (e *Engine) Close()
  • func (e *Engine) Execute(query string) (string, error)

Functions

func Introspect

func Introspect(schema string) (prismaSchema, prismaSDL string, err error)

Types

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is holding a C pointer of the prisma engine created in Rust

func NewEngine

func NewEngine(schema string) (*Engine, error)

NewEngine requires a valid prisma schema with one db defined please read the prisma docs for further information

The returned Engine object contains a pointer to the prisma Rust engine the engine is already connected If you want to disconnect it, call Close()

You're able to configure the number of database connections in the connection pool, timeouts etc. by using standard prisma configuration More info here: https://www.prisma.io/docs/concepts/components/prisma-client/working-with-prismaclient/connection-pool

Do not forget to call Close() before the Engine struct goes out of scope, otherwise you have a memory leak!

func (*Engine) Close

func (e *Engine) Close()

Close disconnects the Rust prisma engine from the database and cleans up all structs and pointers on both sides of the bridge. If you forget to call Close before the Engine struct goes out of scope, you have a memory leak!

func (*Engine) Execute

func (e *Engine) Execute(query string) (string, error)

Execute takes a JSON encoded GraphQL query and executes it using the Rust prisma engine make sure to add an empty variables object to the query, otherwise the request will fail that said, variables are not supported by prisma, all values must be inlined into the query