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. The version available has severe limitations that make it unsuitable for production workloads, including missing features, limited performance and stability issues. We will address all these limitations before issuing a stable release later this year.
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.
- 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
- Data mapper ORM pattern
- 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
)
You can find comprehensive documentation for Photon in the Prisma 2 docs.
Here are few example API calls:
import Photon from '@generated/photon'
const photon = new Photon()
async function main() {
await photon.connect()
const userById = await prisma.users.findOne({ where: 1 })
const userByEmail = await prisma.users.findOne({ where: { email: "[email protected]" }})
const userWithPosts = await prisma.users.findOne({
where: { email: "[email protected]" },
include: { posts: { first: 10 } },
})
const newUser = await prisma.users.create({ data: {
name: "Alice",
email: "[email protected]",
}})
const newUser = await prisma.users.create({ data: {
email: "[email protected]",
posts: {
create: [
{ title: "Join us for Prisma Day. June 19, Berlin!" },
{ title: "Follow Prisma on Twitter!" },
]
}
}})
const updatedUser = await prisma.users.update({
where: { email: "[email protected]" },
data: { role: "ADMIN" },
})
await photon.disconnect()
}
main().catch(e => {
console.error(e)
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.
Specify the connection details for your database as a data source in your Prisma project 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 project file that connects to a local PostgreSQL database:
// project.prisma
datasource postgres {
url = "postgresql://user:password@localhost:5432"
provider = "postgres"
}
generator photonjs {
provider = 'photonjs'
}
The data model definition is a declarative and human-readable representation of your database schema. Here is the project file from above extended with a sample data model:
// project.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.
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.
When starting from scratch, you can simply write your own data model definition inside your project file. You can then use Lift to migrate your database (Lift maps your data model definition to the schema of the underlying database).
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.
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.
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.
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
When using Lift, you need to re-generate the Photon JS client immediately after you performed a schema migration:
# adjust data model definition in project.prisma
prisma2 lift save
prisma2 lift up
prisma2 generate
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
- ...