leonardopliski / photonjs

Type-safe database client for TypeScript & Node.js (ORM replacement)

Type-safe database client for TypeScript & Node.js (ORM replacement)

Get started • Features • Docs • API • Workflow • Supported databases

---

Photon.js is an auto-generated database client that enables type-safe database access and reduces boilerplate. You can use it as an alternative to traditional ORMs such as Sequelize, TypeORM or Knex.js

It is part of the Prisma 2 ecosystem. Prisma 2 provides database tools for data access, declarative data modeling, schema migrations and visual data management. Learn more in the Prisma 2 announcement.

Note that Photon.js is currently running in Preview. A productionn-ready release is planned for Q1 2020.

Getting started

The easiest way to get started with Photon is by installing the Prisma 2 CLI and running the interactive init command:

npm install -g prisma2
prisma2 init hello-prisma

The interactive prompt will ask you to provide database credentials for your database. If you don't have a database yet, select SQLite and let the CLI set up a database file for you.

Learn more about the prisma2 init flow here.

Features

• Auto-generated database client
• Fully type-safe data access API (even for JavaScript), including:
  • Field selection, lazy/eager loading
  • Fluent API to traverse relations
  • Transactional nested writes and batching API
  • Relation filters (filter on JOINed tables)
  • Powerful methods for filtering, sorting and (cursor) pagination
• Declarative data modelling and migrations with Lift
• Connection pooling
• Works with existing databases using schema introspection
• CLI to support all major workflows
• Integrates seamlessly in your npm projects (without npm install)

Docs

You can find comprehensive documentation for Photon in the Prisma 2 docs.

API examples

Here are few example API calls:

import Photon from '@generated/photon'

const photon = new Photon()

async function main() {
  await photon.connect()

  const userById = await photon.users.findOne({ where: { id: 1 } })
  const userByEmail = await photon.users.findOne({ where: { email: "[e-mail]" }})

  const userWithPosts = await photon.users.findOne({
    where: { email: "[e-mail]" },
    include: { posts: { first: 10 } },
  })

  const newUser = await photon.users.create({ data: {
    name: "Alice",
    email: "[e-mail]",
  }})

  const newUserWithPosts = await photon.users.create({ data: {
    email: "[e-mail]",
    posts: {
      create: [
        { title: "Join us for Prisma Day. June 19, Berlin!" },
        { title: "Follow Prisma on Twitter!" },
      ]
    }
  }})

  const updatedUser = await photon.users.update({
    where: { email: "[e-mail]" },
    data: { role: "ADMIN" },
  })
}

main().catch(e => {
  console.error(e)
}).finally(async () => {
  await photon.disconnect()
})

Expand to the view the data model based on which the above Photon API was generated

datasource ds {
  // some data source config, e.g. SQLite, PostgreSQL, ...
}

generator photonjs {
  provider = "photonjs"
}

model User {
  id         Int       @id
  email      String    @unique
  name       String
  posts      Post[]
}

model Post {
  id          Int       @id
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
  draft       Boolean   @default(true)
  author      User
}

Learn more about the data model in the docs.

You can learn more about the Photon's API features on the website or in the API reference.

The Photon.js workflow

1. Configure data source

Specify the connection details for your database as a data source in your Prisma schema file. The connection details might differ per database, but most commonly you'll provide the following:

• Host: The IP address or domain name of the machine where your database server is running.
• Port: The port on which your database server is listening.
• User & password: Credentials for your database server.

Here is an example schema file that connects to a local PostgreSQL database:

// schema.prisma

datasource postgres {
  url      = "postgresql://user:password@localhost:5432"
  provider = "postgres"
}

generator photonjs {
  provider = "photonjs"
}

2. Define initial data model

The data model definition is a declarative and human-readable representation of your database schema. Here is the schema file from above extended with a sample data model:

// schema.prisma

datasource postgres {
  url      = "postgresql://user:password@localhost:5432"
  provider = "postgres"
}

generator photonjs {
  provider = "photonjs"
}

model User {
  id        Int      @id
  createdAt DateTime @default(now())
  email     String   @unique
  name      String?
  role      Role     @default(USER)
  posts     Post[]
}

model Post {
  id         Int        @id
  createdAt  DateTime   @default(now())
  updatedAt  DateTime   @updatedAt
  author     User
  title      String
  published  Boolean    @default(false)
}

enum Role {
  USER
  ADMIN
}

Read below to learn how you obtain it for your project.

Option A: Starting with an existing database (brownfield)

If you want to use Photon with an existing database, you can introspect your database schema using the Prisma 2 CLI. This generates a data model which is the foundation for the generated Photon API.

Option B: Start from scratch (greenfield)

When starting from scratch, you can simply write your own data model definition inside your schema file. You can then use Lift to migrate your database (Lift maps your data model definition to the schema of the underlying database).

3. Generate Photon.js

Generate your Photon database client using the Prisma 2 CLI:

prisma2 generate

Photon is generated based on the data model definition and provides a type-safe API with the following features:

• CRUD
• Filter, sorting and (cursor) pagination
• Field selection and eager loading
• Relations and transactions
• Raw database access

Photon.js gets generated into your node_modules folder so you can import it directly from '@generated/photon'. There's no need to install any additional dependencies or database drivers.

4. Build an app

Similar to traditional ORMs, the Photon.js client can be used any of your Node.js or TypeScript application. For example to implement REST, GraphQL or gRPC APIs. You can find reference examples for these use cases in the examples directory.

5. Evolve your database and Photon.js database client

As you build your app, you'll likely migrate your database to implement new features. Depending on how you obtained your initial data model and whether or not you're using Lift, there might be two ways for evolving your application going forward.

Option A: Without Lift

If you're not using Lift, you need to re-introspect your database (to update the generated datamodel) and re-generate the Photon.js client after each schema migration:

prisma2 introspect
prisma2 generate

Option B: With Lift

When using Lift, you need to re-generate the Photon.js client immediately after you performed a schema migration:

# adjust data model definition in schema.prisma
prisma2 lift save
prisma2 lift up
prisma2 generate

Supported databases

Photon.js can be used with the following databases:

• SQLite
• MySQL
• PostgreSQL
• MongoDB (coming very soon)

More databases that will be supported in the future are:

• MS SQL
• Oracle
• Neo4J
• FaunaDB
• ...

Contributing

Read more about how to contribute to Photon here