From 0100b47754622e5188b5f406325956a64cfaaae0 Mon Sep 17 00:00:00 2001 From: "Brian J. Cardiff" Date: Tue, 2 Jul 2019 10:01:17 -0300 Subject: [PATCH] Documentation improvements (#107) Closes #89 --- README.md | 29 ++++++++++++++++++++++------- src/db.cr | 33 +++++++++++++++++++++++---------- src/db/database.cr | 36 +++++++++++++++++++++--------------- 3 files changed, 66 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index ffa527b..fca3379 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/src/db.cr b/src/db.cr index 72be0cc..915e7b8 100644 --- a/src/db.cr +++ b/src/db.cr @@ -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 diff --git a/src/db/database.cr b/src/db/database.cr index 235edfe..565a4cf 100644 --- a/src/db/database.cr +++ b/src/db/database.cr @@ -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