iv-org-mirror/shard-crystal-db
1
0
Fork 0
mirror of https://gitea.invidious.io/iv-org/shard-crystal-db.git synced 2024-08-15 00:53:32 +00:00
Code Issues Projects Releases Packages Wiki Activity

Documentation improvements (#107)

Browse source 
Closes #89
This commit is contained in:
Brian J. Cardiff 2019-07-02 10:01:17 -03:00 committed by GitHub
parent f14abc19fd
commit 0100b47754
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 66 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
README.md
View file

@ -4,14 +4,14 @@
Common db api for crystal. You will need to have a specific driver to access a database.
* [sqlite](https://github.com/crystal-lang/crystal-sqlite3)
* [mysql](https://github.com/crystal-lang/crystal-mysql)
* [postgres](https://github.com/will/crystal-pg)
* [cassandra](https://github.com/kaukas/crystal-cassandra)
* [SQLite](https://github.com/crystal-lang/crystal-sqlite3)
* [MySQL](https://github.com/crystal-lang/crystal-mysql)
* [PostgreSQL](https://github.com/will/crystal-pg)
* [Cassandra](https://github.com/kaukas/crystal-cassandra)
## Installation
Add this to your application's `shard.yml`:
If you are creating a shard that will work with _any_ driver, then add `crystal-db` as a dependency in `shard.yml`:
```yaml
dependencies:
@ -19,6 +19,18 @@ dependencies:
github: crystal-lang/crystal-db
```
If you are creating an application that will work with _some specific_ driver(s), then add them in `shard.yml`:
```yaml
dependencies:
sqlite3:
github: crystal-lang/crystal-sqlite3
```
`crystal-db` itself will be a nested dependency if drivers are included.
Note: Multiple drivers can be included in the same application.
## Documentation
* [Latest API](http://crystal-lang.github.io/crystal-db/api/latest/)
@ -26,7 +38,9 @@ dependencies:
## Usage
Since this is an abstract db api, its usage is through a concrete database driver.
This shard only provides an abstract database API. In order to use it, a specific driver for the intended database has to be required as well:
The following example uses SQLite where `?` indicates the arguments. If PostgreSQL is used `$1`, `$2`, etc. should be used. `crystal-db` does not interpret the statements.
```crystal
require "db"
@ -60,13 +74,14 @@ end
## Roadmap
Issues not yet addressed
Issues not yet addressed:
- [x] Support non prepared statements. [#25](https://github.com/crystal-lang/crystal-db/pull/25)
- [x] Time data type. (implementation details depends on actual drivers)
- [x] Data type extensibility. Allow each driver to extend the data types allowed.
- [x] Transactions & nested transactions. [#27](https://github.com/crystal-lang/crystal-db/pull/27)
- [x] Connection pool.
- [ ] Logging
- [ ] Direct access to `IO` to avoid memory allocation for blobs.
## Contributing

33
src/db.cr
View file

@ -1,16 +1,22 @@
require "uri"
# The DB module is a unified interface to database access.
# Database dialects is supported by custom database driver shards.
# Check [crystal-lang/crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) for example.
# The DB module is a unified interface for database access.
# Individual database systems are supported by specific database driver shards.
#
# Drivers implementors check `Driver` class.
# Available drivers include:
# * [crystal-lang/crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) for SQLite
# * [crystal-lang/crystal-mysql](https://github.com/crystal-lang/crystal-mysql) for MySQL and MariaDB
# * [will/crystal-pg](https://github.com/will/crystal-pg) for PostgreSQL
# * [kaukas/crystal-cassandra](https://github.com/kaukas/crystal-cassandra) for Cassandra
#
# DB manage a connection pool. The connection pool can be configured by `URI` query. See `Database`.
# For basic instructions on implementing a new database driver, check `Driver` and the existing drivers.
#
# DB manages a connection pool. The connection pool can be configured by query parameters to the
# connection `URI` as described in `Database`.
#
# ### Usage
#
# Assuming `crystal-sqlite3` is included a sqlite3 database can be opened with `#open`.
# Assuming `crystal-sqlite3` is included a SQLite3 database can be opened with `#open`.
#
# ```
# db = DB.open "sqlite3:./path/to/db/file.db"
@ -36,11 +42,14 @@ require "uri"
#
# Check a full working version:
#
# The following example uses SQLite where `?` indicates the arguments. If PostgreSQL is used `$1`, `$2`, etc. should be used. `crystal-db` does not interpret the statements.
#
# ```
# require "db"
# require "sqlite3"
#
# DB.open "sqlite3:./file.db" do |db|
# # When using the pg driver, use $1, $2, etc. instead of ?
# db.exec "create table contacts (name text, age integer)"
# db.exec "insert into contacts values (?, ?)", "John Doe", 30
#
@ -95,15 +104,19 @@ module DB
@@drivers ||= {} of String => Driver.class
end
# Opens a database using the specified *uri*.
# Creates a `Database` pool and opens initial connection(s) as specified in the connection *uri*.
# Use `DB#connect` to open a single connection.
#
# The scheme of the *uri* determines the driver to use.
# Returned database must be closed by `Database#close`.
# If a block is used the database is yielded and closed automatically.
# Connection parameters such as hostname, user, database name, etc. are specified according
# to each database driver's specific format.
#
# The returned database must be closed by `Database#close`.
def self.open(uri : URI | String)
build_database(uri)
end
# Same as `#open` but the database is yielded and closed automatically.
# Same as `#open` but the database is yielded and closed automatically at the end of the block.
def self.open(uri : URI | String, &block)
db = build_database(uri)
begin

36
src/db/database.cr
View file

@ -4,23 +4,29 @@ require "weak_ref"
module DB
# Acts as an entry point for database access.
# Connections are managed by a pool.
# The connection pool can be configured from URI parameters:
#
# - initial_pool_size (default 1)
# - max_pool_size (default 0 = unlimited)
# - max_idle_pool_size (default 1)
# - checkout_timeout (default 5.0)
# - retry_attempts (default 1)
# - retry_delay (in seconds, default 1.0)
#
# When querying a database prepared statements are used by default.
# This can be changed from the `prepared_statements` URI parameter:
#
# - prepared_statements = `true`|`false` (default `true`)
#
# It should be created from DB module. See `DB#open`.
# Use `DB#open` to create a `Database` instance.
#
# Refer to `QueryMethods` and `SessionMethods` for documentation about querying the database.
#
# ## Database URI
#
# Connection parameters are configured in a URI. The format is specified by the individual
# database drivers. See the [reference book](https://crystal-lang.org/reference/database/) for examples.
#
# The connection pool can be configured from URI parameters:
#
# - `initial_pool_size` (default 1)
# - `max_pool_size` (default 0 = unlimited)
# - `max_idle_pool_size` (default 1)
# - `checkout_timeout` (default 5.0)
# - `retry_attempts` (default 1)
# - `retry_delay` (in seconds, default 1.0)
#
# When querying a database, prepared statements are used by default.
# This can be changed from the `prepared_statements` URI parameter:
#
# - `prepared_statements` (true, or false, default true)
#
class Database
include SessionMethods(Database, PoolStatement)
include ConnectionContext