diff --git a/content/01-getting-started/03-setup-prisma/02-start-from-scratch-sql-migrations.mdx b/content/01-getting-started/03-setup-prisma/02-start-from-scratch-sql-migrations.mdx index 8a1d841795..2d66bf2f41 100644 --- a/content/01-getting-started/03-setup-prisma/02-start-from-scratch-sql-migrations.mdx +++ b/content/01-getting-started/03-setup-prisma/02-start-from-scratch-sql-migrations.mdx @@ -18,7 +18,7 @@ In order to successfully complete this guide, you need: Make sure your have your database [connection URL]() (includes your authentication credentials) at hand! -If you don't have a database server running and only want to explore Prisma, check out the [Quickstart](). +If you don't have a database server running and only want to explore Prisma, check out the [Quickstart](). Alternatively you can [setup a free PostgreSQL database on Heroku](https://dev.to/prisma/how-to-setup-a-free-postgresql-database-on-heroku-1dc1) and use it in this guide. ## Create project setup diff --git a/content/03-reference/01-tools-and-interfaces/02-prisma-client/20-database-polyfills.mdx b/content/03-reference/01-tools-and-interfaces/02-prisma-client/20-database-polyfills.mdx new file mode 100644 index 0000000000..7ede15a3f4 --- /dev/null +++ b/content/03-reference/01-tools-and-interfaces/02-prisma-client/20-database-polyfills.mdx @@ -0,0 +1,13 @@ +--- +title: "Database polyfills" +metaTitle: "" +metaDescription: "" +--- + +## Overview + +Prisma Client provides features that are typically not achievable with relational databases. These features are referred to as _polyfills_. + +- Initializing [ID]() values with `cuid` and `uuid` values (requires [Prisma Migrate]()) +- [Making 1-1-relations required on both sides]() +- [Implicit many-to-many relations]() diff --git a/content/03-reference/01-tools-and-interfaces/03-prisma-migrate/01-what-is-prisma-migrate.mdx b/content/03-reference/01-tools-and-interfaces/03-prisma-migrate/01-what-is-prisma-migrate.mdx new file mode 100644 index 0000000000..c883a49acd --- /dev/null +++ b/content/03-reference/01-tools-and-interfaces/03-prisma-migrate/01-what-is-prisma-migrate.mdx @@ -0,0 +1,213 @@ +--- +title: "What is Prisma Migrate" +metaTitle: "" +metaDescription: "" +--- + +## Overview + +Prisma Migrate is a tool that lets you _change your database schema_, e.g. by creating new tables or adding columns to existing tables. These changes are called _schema migrations_. Prisma Migrate is available as part of the [Prisma CLI]() via the `prisma migrate` command. + +**Prisma Migrate is currently in an experimental state.** This means that it is not recommended to use Prisma Migrate in production. Instead, you can perform schema migrations using plain SQL or another migration tool of your choice and then bring the changes into your Prisma schema using [introspection](). + +## Prisma Migrate vs SQL migrations + +Prisma Migrate is a _declarative_ migration system, as opposed to SQL which can be considered _imperative_: + +- **SQL (imperative)**: Provide the individual _steps_ to get from the current schema to the desired schema. +- **Prisma Migrate (delarative)**: Define the desired schema as a [Prisma data model]() (Prisma Migrate takes care of generating the necessary _steps_). + +Here's a quick comparison. Assume you have the following scenario: + +1. You need to create `User` table to store user information (name, email, ...) +1. Create two new tables `Post` and `Profile` with foreign keys to `User` +1. Add a new column with default value to the `Post` table + +### SQL + +In SQL, you'd have to send three subsequent SQL statements to account for this scenario: + +**1. Create `User` table to store user information (name, email, ...)** + +```sql +CREATE TABLE "User" ( + id SERIAL PRIMARY KEY, + name VARCHAR(255), + email VARCHAR(255) NOT NULL +); +``` + +**2. Create two new tables `Post` and `Profile` with foreign keys to `User`** + +```sql +CREATE TABLE "Profile" ( + id SERIAL PRIMARY KEY, + bio TEXT NOT NULL, + "user" integer NOT NULL UNIQUE, + FOREIGN KEY ("user") REFERENCES "User"(id) +); +CREATE TABLE "Post" ( + id SERIAL PRIMARY KEY, + title VARCHAR(255) NOT NULL, + author integer NOT NULL, + FOREIGN KEY (author) REFERENCES "User"(id) +); +``` + +**3. Add a new column with default value to the `Post` table** + +```sql +ALTER TABLE "Post" +ADD COLUMN published BOOLEAN DEFAULT false; +``` + +### Prisma Migrate + +With Prisma Migrate, you write the desired database schema in the form of a [Prisma data model]() inside your [Prisma schema file](). To map the data model to your database schema, you then have to run these two commands: + +``` +prisma migrate save --experimental +prisma migrate up --experimental +``` + +The first command _saves_ a new migration to the file system and updates the [`_Migration`]() table. It stores information about the migration in a dedicated directory inside the [`migrations`]() directory. Each migration that is stored has its own `README.md` file which contains detailled information about the migration (e.g. the generated SQL statements which will be executed when you run `prisma migrate up`). + +The second command _executes_ the migration against your database. + +**1. Create `User` table to store user information (name, email, ...)** + +Add a model to your Prisma schema: + +```prisma +model User { + id Int @id @default(autoincrement()) + name String? + email String @unique +} +``` + +Now run the two commands mentioned above: + +``` +prisma migrate save --experimental +prisma migrate up --experimental +``` + +**2. Create two new tables `Post` and `Profile` with foreign keys to `User`** + +Add two models with [relation fields]() to your Prisma schema: + +```prisma +model User { + id Int @id @default(autoincrement()) + name String? + email String @unique + posts Post[] + profile Profile? +} + +model Profile { + id Int @id @default(autoincrement()) + bio String + user User +} + +model Post { + id Int @id @default(autoincrement()) + title String + author User +} +``` + +Notice that in addition to the [relation fields which represent the foreign keys](), you also must specify the [virtual relation fields]() on the other side of the relation. + +Now run the two commands mentioned above: + +``` +prisma migrate save --experimental +prisma migrate up --experimental +``` + +**3. Add a new column with default value to the `Post` table** + +Add a [field]() to the `Post` model: + +```prisma +model User { + id Int @id @default(autoincrement()) + name String? + email String @unique + posts Post[] + profile Profile? +} + +model Profile { + id Int @id @default(autoincrement()) + bio String + user User +} + +model Post { + id Int @id @default(autoincrement()) + title String + published Boolean @default(false) + author User +} +``` + +Now run the two commands mentioned above: + +``` +prisma migrate save --experimental +prisma migrate up --experimental +``` + +## Supported operations + +The following table shows which SQL operations are currently supported by Prisma Migrate. If an operation is not yet supported, it links to a workaround that uses plain SQL and [introspection]() to enable this feature in Prisma Client. + +| Operation | SQL | Supported | +| :---------------------------------- | :------------------------------ | :----------------------: | +| Create a new table | `CREATE TABLE` | ✔️ | +| Rename an existing table | `ALTER TABLE` + `RENAME` | Not yet ([workaround]()) | +| Delete an existing table | `DROP TABLE` | ✔️ | +| Add a column to an existing table | `ALTER TABLE` + `ADD COLUMN` | ✔️ | +| Rename an existing column | `ALTER TABLE` + `RENAME COLUMN` | Not yet ([workaround]()) | +| Delete an existing column | `ALTER TABLE` + `DROP COLUMN` | ✔️ | +| Set primary keys ([IDs]()) | `PRIMARY KEY` | ✔️ | +| Define [relations]() (foreign keys) | `FOREIGN KEY` + `REFERENCES` | ✔️ | +| Make columns [optional/required]() | `NOT NULL` | ✔️ | +| Set [unique constraints]() | `UNIQUE` | ✔️ | +| Set [default]() values | `DEFAULT` | ✔️ | +| Defining [enums]() | `ENUM` | ✔️ | +| Create [indexes]() | `CREATE INDEX` | ✔️ | +| Cascading deletes | `ON DELETE` | Not yet ([workaround]()) | +| Cascading updates | `ON UPDATE` | Not yet ([workaround]()) | +| Data validation | `CHECK` | Not yet ([workaround]()) | + +Note that this table assumes that the operation is also supported by the underlying database. For example, `ENUM` is not supported in SQLite, this means that you also can't use `enum` using Prisma Migrate. + +## Polyfills + +Prisma Migrate provides features that are typically not achievable with relational databases. These features are referred to as _polyfills_. + +- Initializing [ID]() values with `cuid` and `uuid` values (requires [Prisma Migrate]()) +- [Making 1-1-relations required on both sides]() +- [Implicit many-to-many relations]() + +## Migration history + +Prisma Migrate stores the migration history of your project in two places: + +- A directory called `migrations` on your file system +- A table called `_Migrations` in your database + +### The `migrations` directory + +The `migrations` directory stores information about the migrations that have been or will be executed against your database. You should never make any manual changes to the files in `migrations`, the only way to change the content of this directory should be using the `prisma migrate save` command. + +The `migrations` directory should be checked into version control (e.g. Git). + +### The `_Migrations` table + +The `_Migrations` table additionally stores information about each migration that was ever executed against the database by Prisma Migrate. \ No newline at end of file diff --git a/content/03-reference/01-tools-and-interfaces/03-prisma-migrate/migration-scenarios.mdx b/content/03-reference/01-tools-and-interfaces/03-prisma-migrate/migration-scenarios.mdx deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/content/03-reference/01-tools-and-interfaces/03-prisma-migrate/what-is-prisma-migrate.mdx b/content/03-reference/01-tools-and-interfaces/03-prisma-migrate/what-is-prisma-migrate.mdx deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/content/03-reference/02-database-connectors/01-postgresql.mdx b/content/03-reference/02-database-connectors/01-postgresql.mdx index e73dd09535..042ff4e2b9 100644 --- a/content/03-reference/02-database-connectors/01-postgresql.mdx +++ b/content/03-reference/02-database-connectors/01-postgresql.mdx @@ -4,4 +4,208 @@ metaTitle: '' metaDescription: '' --- -Coming 🔜 +## Overview + +The PostgreSQL data source connector connects Prisma to a [PostgreSQL]() database server. + +## Example + +To connect to a PostgreSQL database server, you need to configure a [`datasource`]() block in your [Prisma schema file](): + +```prisma +datasource postgresql { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` + +The fields passed to the `datasource` block are: + +- `provider`: Specifies the `postgresql` data source connector. +- `url`: Specifies the [connection URL](#connection-url) for the PostgreSQL database server. In this case, an [environment variable is used]() to provide the connection URL. + +## Connection details + +### Connection URL + +Prisma follows the [official PostgreSQLl format](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) for connection URLs. Here's an overview of the components needed for a PostgreSQL connection URL: + +![](https://imgur.com/ZMzozDQ.png) + +**Base URL and path** + +Here is an example of the structure of the _base URL_ and the _path_ using placeholder values in uppercase letters: + +``` +postgresql://USER:PASSWORD@HOST:PORT/DATABASE +``` + +The following components make up the _base URL_ of your database, they are always required: + +| Name | Placeholder | Description | +| :------- | :---------- | :---------------------------------------------------------- | +| Host | `HOST` | IP address/domain of your database server, e.g. `localhost` | +| Port | `PORT` | Port on which your database server is running, e.g. `5432` | +| User | `USER` | Name of your database user, e.g. `janedoe` | +| Password | `PASSWORD` | Password for your database user | +| Database | `DATABASE` | Name of the [database]() you want to use, e.g. `mydb` | + +**Arguments** + +A connection URL can also take arguments. Here is the same example from above with placeholder values in uppercase letters for three _arguments_: + +``` +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` | Mame of the schema you want to use, e.g. `myschema` | +| `connection_limit` | No | `num_cpus * 2 + 1` | Maximum size of the [connection pool]() | +| `connect_timeout` | No | `5` | Maximum number of seconds to wait for a new connection | +| `socket_timeout` | No | `5` | Maximum number of seconds to wait until a single query terminates | +| `sslmode` | No | `prefer` | Configures whether to use TLS, possible values: `prefer`, `disable`, `require` | +| `sslcert` | No | | Path the the server certificate | +| `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 | +| `host` | No | | Points to a directory that contains a socket to be used for the connection | + +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: + +``` +postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=myschema&connection_limit=5&socket_timeout=3 +``` + +### Configuring an SSL connection + +You can add various parameters to the connection string if your database server uses SSL. Here's an overview of the possible parameters: + +- `sslmode=(disable|prefer|require)`: + - `prefer` (default): Prefer TLS if possible, accept plain text connections. + - `disable`: Do not use TLS. + - `require`: Require TLS or fail if not possible. +- `sslcert=`: Path the the server certificate. This is the root certificate used by the database server to sign the client certificate. You need to provide this if the certificate doesn't exist in the trusted certificate store of your system. For Google Cloud this likely is `server-ca.pem`. +- `sslidentity=`: Path to the PKCS12 certificate database created from client cert and key. This is the SSL identity file in PKCS12 format which you will generate using the client key and client certificate. It combines these two files in a single file and secures them via a password (see next parameter). You can create this file using your client key and client certificate by using the following command (using `openssl`): + ``` + openssl pkcs12 -export -out client-identity.p12 -inkey client-key.pem -in client-cert.pem + ``` +- `sslpassword=`: Password that was used to secure the PKCS12 file. The `openssl` command listed in the previous step will ask for a password while creating the PKCS12 file, you will need to provide that same exact password here. +- `sslaccept=(strict|accept_invalid_certs)`: + - `strict`: Any missing value in the certificate will lead to an error. For Google Cloud, especially if the database doesn't have a domain name, the certificate might miss the domain/IP address, causing an error when connecting. + - `accept_invalid_certs` (default): Bypass this check. Be aware of the security consequences of this setting. + +To recap, in order to create a SSL connection to your database, you need: + +- A root [CA]() file +- A [PKCS12](https://en.wikipedia.org/wiki/PKCS_12) client file +- A [PKCS12](https://en.wikipedia.org/wiki/PKCS_12) password + +Your database connection URL will look similar to this: + +``` +postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=client-identity.p12&sslpassword=mypassword&sslcert=rootca.cert +``` + +### Connecting via sockets + +To connect to your PostgreSQL database via sockets, you must add a `host` field as a _query parameter_ to the connection string (instead of setting it as the `host` part of the URI). +The value of this parameter then must point to the directory that contains the socket, e.g.: `postgresql://USER:POST@localhost/database?host=/var/run/postgresql/` + +Note that `localhost` is required, the value itself is ignored and can be anything. + +> **Note**: You can find additional context in this [GitHub issue](https://github.com/prisma/prisma-client-js/issues/437#issuecomment-592436707). + +## Type mapping between PostgreSQL to Prisma schema + +The PostgreSQL connector maps the [scalar types]() from the Prisma [data model]() as follows to native column types: + +### Prisma Migrate + +| Prisma | PostgreSQL | +| ---------- | ----------- | +| `String` | `text` | +| `Boolean` | `boolean` | +| `Int` | `integer` | +| `Float` | `real` | +| `Datetime` | `timestamp` | + +### Introspection + +When introspecting a PostgreSQL database, the database types are mapped to Prisma according to the following table: + +| PostgreSQL | Prisma | Supported | +| ------------------------------------------- | ---------- | :-------: | +| `smallint` \| `int2` | `Int` | ✔️ | +| `integer` \| `int`, `int4` | `Int` | ✔️ | +| `bigint` \| `int8` | `Int` | ✔️ | +| `numeric(p,s)` \| `decimal(p,s)` | `Float` | ✔️ | +| `real` \| `float`, `float4` | `Float` | ✔️ | +| `double precision` \| `float8` | `Float` | ✔️ | +| `smallserial` \| `serial2` | `Int` | ✔️ | +| `serial` \| `serial4` | `Int` | ✔️ | +| `bigserial` \| `serial8` | `Int` | ✔️ | +| `money` | `Float` | ✔️ | +| `character(n)` \| `char(n)` | `String` | ✔️ | +| `character varying(n)` \| `varchar(n)` | `String` | ✔️ | +| `text` | `String` | ✔️ | +| `timestamp with time zone` \| `timestamptz` | `DateTime` | ✔️ | +| `date` | `DateTime` | ✔️ | +| `time without time zone` \| `time` | `DateTime` | ✔️ | +| `time with time zone` \| `timetz` | `DateTime` | ✔️ | +| `boolean` \| `bool` | `Bool` | ✔️ | +| `enum` | `Enum` | ✔️ | +| `inet` | `String` | ✔️ | +| `bit(n)` | `String` | ✔️ | +| `bit varying(n)` | `String` | ✔️ | +| `uuid` | `String` | ✔️ | +| `json` | `String` | ✔️ | +| `jsonb` | `String` | ✔️ | +| Array types | `[]` | ✔️ | +| `interval` | `String` | Not yet | +| `cidr` | `String` | Not yet | +| `macaddr` | `String` | Not yet | +| `tsvector` | `String` | Not yet | +| `tsquery` | `String` | Not yet | +| `oid` | `Int` | Not yet | +| `int4range` | `String` | Not yet | +| `int8range` | `String` | Not yet | +| `numrange` | `String` | Not yet | +| `tsrange` | `String` | Not yet | +| `tstzrange` | `String` | Not yet | +| `daterange` | `String` | Not yet | +| `xml` | n/a | Not yet | +| `bytea` | n/a | Not yet | +| `point` | n/a | Not yet | +| `line` | n/a | Not yet | +| `lseg` | n/a | Not yet | +| `box` | n/a | Not yet | +| `path` | n/a | Not yet | +| `polygon` | n/a | Not yet | +| `circle` | n/a | Not yet | +| Composite types | n/a | Not yet | +| Domain types | n/a | Not yet | + +During [introspection](), fields with types that **already have match in the Prisma schema but are not yet supported** will be added to the Prisma schema as comments, e.g. `macaddr` would be added to a model as follows: + +```prisma +model Device { + id Int @id @default(autoincrement()) + name String +// This type is currently not supported. +// mac String +} +``` + +Fields with types that **do not yet have match in the Prisma schema (and are not yet supported)** will be also be added as comments to the Prisma schema as comments using the PostgreSQL type, e.g. `macaddr` would be added to a model as follows: + +```prisma +model Device { + id Int @id @default(autoincrement()) + name String +// This type is currently not supported. +// data xml +} +``` \ No newline at end of file diff --git a/content/03-reference/02-database-connectors/02-mysql.mdx b/content/03-reference/02-database-connectors/02-mysql.mdx index 0bb0450394..102b3a5002 100644 --- a/content/03-reference/02-database-connectors/02-mysql.mdx +++ b/content/03-reference/02-database-connectors/02-mysql.mdx @@ -1,7 +1,200 @@ --- + title: 'MySQL' metaTitle: '' metaDescription: '' --- -Coming 🔜 +## Overview + +The MySQL data source connector connects Prisma to a [MySQL]() database server. + +## Example + +To connect to a MySQL database server, you need to configure a [`datasource`]() block in your [Prisma schema file](): + +```prisma +datasource mysql { + provider = "mysql" + url = env("DATABASE_URL") +} +``` + +The fields passed to the `datasource` block are: + +- `provider`: Specifies the `mysql` data source connector. +- `url`: Specifies the [connection URL](#connection-url) for the MySQL database server. In this case, an [environment variable is used]() to provide the connection URL. + +## Connection details + +### Connection URL + +Here's an overview of the components needed for a MySQL connection URL: + +![](![](https://imgur.com/NswjbsP.png) + +**Base URL and path** + +Here is an example of the structure of the _base URL_ and the _path_ using placeholder values in uppercase letters: + +``` +mysql://USER:PASSWORD@HOST:PORT/DATABASE +``` + +The following components make up the _base URL_ of your database, they are always required: + +| Name | Placeholder | Description | +| :------- | :---------- | :---------------------------------------------------------- | +| Host | `HOST` | IP address/domain of your database server, e.g. `localhost` | +| Port | `PORT` | Port on which your database server is running, e.g. `5432` | +| User | `USER` | Name of your database user, e.g. `janedoe` | +| Password | `PASSWORD` | Password for your database user | +| Database | `DATABASE` | Name of the [database]() you want to use, e.g. `mydb` | + +**Arguments** + +A connection URL can also take arguments. Here is the same example from above with placeholder values in uppercase letters for three _arguments_: + +``` +mysql://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` | Mame of the schema you want to use, e.g. `myschema` | +| `connection_limit` | No | `num_cpus * 2 + 1` | Maximum size of the [connection pool]() | +| `connect_timeout` | No | `5` | Maximum number of seconds to wait for a new connection | +| `socket_timeout` | No | `5` | Maximum number of seconds to wait until a single query terminates | +| `sslmode` | No | `prefer` | Configures whether to use TLS, possible values: `prefer`, `disable`, `require` | +| `sslcert` | No | | Path the the server certificate | +| `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 | +| `host` | No | | Points to a directory that contains a socket to be used for the connection | + +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: + +``` +mysql://USER:PASSWORD@HOST:PORT/DATABASE?schema=myschema&connection_limit=5&socket_timeout=3 +``` + +### Configuring an SSL connection + +You can add various parameters to the connection string if your database server uses SSL. Here's an overview of the possible parameters: + +- `sslmode=(disable|prefer|require)`: + - `prefer` (default): Prefer TLS if possible, accept plain text connections. + - `disable`: Do not use TLS. + - `require`: Require TLS or fail if not possible. +- `sslcert=`: Path the the server certificate. This is the root certificate used by the database server to sign the client certificate. You need to provide this if the certificate doesn't exist in the trusted certificate store of your system. For Google Cloud this likely is `server-ca.pem`. +- `sslidentity=`: Path to the PKCS12 certificate database created from client cert and key. This is the SSL identity file in PKCS12 format which you will generate using the client key and client certificate. It combines these two files in a single file and secures them via a password (see next parameter). You can create this file using your client key and client certificate by using the following command (using `openssl`): + ``` + openssl pkcs12 -export -out client-identity.p12 -inkey client-key.pem -in client-cert.pem + ``` +- `sslpassword=`: Password that was used to secure the PKCS12 file. The `openssl` command listed in the previous step will ask for a password while creating the PKCS12 file, you will need to provide that same exact password here. +- `sslaccept=(strict|accept_invalid_certs)`: + - `strict`: Any missing value in the certificate will lead to an error. For Google Cloud, especially if the database doesn't have a domain name, the certificate might miss the domain/IP address, causing an error when connecting. + - `accept_invalid_certs` (default): Bypass this check. Be aware of the security consequences of this setting. + +To recap, in order to create a SSL connection to your database, you need: + +- A root [CA]() file +- A [PKCS12](https://en.wikipedia.org/wiki/PKCS_12) client file +- A [PKCS12](https://en.wikipedia.org/wiki/PKCS_12) password + +Your database connection URL will look similar to this: + +``` +mysql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=client-identity.p12&sslpassword=mypassword&sslcert=rootca.cert +``` + +### Connecting via sockets + +To connect to your MySQL database via sockets, you must add a `host` field as a _query parameter_ to the connection string (instead of setting it as the `host` part of the URI). +The value of this parameter then must point to the directory that contains the socket, e.g.: `mysql://USER:POST@localhost/database?host=/var/run/mysql/` + +Note that `localhost` is required, the value itself is ignored and can be anything. + +> **Note**: You can find additional context in this [GitHub issue](https://github.com/prisma/prisma-client-js/issues/437#issuecomment-592436707). + +## Type mapping between MySQL to Prisma schema + +The MySQL connector maps the [scalar types]() from the Prisma [data model]() as follows to native column types: + +### Prisma Migrate + +| Data model | MySQL | +| -------- | --------- | +| `String` | `TEXT` | +| `Boolean` | `BOOLEAN` | +| `Int` | `INT` | +| `Float` | `FLOAT` | +| `Datetime` | `TIMESTAMP` | + +### Introspection + +When introspecting a MySQL database, the database types are mapped to Prisma according to the following table: + +| MySQL | Prisma | Supported | +| ------------------------- | ---------- | --------- | +| `smallint` | `Int` | ✔️ | +| `int` | `Int` | ✔️ | +| `bigint` | `Int` | ✔️ | +| `decimal` | `Float` | ✔️ | +| `float` | `Float` | ✔️ | +| `double` | `Float` | ✔️ | +| `bit` | `Int` | ✔️ | +| `boolean` \| `tinyint(1)` | `Boolean` | ✔️ | +| `date` | `DateTime` | ✔️ | +| `datetime` | `DateTime` | ✔️ | +| `timestamp` | `DateTime` | ✔️ | +| `time` | `DateTime` | ✔️ | +| `year` | `Int` | ✔️ | +| `char` | `String` | ✔️ | +| `varchar` | `String` | ✔️ | +| `tinytext` | `String` | ✔️ | +| `text` | `String` | ✔️ | +| `mediumtext` | `String` | ✔️ | +| `longtext` | `String` | ✔️ | +| `enum` | `Enum` | ✔️ | +| `json` | `String` | ✔️ | +| `varbinary` | `String` | Not yet | +| `tinyblob` | `String` | Not yet | +| `mediumblob` | `String` | Not yet | +| `blob` | `String` | Not yet | +| `binary` | | Not yet | +| `set` | | Not yet | +| `geometry` | | Not yet | +| `point` | | Not yet | +| `linestring` | | Not yet | +| `polygon` | | Not yet | +| `multipoint` | | Not yet | +| `multilinestring` | | Not yet | +| `multipolygon` | | Not yet | +| `geometrycollection` | | Not yet | + + + +During [introspection](), fields with types that **already have match in the Prisma schema but are not yet supported** will be added to the Prisma schema as comments, e.g. `macaddr` would be added to a model as follows: + +```prisma +model Device { + id Int @id @default(autoincrement()) + name String +// This type is currently not supported. +// mac String +} +``` + +Fields with types that **do not yet have match in the Prisma schema (and are not yet supported)** will be also be added as comments to the Prisma schema as comments using the MySQL type, e.g. `macaddr` would be added to a model as follows: + +```prisma +model Device { + id Int @id @default(autoincrement()) + name String +// This type is currently not supported. +// data xml +} +``` \ No newline at end of file diff --git a/content/03-reference/02-database-connectors/03-sqlite.mdx b/content/03-reference/02-database-connectors/03-sqlite.mdx index 38dae3a2de..28633947c5 100644 --- a/content/03-reference/02-database-connectors/03-sqlite.mdx +++ b/content/03-reference/02-database-connectors/03-sqlite.mdx @@ -4,4 +4,64 @@ metaTitle: '' metaDescription: '' --- -Coming 🔜 +## Overview + +The SQLite data source connector connects Prisma to a [SQLite](https://www.sqlite.org/) database file. These files always have the file ending `.db` (e.g.: `dev.db`). + +## Example + +To connect to a SQLite database file, you need to configure a [`datasource`]() block in your [schema file](): + +```prisma +datasource sqlite { + provider = "sqlite" + url = "file:./dev.db" +} +``` + +The fields passed to the `datasource` block are: + +- `provider`: Specifies the `sqlite` data source connector. +- `url`: Specifies the [connection string](#connection-string) for the SQLite database. The connection string always starts with the prefix `file:` and then contains a file path pointing to the SQLite database file. In this case, the file is located in the same directory and called `dev.db`. + +## Data model mapping + +The SQLite connector maps the [scalar types]() from the [data model]() to native column types as follows: + +| Data model | SQLite | +| -------- | --------- | +| `String` | `TEXT` | +| `Boolean` | `BOOLEAN` | +| `Int` | `INTEGER` | +| `Float` | `REAL` | + +## Connection details + +### Connection URL + +The connection URL of a SQLite connector points to a file on your file system. For example, the following two paths are equivalent because the `.db` iss in the same directory: + +```prisma +datasource sqlite { + provider = "sqlite" + url = "file:./dev.db" +} +``` + +is the same as: + +```prisma +datasource sqlite { + provider = "sqlite" + url = "file:dev.db" +} +``` + +You can also target files from the root or any other place in your file system: + +```prisma +datasource sqlite { + provider = "sqlite" + url = "file:/Users/janedoe/dev.db" +} +``` \ No newline at end of file diff --git a/content/03-reference/02-database-connectors/04-connection-urls.mdx b/content/03-reference/02-database-connectors/04-connection-urls.mdx new file mode 100644 index 0000000000..48ac98ec52 --- /dev/null +++ b/content/03-reference/02-database-connectors/04-connection-urls.mdx @@ -0,0 +1,75 @@ +--- +title: 'Connection URLs' +metaTitle: '' +metaDescription: '' +--- + +## Overview + +Prisma needs a connection URL to be able to connect to your database, e.g. when sending queries with [Prisma Client]() or when changing the database schema with [Prisma Migrate](). + +The connection URL is provided via the `url` field of a `datasource` block in your Prisma schema. It generally consists of the following components (except for SQLite): + +- **User**: The name of your database user +- **Password**: The password for your database user +- **Host**: The IP or domain name of the machine where your database server is running +- **Port**: The port on which your database server is running +- **Database name**: The name of the database you want to use + +Make sure you have this information at hand when getting started with Prisma. If you don't have a database server running yet, you can either use a local SQLite database file (see the [Quickstart]()) or [setup a free PostgreSQL database on Heroku](https://dev.to/prisma/how-to-setup-a-free-postgresql-database-on-heroku-1dc1). + +## Examples + +Here are examples for the connection URLs of the databases Prisma supports: + +**PostgreSQL** + +```prisma +datasource postgresql { + provider = "postgresql" + url = "postgresql://janedoe:mypassword@localhost:5432/mydb" +} +``` + +**MySQL** + +```prisma +datasource mysql { + provider = "mysql" + url = "mysql://janedoe:mypassword@localhost:3306/mydb" +} +``` + +**SQLite** + +```prisma +datasource mysql { + provider = "sqlite" + url = "file:./dev.db" +} +``` + +Note thay you can also provide the connection URL as an environment variable like so: + +```prisma +datasource postgresql { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` + +You can then either set the environment variable in your terminal or by providing a [dotenv]() file called `.env`. This will automatically be picked up by the Prisma CLI. + +**.env** + +``` +DATABASE_URL=postgresql://janedoe:mypassword@localhost:5432/mydb +``` + +## Format + +The format of the connection URL depends on the _database connector_ you're using. Prisma generally supports the standard formats for each database. You can find out more about the connection URL of your database on the dedicated docs page: + +- [PostgreSQL]() +- [MySQL]() +- [SQLite]() \ No newline at end of file diff --git a/content/04-guides/01-database-workflows/07-data-validation/index.mdx b/content/04-guides/01-database-workflows/07-data-validation/index.mdx index d532994bde..e9a6ec135a 100644 --- a/content/04-guides/01-database-workflows/07-data-validation/index.mdx +++ b/content/04-guides/01-database-workflows/07-data-validation/index.mdx @@ -1,4 +1,4 @@ --- -title: 'Data validation' +title: 'Renaming tables and columns' metaTitle: '' --- diff --git a/content/05-more/01-about-the-docs.mdx b/content/05-more/01-about-the-docs.mdx index ff2ececf9f..f2311ca797 100644 --- a/content/05-more/01-about-the-docs.mdx +++ b/content/05-more/01-about-the-docs.mdx @@ -11,3 +11,7 @@ Coming 🔜 ## The `User` and `Post` data model `User` and `Post` are the canonical models that are being used throughout the Prisma docs. This page gives some context on why these have been selected and how to interpret them. + +## Naming conventions for tables and columns + +Table names are generally spelled in [PascalCase](). Column names in [camelCase]().