Get started • Features • Docs • API • Workflow • Supported databases
Specify the connection details for your database as a _data source_ in your [Prisma schema file](https://github.com/prisma/prisma2/blob/master/docs/prisma-schema-file.md). 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:
```groovy
// 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](https://github.com/prisma/prisma2/blob/master/docs/data-modeling.md#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:
```groovy
// 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](https://github.com/prisma/prisma2/blob/master/docs/introspection.md) your database schema using the [Prisma 2 CLI](https://github.com/prisma/prisma2/blob/master/docs/prisma-2-cli.md). This generates a [data model](https://github.com/prisma/prisma2/blob/master/docs/data-modeling.md#data-model-definition) 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](https://github.com/prisma/prisma2/blob/master/docs/data-modeling.md#data-model-definition) inside your [schema file](https://github.com/prisma/prisma2/blob/master/docs/prisma-schema-file.md). You can then use [Lift](https://github.com/prisma/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](https://github.com/prisma/prisma2/blob/master/docs/prisma-2-cli.md):
```sh
prisma2 generate
```
Photon is generated based on the [data model definition](https://github.com/prisma/prisma2/blob/master/docs/data-modeling.md#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`](./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](#2-define-initial-data-model) and whether or not you're using [Lift](https://github.com/prisma/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:
```sh
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:
```sh
# 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](https://github.com/prisma/photonjs/blob/master/CONTRIBUTING.md)
[](https://buildkite.com/prisma/photon)