From 30e4705b41ae33afe1703546bf2c19066920a703 Mon Sep 17 00:00:00 2001 From: Steven Pousty Date: Thu, 11 Jul 2019 09:44:52 -0700 Subject: [PATCH] Ready for next rev of class (#37) * up to date (#1) * Cleanup * Use latest version of docker * Remove Docker first * Remove more of Docker * Start Docker after installing * fixed misspecification * breaking apart the workshop * beginning * finished first page and added to the dir * more scaffolding * more progress * mid progress in page 3 * a little more * done for now * fixing commands * normal typo and bug finding * typo fixes from @davecramer --- .../basicfunctions/01-first-function.md | 2 +- .../basicfunctions/02-name-parameters.md | 38 +++++++++++++------ .../basicfunctions/03-return-types.md | 29 ++++++-------- 3 files changed, 39 insertions(+), 30 deletions(-) diff --git a/basic-postgresql-devel/basicfunctions/01-first-function.md b/basic-postgresql-devel/basicfunctions/01-first-function.md index b0e361c5..82e27aa0 100644 --- a/basic-postgresql-devel/basicfunctions/01-first-function.md +++ b/basic-postgresql-devel/basicfunctions/01-first-function.md @@ -5,7 +5,7 @@ of programming language, need in order to work. ## Basic Pieces of Every Function -Just like functions in other languages, PostgreSQL functions has certain structure and syntax. Let's avoid dealing +Just like functions in other languages, PostgreSQL functions have certain structure and syntax. Let's avoid dealing with parameters for the time being and just make the simplest function possible. We are just going to make a simple function that returns, get ready for it, the string "hello world". diff --git a/basic-postgresql-devel/basicfunctions/02-name-parameters.md b/basic-postgresql-devel/basicfunctions/02-name-parameters.md index 04a44833..27a064bb 100644 --- a/basic-postgresql-devel/basicfunctions/02-name-parameters.md +++ b/basic-postgresql-devel/basicfunctions/02-name-parameters.md @@ -13,7 +13,7 @@ we are going to use this so we can keep iterating on our function. ## Parameterising Our Function -You know the next step in our function right? Of course we need to get it so say "Hello ". Let's start with the +You know the next step in our function right? Of course we need to get it so say "Hello [your name]". Let's start with the simplest way possible ``` @@ -39,7 +39,7 @@ $$ LANGUAGE sql; ```{{execute}} -If we had used more parameters we would keep incrementing the $number for each new parameter. The '||' is the concatenation +If we had used more parameters we would keep incrementing the $number for each new parameter. The '||' is the concatenation operator per the SQL standard. Let's go ahead and use our cool new function! @@ -70,9 +70,9 @@ as long as there is one string type in the concatenation. Time to exercise our function again: -''' +``` select brilliance('student', 1); -'''{{execute}} +```{execute}} ## Default Values for Parameters @@ -92,27 +92,41 @@ $$ LANGUAGE sql; ```{{execute}} -And now if we call our function we will get those values if we don't specify a value +And now if we call our function we will get those values if we don't specify a value. Before we do this we need to drop our +original function - think about why?.... -''' +``` +DROP FUNCTION brilliance(); +``` + +Since we already wrote a function named brilliance in step 1 that accepted no parameters, it is going to try and use that +rather than what we want to happen here. + +``` select brilliance(); -'''{{execute}} +```{{execute}} But we can also specify only one parameter and use the parameter name. Read more in the [official docs](https://www.postgresql.org/docs/11/sql-syntax-calling-funcs.html) about how to call functions: -''' +``` select brilliance(rank => 1); -'''{{execute}} +```{{execute}} ## Wrap Up **NOTE** No two functions can have the same name UNLESS they have different parameter signatures. For example, you can't have two functions named _myfunction_ unless one is myfunction() -and the other is myfunction(myparam varchar). What this also means is that you can overload a function to -do different behavior depending on the types passed in. Keep this in mind if you run into an error or trying to determine -how to architect your functions. +and the other is myfunction(myparam varchar). You could actually have functions: +1. myfunction() +1. myfunction(varchar) +1. myfunction(int) + +As long as the parameters are different (order does not matter) they can co-exist. What this also means is that you can +overload a function to do different behavior depending on the types passed in.As we saw above, having default values +along with over-ridden function names can sometimes cause issues for the users of the functions. +Keep this in mind if you run into an error or trying to determine how to architect your functions. Though we covered the basics of adding parameters to your functions we will return to this as we move on to the next section. diff --git a/basic-postgresql-devel/basicfunctions/03-return-types.md b/basic-postgresql-devel/basicfunctions/03-return-types.md index 062ecabd..08ead27c 100644 --- a/basic-postgresql-devel/basicfunctions/03-return-types.md +++ b/basic-postgresql-devel/basicfunctions/03-return-types.md @@ -12,14 +12,17 @@ PostgreSQL allows you to specify the "direction" data flows into a function base default all parameters are specified as IN parameters, meaning data is only passed into the function with the parameter. If you declare a parameter as OUT then data will be returned. You can have more than one OUT parameter in a function. Using a -RETURNS AS statement when you have OUT parameters is optional. If you -use the RETURNS AS statement with your function, it's type must match the type of our OUT parameters. +RETURNS {type} AS statement when you have OUT parameters is optional. If you +use the RETURNS {type}AS statement with your function, it's type must match the type of our OUT parameters. An INOUT parameter means it will be used to pass data in and then return data through this parameter name as well -For our function let's rid of the RETURNS AS statement and add another OUT parameter +For our function let's get rid of the RETURNS {type} AS statement and add another OUT parameter. We have to drop our function first +because Postgresql does NOT consider OUT parameters as a change in signature but by adding the OUTs we are changing the +return type. ``` +DROP FUNCTION brilliance(varchar, int); CREATE OR REPLACE FUNCTION brilliance(name varchar = 'Jorge', rank int = 7, out greetings varchar, out word_count int) AS @@ -52,9 +55,9 @@ for assignment of a single value or a single row we need to wrap our select stat When we use this function: -''' +``` select brilliance(); -'''{{execute}} +```{{execute}} Notice we get a different type of result: @@ -75,9 +78,9 @@ anonymous record type to hold the output. Let's make it a bit nicer to read: -''' +``` select * from brilliance(); -'''{{execute}} +```{{execute}} Which should give you a result like this: @@ -100,9 +103,9 @@ return anything you can use to define a column in a table, even your custom defi Quite often you are going to want to return a row in a table or perhaps a whole table (or use them as OUT parameters): 1. RETURNS RECORD - A record can be thought of as a single row in an arbitrary table. -1. RETURNS - If you want a row to obey the schema of a table you can just pass in the table name. +1. RETURNS {tablename} - If you want a row to obey the schema of a table you can just pass in the table name. 1. RETURNS SETOF RECORD - By adding the SETOF to the statement you can now return multiple records (rows) -1. RETURNS SETOF - And by extension, this will return multiple rows with a schema that obeys the table schema +1. RETURNS SETOF {tablename} - And by extension, this will return multiple rows with a schema that obeys the table schema Specific to the RETURNS X AS, you can actually define a table in the place of X. For example: @@ -113,14 +116,6 @@ RETURNS TABLE (id int, name text, quarter tsrange) As $$ ``` -## Clean up - -To get rid of our functions we can just do: - -''' -DROP FUNCTION brilliance; -``` - ## Wrap Up