Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update DB Readme #602

Merged
merged 2 commits into from
May 26, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion docs/database/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,8 @@ db.exec "insert into contacts values (?, ?)", "John", 30
# Postgres
db.exec "insert into contacts values ($1, $2)", "Sarah", 33
```
Query parameters are accomplished typically using PreparedStatements under the hood,
though this can be disabled via a connection string option `prepared_statements=false`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if that statement is correct. I don't think query parameters are technically tied to prepared statements.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also in a147195


## Query

Expand All @@ -91,6 +93,16 @@ db.query "select name, age from contacts order by age desc" do |rs|
end
```

You can also use query parameters:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Query parameters are already mentioned in more depth a couple lines above. It would probably make sense to move the explanation of query parameters to a separate section and reference that from both exec and query sections.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK attempted see a147195


```crystal
db.query("select name from contacts where age = ?", 33) do |rs|
rs.each do
# ... perform for each row in the ResultSet
end
end
```

When reading values from the database there is no type information during compile time that crystal can use. You will need to call `rs.read(T)` with the type `T` you expect to get from the database.

```crystal
Expand All @@ -105,7 +117,7 @@ db.query "select name, age from contacts order by age desc" do |rs|
end
```

There are many convenient query methods built on top of `#query`.
There are many convenient query methods built on top of `#query` to make this easier.

You can read multiple columns at once:

Expand All @@ -125,4 +137,5 @@ Or read a scalar value without dealing explicitly with the ResultSet:
max_age = db.scalar "select max(age) from contacts"
```

There are many other helper methods to query with types, query column names with types, etc.
All available methods to perform statements in a database are defined in `DB::QueryMethods`.