From 8892a0d3fbad8a712c34c808bed93bf7e5958700 Mon Sep 17 00:00:00 2001 From: Shay Rojansky Date: Sat, 28 Oct 2023 10:15:35 +0200 Subject: [PATCH] Documentation on storage parameters Following https://github.com/npgsql/efcore.pg/pull/2914 --- conceptual/EFCore.PG/modeling/indexes.md | 13 +++++++++++++ .../{table-column-naming.md => tables.md} | 15 ++++++++++++++- conceptual/EFCore.PG/release-notes/8.0.md | 2 ++ conceptual/EFCore.PG/toc.yml | 8 ++++---- 4 files changed, 33 insertions(+), 5 deletions(-) rename conceptual/EFCore.PG/modeling/{table-column-naming.md => tables.md} (72%) diff --git a/conceptual/EFCore.PG/modeling/indexes.md b/conceptual/EFCore.PG/modeling/indexes.md index 5dbf90faa..b3e02ecbd 100644 --- a/conceptual/EFCore.PG/modeling/indexes.md +++ b/conceptual/EFCore.PG/modeling/indexes.md @@ -63,6 +63,19 @@ Note that each operator class is used for the corresponding index column, by ord CREATE INDEX "IX_blogs_Id_Name" ON blogs ("Id", "Name" text_pattern_ops); ``` +## Storage parameters + +PostgreSQL allows configuring indexes with *storage parameters*, which can tweak their behaviors in various ways; which storage parameters are available depends on the chosen index method. [See the PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS) for more information. + +To configure a storage parameter on an index, use the following code: + +```c# +protected override void OnModelCreating(ModelBuilder modelBuilder) + => modelBuilder.Entity() + .HasIndex(b => b.Url) + .HasStorageParameter("fillfactor", 70); +``` + ## Creating indexes concurrently Creating an index can interfere with regular operation of a database. Normally PostgreSQL locks the table to be indexed against writes and performs the entire index build with a single scan of the table. Other transactions can still read the table, but if they try to insert, update, or delete rows in the table they will block until the index build is finished. This could have a severe effect if the system is a live production database. Very large tables can take many hours to be indexed, and even for smaller tables, an index build can lock out writers for periods that are unacceptably long for a production system. diff --git a/conceptual/EFCore.PG/modeling/table-column-naming.md b/conceptual/EFCore.PG/modeling/tables.md similarity index 72% rename from conceptual/EFCore.PG/modeling/table-column-naming.md rename to conceptual/EFCore.PG/modeling/tables.md index 264b53551..7a6f806d4 100644 --- a/conceptual/EFCore.PG/modeling/table-column-naming.md +++ b/conceptual/EFCore.PG/modeling/tables.md @@ -1,4 +1,6 @@ -# Table and Column Naming +# Tables + +## Naming By default, EF Core will map to tables and columns named exactly after your .NET classes and properties, so an entity type named `BlogPost` will be mapped to a PostgreSQL table called `BlogPost`. While there's nothing wrong with that, the PostgreSQL world tends towards snake_case naming instead. In addition, any upper-case letters in unquoted identifiers are automatically converted to lower-case identifiers, so the Npgsql provider generates quotes around all such identifiers. @@ -30,3 +32,14 @@ SELECT c.id, c.full_name ``` See the [plugin documentation](https://github.com/efcore/EFCore.NamingConventions) for more details, + +## Storage parameters + +PostgreSQL allows configuring tables with *storage parameters*, which can tweak storage behavior in various ways; [see the PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-STORAGE-PARAMETERS) for more information. + +To configure a storage parameter on a table, use the following code: + +```c# +protected override void OnModelCreating(ModelBuilder modelBuilder) + => modelBuilder.Entity().HasStorageParameter("fillfactor", 70); +``` diff --git a/conceptual/EFCore.PG/release-notes/8.0.md b/conceptual/EFCore.PG/release-notes/8.0.md index 7418dbc54..b0c2e343c 100644 --- a/conceptual/EFCore.PG/release-notes/8.0.md +++ b/conceptual/EFCore.PG/release-notes/8.0.md @@ -6,6 +6,8 @@ New features will be documented later. +* Storage parameters can now be configured on indexes ([see docs](../modeling/indexes.md)), and storage parameters are now scaffolded from existing databases for both tables and indexes. + ## Breaking changes Note: version 8.0 of the lower-level Npgsql ADO.NET driver, which is used by the EF provider, also has some breaking changes. It's recommended to read the [release notes](../../Npgsql/release-notes/8.0.md) for that as well. diff --git a/conceptual/EFCore.PG/toc.yml b/conceptual/EFCore.PG/toc.yml index 46c8cccbe..c82ed2712 100644 --- a/conceptual/EFCore.PG/toc.yml +++ b/conceptual/EFCore.PG/toc.yml @@ -24,14 +24,14 @@ href: release-notes/1.1.md - name: Creating a model items: - - name: Table and column naming - href: modeling/table-column-naming.md + - name: Tables + href: modeling/tables.md - name: Generated properties href: modeling/generated-properties.md - - name: Concurrency tokens - href: modeling/concurrency.md - name: Indexes href: modeling/indexes.md + - name: Concurrency tokens + href: modeling/concurrency.md - name: Mapping and translation items: - name: General