Skip to content

Commit

Permalink
Merge branch 'main' into janpio/connetors-native-type-mapping
Browse files Browse the repository at this point in the history
  • Loading branch information
@jharrell
jharrell authored Nov 20, 2023
2 parents a8bbc1f + 781284c commit d5b9c70
Show file tree
Hide file tree
Showing 6 changed files with 99 additions and 44 deletions.
54 changes: 45 additions & 9 deletions content/100-getting-started/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,29 @@ metaDescription: 'Get started'

<TopBlock>

Welcome to the Prisma getting started section! 👋 Prisma is an [open source](https://github.com/prisma/prisma) next-generation ORM. It consists of the following parts:
Welcome to the Prisma getting started section! 👋

- [**Prisma Client**](/concepts/components/prisma-client): Auto-generated and type-safe query builder for Node.js & TypeScript
- [**Prisma Migrate**](/concepts/components/prisma-migrate): Migration tool to easily evolve your database schema from prototyping to production
- [**Prisma Studio**](/concepts/components/prisma-studio): GUI to view and edit data in your database
Explore our range of products defined to make working with data easy:

Prisma is also available on the [Prisma Data Platform](https://console.prisma.io), a cloud-based, collaborative environment for teams and organizations to develop type-safe applications. The platform focuses on developer productivity with GitHub integration for your code and schema, a visual data browser, an online query console, and an optional data proxy for handling database connections. For more information, refer to the Prisma Data Platform [documentation](/data-platform).
[**Prisma ORM**](/concepts/overview/what-is-prisma) is an [open source](https://github.com/prisma/prisma) next-generation database toolkit that helps with data modeling, data access, schema migrations and more.

For a more detailed breakdown of what problems Prisma solves and why it's **built to make you more productive**, see the [Why Prisma](/concepts/overview/why-prisma) section.
[**Prisma Accelerate**](/data-platform/accelerate/what-is-accelerate) is a global database cache with scalable connection pooling.

[**Prisma Pulse**](/data-platform/pulse/what-is-pulse) allows you to build reactive, real-time applications in a type-safe manner.

</TopBlock>

## Which tutorial is right for me?

To get up and running with Prisma in your local environment, follow our [Quickstart guide](./quickstart). It makes no assumptions about your knowledge level and offers the **fastest** way from install to query!
### Get started with Prisma ORM

To get up and running with Prisma in your local environment, follow our Quickstart guide It makes no assumptions about your knowledge level and offers the **fastest** way from install to query!

<ButtonLink color="dark" type="primary" href="./getting-started/quickstart">
Quickstart
</ButtonLink>

If you're looking to incorporate Prisma with an **existing project**, choose whether you want to use a SQL database or MongoDB:
If you're looking to incorporate Prisma with an **existing project**, choose whether you want to use a SQL database or MongoDB.

<ButtonLink
color="dark"
Expand All @@ -44,7 +46,7 @@ If you're looking to incorporate Prisma with an **existing project**, choose whe
Existing MongoDB project
</ButtonLink>

To learn how to **create a project** with Prisma from scratch, choose between SQL and MongoDB. Both tutorials will guide you through creating a project, connecting your database, and querying your data.
To learn how to **create a new project** with Prisma from scratch, choose between SQL and MongoDB. Both tutorials will guide you through creating a project, connecting your database, and querying your data.

<ButtonLink
color="dark"
Expand All @@ -62,6 +64,40 @@ To learn how to **create a project** with Prisma from scratch, choose between SQ
New MongoDB project
</ButtonLink>

If you're interested in learning how Prisma integrates with your favorite library or framework, such as Next.js, Express, Apollo GraphQL, NestJS, etc, you can check out our **ready-to-run examples**.

<ButtonLink
color="dark"
type="primary"
href="https://github.com/prisma/prisma-examples/"
>
Examples
</ButtonLink>

### Get started with Prisma Accelerate

Add **Accelerate** to your app to use connection pooling and global database caching.

<ButtonLink
color="dark"
type="primary"
href="/data-platform/accelerate/getting-started"
>
Get started with Accelerate
</ButtonLink>

### Get started with Prisma Pulse

Add **Pulse** to your app to subscribe to real-time updates from your database using Prisma Client.

<ButtonLink
color="dark"
type="primary"
href="/data-platform/pulse/getting-started"
>
Get started with Pulse
</ButtonLink>

## Prisma with different tooling

Prisma can be used with a wide range of tooling and frameworks, the following links outline how to get started with some of them:
Expand Down
2 changes: 1 addition & 1 deletion content/200-concepts/100-components/01-prisma-schema/03-generators.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,5 +95,5 @@ The following is a list of community created generators. If you want to create y
- [`prisma-generator-graphql-typedef`](https://github.com/mavvy22/prisma-generator-graphql-typedef): Generates graphql schema.
- [`prisma-markdown`](https://github.com/samchon/prisma-markdown): Generates markdown document composed with ERD diagrams and their descriptions. Supports pagination of ERD diagrams through `@namespace` comment tag.
- [`prisma-models-graph`](https://github.com/dangchinh25/prisma-models-graph): Generates a bi-directional models graph for schema without strict relationship defined in the schema, works via a custom schema annotation.
- [`https://github.com/luisrudge/prisma-generator-fake-data`](https://github.com/luisrudge/prisma-generator-fake-data): Generates realistic-looking fake data for your Prisma models that can be used in unit/integration tests, demos, and more.
- [`prisma-generator-fake-data`](https://github.com/luisrudge/prisma-generator-fake-data): Generates realistic-looking fake data for your Prisma models that can be used in unit/integration tests, demos, and more.

2 changes: 1 addition & 1 deletion content/200-concepts/100-components/03-prisma-migrate/150-db-push.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ The Prisma CLI has a dedicated command for prototyping schemas: [`db push`](/ref

> **Notes**:
>
> - `db push` does not interact with or rely on migrations. The migrations table will not be updated, and no migration files will be generated.
> - `db push` does not interact with or rely on migrations. The migrations table `_prisma_migrations` will not be created or updated, and no migration files will be generated.
> - When working with PlanetScale, we recommend that you use `db push` instead of `migrate`. For details refer to our Getting Started documentation, either [Start from scratch](/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-planetscale) or [Add to existing project](/getting-started/setup-prisma/add-to-existing-project/relational-databases-typescript-planetscale) depending on your situation.
</TopBlock>
Expand Down
60 changes: 43 additions & 17 deletions content/200-concepts/200-database-connectors/03-postgresql.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,23 +71,24 @@ postgresql://USER:PASSWORD@HOST:PORT/DATABASE?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE

The following arguments can be used:

| Argument name | Required | Default | Description |
| :----------------- | :------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema` | **Yes** | `public` | Name of the [schema](https://www.postgresql.org/docs/12/ddl-schemas.html) you want to use, e.g. `myschema` |
| `connection_limit` | No | `num_cpus * 2 + 1` | Maximum size of the [connection pool](/concepts/components/prisma-client/working-with-prismaclient/connection-pool) |
| `connect_timeout` | No | `5` | Maximum number of seconds to wait for a new connection to be opened, `0` means no timeout |
| `pool_timeout` | No | `10` | Maximum number of seconds to wait for a new connection from the pool, `0` means no timeout |
| `sslmode` | No | `prefer` | Configures whether to use TLS. Possible values: `prefer`, `disable`, `require` |
| `sslcert` | No | | Path of the server certificate. Certificate paths are [resolved relative to the `./prisma folder`](/concepts/components/prisma-schema/data-sources#securing-database-connections) |
| `sslidentity` | No | | Path to the PKCS12 certificate |
| `sslpassword` | No | | Password that was used to secure the PKCS12 file |
| `sslaccept` | No | `accept_invalid_certs` | Configures whether to check for missing values in the certificate. Possible values: `accept_invalid_certs`, `strict` |
| `host` | No | | Points to a directory that contains a socket to be used for the connection |
| `socket_timeout` | No | | Maximum number of seconds to wait until a single query terminates |
| `pgbouncer` | No | `false` | Configure the Engine to [enable PgBouncer compatibility mode](/guides/performance-and-optimization/connection-management/configure-pg-bouncer) |
| `application_name` | No | | Since 3.3.0: Specifies a value for the application_name configuration parameter |
| `channel_binding` | No | `prefer` | Since 4.8.0: Specifies a value for the channel_binding configuration parameter |
| `options` | No | | Since 3.8.0: Specifies command line options to send to the server at connection start |
| Argument name | Required | Default | Description |
| :--------------------- | :------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema` | **Yes** | `public` | Name of the [schema](https://www.postgresql.org/docs/12/ddl-schemas.html) you want to use, e.g. `myschema` |
| `connection_limit` | No | `num_cpus * 2 + 1` | Maximum size of the [connection pool](/concepts/components/prisma-client/working-with-prismaclient/connection-pool) |
| `connect_timeout` | No | `5` | Maximum number of seconds to wait for a new connection to be opened, `0` means no timeout |
| `pool_timeout` | No | `10` | Maximum number of seconds to wait for a new connection from the pool, `0` means no timeout |
| `sslmode` | No | `prefer` | Configures whether to use TLS. Possible values: `prefer`, `disable`, `require` |
| `sslcert` | No | | Path of the server certificate. Certificate paths are [resolved relative to the `./prisma folder`](/concepts/components/prisma-schema/data-sources#securing-database-connections) |
| `sslidentity` | No | | Path to the PKCS12 certificate |
| `sslpassword` | No | | Password that was used to secure the PKCS12 file |
| `sslaccept` | No | `accept_invalid_certs` | Configures whether to check for missing values in the certificate. Possible values: `accept_invalid_certs`, `strict` |
| `host` | No | | Points to a directory that contains a socket to be used for the connection |
| `socket_timeout` | No | | Maximum number of seconds to wait until a single query terminates |
| `pgbouncer` | No | `false` | Configure the Engine to [enable PgBouncer compatibility mode](/guides/performance-and-optimization/connection-management/configure-pg-bouncer) |
| `statement_cache_size` | No | `500` | Since 2.1.0: Specifies the number of [prepared statements](#prepared-statement-caching) cached per connection |
| `application_name` | No | | Since 3.3.0: Specifies a value for the application_name configuration parameter |
| `channel_binding` | No | `prefer` | Since 4.8.0: Specifies a value for the channel_binding configuration parameter |
| `options` | No | | Since 3.8.0: Specifies command line options to send to the server at connection start |

As an example, if you want to connect to a schema called `myschema`, set the connection pool size to `5` and configure a timeout for queries of `3` seconds. You can use the following arguments:

Expand Down Expand Up @@ -218,3 +219,28 @@ model Device {
data Unsupported("circle")
}
```

## Prepared statement caching

A [prepared statement](https://www.postgresql.org/docs/current/sql-prepare.html) is a feature that can be used to optimize performance. A prepared statement is parsed, compiled, and optimized only once and then can be executed directly multiple times without the overhead of parsing the query again.

By caching prepared statements, Prisma Client's [query engine](https://www.prisma.io/docs/concepts/components/prisma-engines/query-engine) does not repeatedly compile the same query which reduces database CPU usage and query latency.


For example, here is the generated SQL for two different queries made by Prisma Client:

```sql
SELECT * FROM user WHERE name = "John";
SELECT * FROM user WHERE name = "Brenda";
```

The two queries after parameterization will be the same, and the second query can skip the preparing step, saving database CPU and one extra roundtrip to the database. Query after parameterization:

```sql
SELECT * FROM user WHERE name = $1
```


Every database connection maintained by Prisma has a separate cache for storing prepared statements. The size of this cache can be tweaked with the `statement_cache_size` parameter in the connection string. By default, Prisma Client caches 500 statements per connection.

Due to the nature of pgBouncer, if the `pgbouncer` parameter is set to `true`, the prepared statement cache is automatically disabled for that connection.
4 changes: 2 additions & 2 deletions content/400-reference/200-api-reference/100-prisma-schema-reference.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -343,7 +343,7 @@ Defines a Prisma [model](/concepts/components/prisma-schema/data-model#defining-
#### Order of fields

- In version 2.3.0 and later, introspection lists model fields same order as the corresponding columns in the database. Relation fields are listed after scalar fields.
- In version 2.3.0 and later, introspection lists model fields in the same order as the corresponding columns in the database. Relation fields are listed after scalar fields.

### Examples

Expand Down Expand Up @@ -385,7 +385,7 @@ model User {
- Typically spelled in camelCase
- Must adhere to the following regular expression: `[A-Za-z][A-Za-z0-9_]*`

> **Note**: You can use the [`@map` attribute](#map) to map a field name (for example, `MyField`) to a column with a different name that does not match field naming conventions (for example, `myField`).
> **Note**: You can use the [`@map` attribute](#map) to [map a field name to a column](/concepts/components/prisma-client/working-with-prismaclient/use-custom-model-and-field-names) with a different name that does not match field naming conventions: e.g. `myField @map("my_field")`.
## <inlinecode>model</inlinecode> field scalar types

Expand Down
21 changes: 7 additions & 14 deletions content/400-reference/300-database-reference/03-supported-databases.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@ metaDescription: 'This page lists all the databases and their versions that are

<TopBlock>

Prisma currently supports the following databases:
Prisma currently supports the following databases.

</TopBlock>

## Self-hosted databases

| Database | Version |
| ---------------------------- | ------- |
Expand All @@ -30,6 +34,8 @@ Prisma currently supports the following databases:

## Managed databases

| Database | Version |
| ---------------------------- | ------- |
| PlanetScale | \* |
| AWS Aurora | \* |
| AWS Aurora Serverless &sup1; | \* |
Expand All @@ -43,18 +49,5 @@ An asterisk (\*) indicates that the version number is not relevant; either all v

&sup1; This does not include support for [Data API for Aurora Serverless](https://github.com/prisma/prisma/issues/1964).

</TopBlock>

<!--

## Preview

Support for the following databases is available as a Preview:

| Database | Version |
| ----------- | ------- |
| foo | \* |

-->

See also: [System requirements](/reference/system-requirements)

0 comments on commit d5b9c70

Please sign in to comment.