wehub-resource-sync
419 lines
12 KiB
Markdown
419 lines
12 KiB
Markdown
> This version of `drizzle-orm` requires `drizzle-kit@0.27.0` to enable all new features
|
||
|
||
# New Features
|
||
|
||
## Row-Level Security (RLS)
|
||
|
||
With Drizzle, you can enable Row-Level Security (RLS) for any Postgres table, create policies with various options, and define and manage the roles those policies apply to.
|
||
|
||
Drizzle supports a raw representation of Postgres policies and roles that can be used in any way you want. This works with popular Postgres database providers such as `Neon` and `Supabase`.
|
||
|
||
In Drizzle, we have specific predefined RLS roles and functions for RLS with both database providers, but you can also define your own logic.
|
||
|
||
### Enable RLS
|
||
|
||
If you just want to enable RLS on a table without adding policies, you can use `.enableRLS()`
|
||
|
||
As mentioned in the PostgreSQL documentation:
|
||
|
||
> If no policy exists for the table, a default-deny policy is used, meaning that no rows are visible or can be modified.
|
||
Operations that apply to the whole table, such as TRUNCATE and REFERENCES, are not subject to row security.
|
||
|
||
```ts
|
||
import { integer, pgTable } from 'drizzle-orm/pg-core';
|
||
|
||
export const users = pgTable('users', {
|
||
id: integer(),
|
||
}).enableRLS();
|
||
```
|
||
|
||
> If you add a policy to a table, RLS will be enabled automatically. So, there’s no need to explicitly enable RLS when adding policies to a table.
|
||
|
||
### Roles
|
||
|
||
Currently, Drizzle supports defining roles with a few different options, as shown below. Support for more options will be added in a future release.
|
||
|
||
```ts
|
||
import { pgRole } from 'drizzle-orm/pg-core';
|
||
|
||
export const admin = pgRole('admin', { createRole: true, createDb: true, inherit: true });
|
||
```
|
||
|
||
If a role already exists in your database, and you don’t want drizzle-kit to ‘see’ it or include it in migrations, you can mark the role as existing.
|
||
|
||
```ts
|
||
import { pgRole } from 'drizzle-orm/pg-core';
|
||
|
||
export const admin = pgRole('admin').existing();
|
||
```
|
||
|
||
### Policies
|
||
|
||
To fully leverage RLS, you can define policies within a Drizzle table.
|
||
|
||
> In PostgreSQL, policies should be linked to an existing table. Since policies are always associated with a specific table, we decided that policy definitions should be defined as a parameter of `pgTable`
|
||
|
||
**Example of pgPolicy with all available properties**
|
||
```ts
|
||
import { sql } from 'drizzle-orm';
|
||
import { integer, pgPolicy, pgRole, pgTable } from 'drizzle-orm/pg-core';
|
||
|
||
export const admin = pgRole('admin');
|
||
|
||
export const users = pgTable('users', {
|
||
id: integer(),
|
||
}, (t) => [
|
||
pgPolicy('policy', {
|
||
as: 'permissive',
|
||
to: admin,
|
||
for: 'delete',
|
||
using: sql``,
|
||
withCheck: sql``,
|
||
}),
|
||
]);
|
||
```
|
||
|
||
**Link Policy to an existing table**
|
||
|
||
There are situations where you need to link a policy to an existing table in your database.
|
||
The most common use case is with database providers like `Neon` or `Supabase`, where you need to add a policy
|
||
to their existing tables. In this case, you can use the `.link()` API
|
||
|
||
```ts
|
||
import { sql } from "drizzle-orm";
|
||
import { pgPolicy } from "drizzle-orm/pg-core";
|
||
import { authenticatedRole, realtimeMessages } from "drizzle-orm/supabase";
|
||
|
||
export const policy = pgPolicy("authenticated role insert policy", {
|
||
for: "insert",
|
||
to: authenticatedRole,
|
||
using: sql``,
|
||
}).link(realtimeMessages);
|
||
```
|
||
|
||
### Migrations
|
||
|
||
If you are using drizzle-kit to manage your schema and roles, there may be situations where you want to refer to roles that are not defined in your Drizzle schema. In such cases, you may want drizzle-kit to skip managing these roles without having to define each role in your drizzle schema and marking it with `.existing()`.
|
||
|
||
In these cases, you can use `entities.roles` in `drizzle.config.ts`. For a complete reference, refer to the the [`drizzle.config.ts`](https://orm.drizzle.team/docs/drizzle-config-file) documentation.
|
||
|
||
By default, `drizzle-kit` does not manage roles for you, so you will need to enable this feature in `drizzle.config.ts`.
|
||
|
||
```ts {12-14}
|
||
// drizzle.config.ts
|
||
import { defineConfig } from "drizzle-kit";
|
||
|
||
export default defineConfig({
|
||
dialect: 'postgresql',
|
||
schema: "./drizzle/schema.ts",
|
||
dbCredentials: {
|
||
url: process.env.DATABASE_URL!
|
||
},
|
||
verbose: true,
|
||
strict: true,
|
||
entities: {
|
||
roles: true
|
||
}
|
||
});
|
||
```
|
||
|
||
In case you need additional configuration options, let's take a look at a few more examples.
|
||
|
||
**You have an `admin` role and want to exclude it from the list of manageable roles**
|
||
|
||
```ts
|
||
// drizzle.config.ts
|
||
import { defineConfig } from "drizzle-kit";
|
||
|
||
export default defineConfig({
|
||
...
|
||
entities: {
|
||
roles: {
|
||
exclude: ['admin']
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
**You have an `admin` role and want to include it in the list of manageable roles**
|
||
|
||
```ts
|
||
// drizzle.config.ts
|
||
import { defineConfig } from "drizzle-kit";
|
||
|
||
export default defineConfig({
|
||
...
|
||
entities: {
|
||
roles: {
|
||
include: ['admin']
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
**If you are using `Neon` and want to exclude Neon-defined roles, you can use the provider option**
|
||
|
||
```ts
|
||
// drizzle.config.ts
|
||
import { defineConfig } from "drizzle-kit";
|
||
|
||
export default defineConfig({
|
||
...
|
||
entities: {
|
||
roles: {
|
||
provider: 'neon'
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
**If you are using `Supabase` and want to exclude Supabase-defined roles, you can use the provider option**
|
||
|
||
```ts
|
||
// drizzle.config.ts
|
||
import { defineConfig } from "drizzle-kit";
|
||
|
||
export default defineConfig({
|
||
...
|
||
entities: {
|
||
roles: {
|
||
provider: 'supabase'
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
> You may encounter situations where Drizzle is slightly outdated compared to new roles specified by your database provider.
|
||
In such cases, you can use the `provider` option and `exclude` additional roles:
|
||
|
||
```ts
|
||
// drizzle.config.ts
|
||
import { defineConfig } from "drizzle-kit";
|
||
|
||
export default defineConfig({
|
||
...
|
||
entities: {
|
||
roles: {
|
||
provider: 'supabase',
|
||
exclude: ['new_supabase_role']
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
### RLS on views
|
||
|
||
With Drizzle, you can also specify RLS policies on views. For this, you need to use `security_invoker` in the view's WITH options. Here is a small example:
|
||
|
||
```ts {5}
|
||
...
|
||
|
||
export const roomsUsersProfiles = pgView("rooms_users_profiles")
|
||
.with({
|
||
securityInvoker: true,
|
||
})
|
||
.as((qb) =>
|
||
qb
|
||
.select({
|
||
...getTableColumns(roomsUsers),
|
||
email: profiles.email,
|
||
})
|
||
.from(roomsUsers)
|
||
.innerJoin(profiles, eq(roomsUsers.userId, profiles.id))
|
||
);
|
||
```
|
||
|
||
### Using with Neon
|
||
|
||
The Neon Team helped us implement their vision of a wrapper on top of our raw policies API. We defined a specific
|
||
`/neon` import with the `crudPolicy` function that includes predefined functions and Neon's default roles.
|
||
|
||
Here's an example of how to use the `crudPolicy` function:
|
||
|
||
```ts
|
||
import { crudPolicy } from 'drizzle-orm/neon';
|
||
import { integer, pgRole, pgTable } from 'drizzle-orm/pg-core';
|
||
|
||
export const admin = pgRole('admin');
|
||
|
||
export const users = pgTable('users', {
|
||
id: integer(),
|
||
}, (t) => [
|
||
crudPolicy({ role: admin, read: true, modify: false }),
|
||
]);
|
||
```
|
||
|
||
This policy is equivalent to:
|
||
|
||
```ts
|
||
import { sql } from 'drizzle-orm';
|
||
import { integer, pgPolicy, pgRole, pgTable } from 'drizzle-orm/pg-core';
|
||
|
||
export const admin = pgRole('admin');
|
||
|
||
export const users = pgTable('users', {
|
||
id: integer(),
|
||
}, (t) => [
|
||
pgPolicy(`crud-${admin.name}-policy-insert`, {
|
||
for: 'insert',
|
||
to: admin,
|
||
withCheck: sql`false`,
|
||
}),
|
||
pgPolicy(`crud-${admin.name}-policy-update`, {
|
||
for: 'update',
|
||
to: admin,
|
||
using: sql`false`,
|
||
withCheck: sql`false`,
|
||
}),
|
||
pgPolicy(`crud-${admin.name}-policy-delete`, {
|
||
for: 'delete',
|
||
to: admin,
|
||
using: sql`false`,
|
||
}),
|
||
pgPolicy(`crud-${admin.name}-policy-select`, {
|
||
for: 'select',
|
||
to: admin,
|
||
using: sql`true`,
|
||
}),
|
||
]);
|
||
```
|
||
|
||
`Neon` exposes predefined `authenticated` and `anaonymous` roles and related functions. If you are using `Neon` for RLS, you can use these roles, which are marked as existing, and the related functions in your RLS queries.
|
||
|
||
```ts
|
||
// drizzle-orm/neon
|
||
export const authenticatedRole = pgRole('authenticated').existing();
|
||
export const anonymousRole = pgRole('anonymous').existing();
|
||
|
||
export const authUid = (userIdColumn: AnyPgColumn) => sql`(select auth.user_id() = ${userIdColumn})`;
|
||
```
|
||
|
||
For example, you can use the `Neon` predefined roles and functions like this:
|
||
|
||
|
||
```ts
|
||
import { sql } from 'drizzle-orm';
|
||
import { authenticatedRole } from 'drizzle-orm/neon';
|
||
import { integer, pgPolicy, pgRole, pgTable } from 'drizzle-orm/pg-core';
|
||
|
||
export const admin = pgRole('admin');
|
||
|
||
export const users = pgTable('users', {
|
||
id: integer(),
|
||
}, (t) => [
|
||
pgPolicy(`policy-insert`, {
|
||
for: 'insert',
|
||
to: authenticatedRole,
|
||
withCheck: sql`false`,
|
||
}),
|
||
]);
|
||
```
|
||
|
||
### Using with Supabase
|
||
|
||
We also have a `/supabase` import with a set of predefined roles marked as existing, which you can use in your schema.
|
||
This import will be extended in a future release with more functions and helpers to make using RLS and `Supabase` simpler.
|
||
|
||
```ts
|
||
// drizzle-orm/supabase
|
||
export const anonRole = pgRole('anon').existing();
|
||
export const authenticatedRole = pgRole('authenticated').existing();
|
||
export const serviceRole = pgRole('service_role').existing();
|
||
export const postgresRole = pgRole('postgres_role').existing();
|
||
export const supabaseAuthAdminRole = pgRole('supabase_auth_admin').existing();
|
||
```
|
||
|
||
For example, you can use the `Supabase` predefined roles like this:
|
||
|
||
```ts
|
||
import { sql } from 'drizzle-orm';
|
||
import { serviceRole } from 'drizzle-orm/supabase';
|
||
import { integer, pgPolicy, pgRole, pgTable } from 'drizzle-orm/pg-core';
|
||
|
||
export const admin = pgRole('admin');
|
||
|
||
export const users = pgTable('users', {
|
||
id: integer(),
|
||
}, (t) => [
|
||
pgPolicy(`policy-insert`, {
|
||
for: 'insert',
|
||
to: serviceRole,
|
||
withCheck: sql`false`,
|
||
}),
|
||
]);
|
||
```
|
||
|
||
The `/supabase` import also includes predefined tables and functions that you can use in your application
|
||
|
||
```ts
|
||
// drizzle-orm/supabase
|
||
|
||
const auth = pgSchema('auth');
|
||
export const authUsers = auth.table('users', {
|
||
id: uuid().primaryKey().notNull(),
|
||
});
|
||
|
||
const realtime = pgSchema('realtime');
|
||
export const realtimeMessages = realtime.table(
|
||
'messages',
|
||
{
|
||
id: bigserial({ mode: 'bigint' }).primaryKey(),
|
||
topic: text().notNull(),
|
||
extension: text({
|
||
enum: ['presence', 'broadcast', 'postgres_changes'],
|
||
}).notNull(),
|
||
},
|
||
);
|
||
|
||
export const authUid = sql`(select auth.uid())`;
|
||
export const realtimeTopic = sql`realtime.topic()`;
|
||
```
|
||
|
||
This allows you to use it in your code, and Drizzle Kit will treat them as existing databases,
|
||
using them only as information to connect to other entities
|
||
|
||
```ts
|
||
import { foreignKey, pgPolicy, pgTable, text, uuid } from "drizzle-orm/pg-core";
|
||
import { sql } from "drizzle-orm/sql";
|
||
import { authenticatedRole, authUsers } from "drizzle-orm/supabase";
|
||
|
||
export const profiles = pgTable(
|
||
"profiles",
|
||
{
|
||
id: uuid().primaryKey().notNull(),
|
||
email: text().notNull(),
|
||
},
|
||
(table) => [
|
||
foreignKey({
|
||
columns: [table.id],
|
||
// reference to the auth table from Supabase
|
||
foreignColumns: [authUsers.id],
|
||
name: "profiles_id_fk",
|
||
}).onDelete("cascade"),
|
||
pgPolicy("authenticated can view all profiles", {
|
||
for: "select",
|
||
// using predefined role from Supabase
|
||
to: authenticatedRole,
|
||
using: sql`true`,
|
||
}),
|
||
]
|
||
);
|
||
```
|
||
|
||
Let's check an example of adding a policy to a table that exists in `Supabase`
|
||
|
||
```ts
|
||
import { sql } from "drizzle-orm";
|
||
import { pgPolicy } from "drizzle-orm/pg-core";
|
||
import { authenticatedRole, realtimeMessages } from "drizzle-orm/supabase";
|
||
|
||
export const policy = pgPolicy("authenticated role insert policy", {
|
||
for: "insert",
|
||
to: authenticatedRole,
|
||
using: sql``,
|
||
}).link(realtimeMessages);
|
||
```
|
||
|
||
# Bug fixes
|
||
|
||
- [[BUG]: postgres-js driver throws error when using new { client } constructor arguments ](https://github.com/drizzle-team/drizzle-orm/issues/3176) |