Comments (8)
Sure. Here's some thoughts.
The Installation step in the ReadMe should also include the one-liner npm install pg decimal.js
so people can run and install it. Ideally, purescript-postgresql-client
would state that in their readme, but they don't. (When I originally tried this, I thought npm install decimal
was the same thing as npm install decimal.js
. Turns out it wasn't.)
I think the Setup section could be clearer about what must be true before the rest of that code will work. Stating this in a bullet point format will make it easier to see for a reader who is skimming through the guide:
- a database named
purspg
exists - a user called
init
with passwordquery
has been created
If you add the commands one would run in bash as an example to set that up, it would be even better. However, there's a point where the reader should do their own research on how to do that if they don't know already.
Rather than using a people
table as an initial introduction to tables, I would use metalanguage:
exampleTable :: Table
{ autonumber :: Auto Int
, someValue :: Int
, valueWithDefault :: Default Int
}
exampleTable = Table { name: "example_table" }
I wouldn't use this table in the rest of your examples. Rather, it would help explain what the column wrappers (i.e. Default, Auto) do.
Using a constraint constructor (Auto, Default) only affects insert operation. A column with Auto constraint cannot be inserted, while Default columns can be either omitted or provided. Other operations ignore these constraints and automatically unwrap it so queries return Int and not Auto Int.
I'd convert this paragraph into a table. Something like
Wrapper | on insert ... |
---|---|
None (e.g. Int ) |
value is required |
Default (e.g. Default Int ) |
value is optional |
Auto Int (e.g. Auto Int ) |
value cannot be referenced |
For the First Query part, I think it would be helpful to first see the SQL one would want to write, then show the PS code you would write to get the same result, and then show the outputted SQL the PS code creates.
Also, it would be helpful to see what the types are at various points (as long as they aren't too long). For example, rather than this
qNamesWithBalance
∷ ∀ s. FullQuery s { name ∷ Col s String , balance ∷ Col s (Maybe Int) }
qNamesWithBalance =
selectFrom people \{ id, name, age } → do
{ balance } ← leftJoin bankAccounts \acc → id .== acc.personId
restrict $ id .> lit 1
pure { name, balance }
you might have this:
qNamesWithBalance
∷ ∀ s. FullQuery s { name ∷ Col s String , balance ∷ Col s (Maybe Int) }
qNamesWithBalance =
selectFrom people leftJoinWhereAndSelectClauses
where
leftJoinWhereAndSelectClauses :: ?Full_Type_Goes_Here
leftJoinWhereAndSelectClauses { id, name, age } = do
{ balance } ← leftJoin bankAccounts \acc → id .== acc.personId
restrict $ id .> lit 1
pure { name, balance } -- aka the SELECT statement
In the Type Errors section, perhaps show an example of code that is incorrect and highlight via a comment which part is incorrect. Then explain what error message it produces, why it's incorrect, and then give the corrected version. You already do this in the first part of it by referring back to the previous query (i.e. qCountBankAccountOwners
), but it would be clearer if I saw the code again as an incorrect version rather than scrolling back up and having to figure out to reread it in light of your words.
I think overall it gives a good enough overview of the library. People will probably still need to read through your thesis to have a deeper understanding, but it is getting better.
from purescript-selda.
I think that maybe few words about PG.Aff
and PG.Class
would be a good intro to the Execution section. What do you think?
from purescript-selda.
@JordanMartinez, do you have any suggestions on this topic? What should be included in the guide or maybe you had some problems using selda that you wished were explained in a README (or completely redesigned). Your opinion would be greatly appreciated :)
from purescript-selda.
Sure! Thanks for asking. Here's just the initial thoughts that come to mind.
I read over your thesis and looked through the test code to figure out how to use this library. It took a while to figure out, but I finally got there.
I'd say it needs to be redesigned to rely less upon your thesis. That paper does a good job explaining how you solve the problem, but it's not something a new user of this library needs to know right away.
Generally, "good" documentation is broken down into 4 levels:
- The Hook - why should I care? How is this library relevant to me? (i.e. your about statement but with a more detailed example showing exactly why a type-safe query is a really good thing)
- Getting Started - what dependencies do I need to install and how? How do I run a basic select query? (e.g. define a table, define the query, run the query)
- How-Tos / Tutorials - how do I do specific things? (use Auto/Default columns, use columns with newtyped types, use
restrict
, use aggregates functions, common patterns used, what errors can arise if I import the wrong function because it has the same name as a function in the correct module?) - Implementation - what do I need to know in order to contribute? (e.g. what design decisions were made when implementing this and what are their tradeoffs? what are the main pieces to focus on?)
from purescript-selda.
Thanks for your detailed answer! We will start working on it as soon as we finish the current tasks
from purescript-selda.
Hi @JordanMartinez, I've made some progress. The README is slightly changed and it has a link to the guide (It is still WIP).
I wanted to cover all the basics and essential features without explaining in-depth everything. If you have any opinions on that we would like to hear 😉
from purescript-selda.
Thank you @JordanMartinez. I've applied some of your ideas 😉
from purescript-selda.
I think that also would be good to add a word in the same section about the fact that only backend which selda currently provides is the postgresql one and that insert
and insert1
which are implemented in this context use RETURNING
under the hood.
from purescript-selda.
Related Issues (20)
- Problem with "pg": "^7.6.0" in package.json
- Question about data intermediate representations HOT 9
- Auto field gets updated HOT 7
- Update returning similar to insert returning
- Easier logging of the update, insert ...
- SELECT values without FROM clause
- Better type inference for insert
- Delete returning
- IS NOT NULL as SQL expression not query needed HOT 4
- `offset` clause missing
- Select Count (*) error HOT 11
- Array distinct unnest ::TEXT[] HOT 3
- good first issues/bugs
- Nested structures/ JSON HOT 2
- Update to be compatible on v0.14.1 PS release HOT 2
- Enable value-level codecs to be used instead of type-level codecs HOT 3
- Is there a way to use `insert_` with `ON CONFLICT` HOT 3
- Add primitive queries that don't use type classes
- Update to the new `postgresql-client` API (upcoming v4.0.0)
- Mysql Support HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from purescript-selda.