diff --git a/documentation/content/images/postgres-sequence.png b/documentation/content/images/postgres-sequence.png new file mode 100644 index 0000000000..549752448b Binary files /dev/null and b/documentation/content/images/postgres-sequence.png differ diff --git a/documentation/content/images/postgres-table-definition.png b/documentation/content/images/postgres-table-definition.png new file mode 100644 index 0000000000..044c4ae131 Binary files /dev/null and b/documentation/content/images/postgres-table-definition.png differ diff --git a/documentation/documentation/order.txt b/documentation/documentation/order.txt index ccfb015651..4b57f19f1b 100644 --- a/documentation/documentation/order.txt +++ b/documentation/documentation/order.txt @@ -4,3 +4,4 @@ documents events precompiling scenarios +postgres \ No newline at end of file diff --git a/documentation/documentation/postgres/backup-restore/index.md b/documentation/documentation/postgres/backup-restore/index.md new file mode 100644 index 0000000000..788602be18 --- /dev/null +++ b/documentation/documentation/postgres/backup-restore/index.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/backup-restore/local.md b/documentation/documentation/postgres/backup-restore/local.md new file mode 100644 index 0000000000..2acd41469e --- /dev/null +++ b/documentation/documentation/postgres/backup-restore/local.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/backup-restore/remote.md b/documentation/documentation/postgres/backup-restore/remote.md new file mode 100644 index 0000000000..febd990fd2 --- /dev/null +++ b/documentation/documentation/postgres/backup-restore/remote.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/casing/case-insensitive-data.md b/documentation/documentation/postgres/casing/case-insensitive-data.md new file mode 100644 index 0000000000..f6766e17e7 --- /dev/null +++ b/documentation/documentation/postgres/casing/case-insensitive-data.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/casing/index.md b/documentation/documentation/postgres/casing/index.md new file mode 100644 index 0000000000..347167bda2 --- /dev/null +++ b/documentation/documentation/postgres/casing/index.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/casing/order.txt b/documentation/documentation/postgres/casing/order.txt new file mode 100644 index 0000000000..6412f5cf62 --- /dev/null +++ b/documentation/documentation/postgres/casing/order.txt @@ -0,0 +1,4 @@ +unique-values +case-insensitive-data +queries +using-duplicate-fields diff --git a/documentation/documentation/postgres/casing/queries.md b/documentation/documentation/postgres/casing/queries.md new file mode 100644 index 0000000000..0ac63fc189 --- /dev/null +++ b/documentation/documentation/postgres/casing/queries.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/casing/unique-values.md b/documentation/documentation/postgres/casing/unique-values.md new file mode 100644 index 0000000000..60c0b56ec3 --- /dev/null +++ b/documentation/documentation/postgres/casing/unique-values.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/casing/using-duplicate-fields.md b/documentation/documentation/postgres/casing/using-duplicate-fields.md new file mode 100644 index 0000000000..cf2fdaf14f --- /dev/null +++ b/documentation/documentation/postgres/casing/using-duplicate-fields.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/casting.md b/documentation/documentation/postgres/casting.md new file mode 100644 index 0000000000..befd5c1cc7 --- /dev/null +++ b/documentation/documentation/postgres/casting.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/dates.md b/documentation/documentation/postgres/dates.md new file mode 100644 index 0000000000..3e45d7350d --- /dev/null +++ b/documentation/documentation/postgres/dates.md @@ -0,0 +1,14 @@ + + + +SQL Server has functions for modifying a date, such as `DATEADD(…)` + +Postgres has an interval type which allows you to add/remove in a much more semantic manner. + +For example, in SQL Server to add 5 days to the current date we might do: + + SELECT DATEADD(day, 5, getutcdate()) + +In Postgres we would achieve the same like so: + + SELECT now() + ‘5 days’::interval; diff --git a/documentation/documentation/postgres/escaping.md b/documentation/documentation/postgres/escaping.md new file mode 100644 index 0000000000..46f4211daf --- /dev/null +++ b/documentation/documentation/postgres/escaping.md @@ -0,0 +1,10 @@ + + + +In SQL Server, escaping is done by wrapping with square brackets. + + select [Id] from [MyTable]; + +In Postgres this is done using double quotes. + + select "id" from "my_table"; diff --git a/documentation/documentation/postgres/if_statements.md b/documentation/documentation/postgres/if_statements.md new file mode 100644 index 0000000000..6382800b39 --- /dev/null +++ b/documentation/documentation/postgres/if_statements.md @@ -0,0 +1,66 @@ + + + +When ever you write SQL in SQL Server Management Studio, you're actually writing TSQL PostgreSQL supports SQL by default only and has key words for breaking out into other supported sub languages, the most common being PL/pgSQL (PostgresSQL) and plv8 (JavaScript run on the v8 engine) + +If statement's are not actually part of the SQL Spec *(The supported version of PostgreSQL 9.5 onwards supports most of the 2011 spec)*, and so in order to write if statements you need to use an anonymous code block with the language PL/pgSQL. + +For example: + + DO %% + BEGIN + + // your sql here… + + END + %%; + +Everything inside the begin/end will use PL/pgSQL by default as an assumed language. + +You can be explicit about the language by defining the language at the end of the block like so: + +DO %% +BEGIN + + // your sql here… + +END +%% LANGUAGE plpgsql; + +Note: `DO` is not part of the SQL Standard and is unique to PostgreSQL. + +An actual example, lets say we wanted to create a new schema called `inventory` if it didn’t exist already. + + DO $$ + BEGIN + IF NOT EXISTS( + SELECT schema_name + FROM information_schema.schemata + WHERE schema_name = 'inventory' + ) + THEN + EXECUTE 'CREATE SCHEMA inventory'; + END IF; + END + $$; + +It is worth noting that Postgres offers helpful syntax for scenarios you would usually use IF statements in SQL Server for. + +For example in SQL Server we might do the following: + + DROP PROCEDURE CreateProduct… + CREATE PROCEDURE CreateProduct… + +or + + IF NOT EXISTS (….) + BEGIN + CREATE TABLE Product (… + +These would be written in Postgres like so: + + CREATE OR REPLACE FUNCTION create_product + + CREATE TABLE IF NOT EXISTS Product (…. + +These don't require you to drop down to PL/pgSQ in order to execute. diff --git a/documentation/documentation/postgres/index.md b/documentation/documentation/postgres/index.md new file mode 100644 index 0000000000..ba31b8d840 --- /dev/null +++ b/documentation/documentation/postgres/index.md @@ -0,0 +1,11 @@ + + + +PostgreSQL has some of the best documentation available, and it's pretty easy to lookup any most anything to do with Postgres, however coming from SQL Server can sometimes be a bit of a barrier to entry. + +This documentation exists to help the transition for some of the basic usage patterns between the two databases and how help you better understand PostgreSQL so you can get the best out of what Marten has to offer. + + +## SQL Server to PostgreSQL Documentation + +<[TableOfContents]> diff --git a/documentation/documentation/postgres/indexing.md b/documentation/documentation/postgres/indexing.md new file mode 100644 index 0000000000..d0b864a4f8 --- /dev/null +++ b/documentation/documentation/postgres/indexing.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/indexing_jsonb.md b/documentation/documentation/postgres/indexing_jsonb.md new file mode 100644 index 0000000000..a26e28bce3 --- /dev/null +++ b/documentation/documentation/postgres/indexing_jsonb.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/naming.md b/documentation/documentation/postgres/naming.md new file mode 100644 index 0000000000..e15bef40ef --- /dev/null +++ b/documentation/documentation/postgres/naming.md @@ -0,0 +1,53 @@ + + + +When you design your database schema in SQL Server, it's common to name your tables and columns using pascal casing. For example, in SQL Server we may have a table like so: + + | Table Name | Product | + |------------|------------------| + | Columns | Id | + | | Name | + | | Price | + | | IsDeleted | + | | CategoryId | + | | CreatedByUser | + | | ModifiedByUser | + + +PostgreSQL stores all table and columns (that are not in double quotes) in lowercase, so the above would be stored as `product` rather than `Product`, if you run a select with uppercase against Postgres, the query will fail saying the column doesn’t exist. Thus, the Postgres convention for tables and columns, is to name everything lowercase with under scores. The above would become: + + + | Table Name | product | + |------------|------------------| + | Columns | id | + | | name | + | | price | + | | is_deleted | + | | category_id | + | | created_by_user | + | | modified_by_user | + + +While it is possible to use the convention from SQL Server, if you're looking at the table and column information from the database you will find it is stored in lowercase, this often makes it harder to read later. + +For example, if we created a table in Postgres, the same as we would in SQL Server. + + create table if not exists Product ( + Id serial, + Name text, + Price money, + IsDeleted bool, + CategoryId int, + CreatedByUser int, + ModifiedByUser int + ); + +When we query the table definition: + + select * + from INFORMATION_SCHEMA.COLUMNS + where table_name = 'product'; + +You can see from the screen grab that the table and columns are stored lowercase. + +![](/content/images/postgres-table-definition.png) diff --git a/documentation/documentation/postgres/order.txt b/documentation/documentation/postgres/order.txt new file mode 100644 index 0000000000..a21e07aebb --- /dev/null +++ b/documentation/documentation/postgres/order.txt @@ -0,0 +1,11 @@ +naming +escaping +types +casting +casing +slow_queries +indexing +indexing_jsonb +if_statements +dates +backup-restore diff --git a/documentation/documentation/postgres/slow_queries.md b/documentation/documentation/postgres/slow_queries.md new file mode 100644 index 0000000000..06e00bb75c --- /dev/null +++ b/documentation/documentation/postgres/slow_queries.md @@ -0,0 +1,4 @@ + + + +//TODO diff --git a/documentation/documentation/postgres/types.md b/documentation/documentation/postgres/types.md new file mode 100644 index 0000000000..5d021aaaa9 --- /dev/null +++ b/documentation/documentation/postgres/types.md @@ -0,0 +1,89 @@ + + + +PostgreSQL offers a lot more range when it comes to data types, and also allow you to easily create your own. However if you find yourself trying to translate your SQL Server knowledge to Postgres, you may run into some gotcha’s. + +The following table is a list of common data types from SQL Server and the Postgres equivalent. + + + | SQL Server | PostgreSQL | Notes | + |--------------|---------------|-----------------------------------------------------------------------------------------------------------------------------| + | int | int / integer | | + | int IDENTITY | serial | serial is the equivalent of SQL Servers auto generated number and is stored as an integer. Your C# code will still use int. | + | bit | boolean | Postgres has an actual boolean data type. | + +### serial + +Serial is interesting, because it can actually be used on multiple tables at the same time. + +If you define a table like so: + + create table if not exists serial_one ( + id serial, + name text + ); + + insert into serial_one (name) values ('phill'); + insert into serial_one (name) values ('james'); + + select * from serial_one; + +You will get a result with two values. And the `id` column will be incremented as you would expect. + +You can then query for sequences in Postgres by selecting from the `information_schema.sequences` table. + + select * from information_schema.sequences; + +There will be an entry for the sequence created by the table definition above. + +![](/content/images/postgres-sequence.png) + +The naming is: table_column_seq + +In this instance, the table is `serial_one`, the column is `id`, and the suffix is `seq` + +If you look at the table schema you can see the column is created with a default value of `nextval('serial_one_id_seq'::regclass)` + +So you can create your own table using the same sequence name, by defining the column as `int` with a default value. + + create table if not exists serial_two ( + id int not null default(nextval('serial_one_id_seq')), + name text + ); + + insert into serial_two (name) values ('demi'); + insert into serial_two (name) values ('nigel'); + + select * from serial_two; + +If you want to name the sequence yourself you can create the sequence first like: + + create sequence my_own_named_sequence + +Look at the Postgres Sequence docs for more info. + +https://www.postgresql.org/docs/9.5/static/sql-createsequence.html + +### boolean + +The boolean type is great to work with, you can use it in many ways. For example, assuming we had a user table with a boolean column `active` + +We could use various different queries like so: + + select * from users where active; + select * from users where not active; + +We can also use true/false instead of implicit checks. + + select * from users where active is true; + select * from users where active is false; + + -- or + + select * from users where active = true; + select * from users where active = false;; + + -- or + + select * from users where active is not true; + select * from users where active is not false;