diff options
author | Austin Clements <austin@google.com> | 2014-10-22 13:25:37 -0400 |
---|---|---|
committer | Austin Clements <austin@google.com> | 2014-10-22 13:25:37 -0400 |
commit | 800a826ae560191d4dbb6c529eea15cf4349a06f (patch) | |
tree | c4206bb02365c3b9c66e2946031b86f0ee527faf /src/database/sql/doc.txt | |
parent | 2c586384223e980fd3303625ea6b02ed5d9fb9c0 (diff) | |
parent | 1678ee65674b332e900a703de296eb66fbadcf45 (diff) | |
download | go-800a826ae560191d4dbb6c529eea15cf4349a06f.tar.gz |
build: merge the great pkg/ rename into dev.power64
This also removes pkg/runtime/traceback_lr.c, which was ported
to Go in an earlier commit and then moved to
runtime/traceback.go.
Reviewer: rsc@golang.org
rsc: LGTM
Diffstat (limited to 'src/database/sql/doc.txt')
-rw-r--r-- | src/database/sql/doc.txt | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/src/database/sql/doc.txt b/src/database/sql/doc.txt new file mode 100644 index 000000000..405c5ed2a --- /dev/null +++ b/src/database/sql/doc.txt @@ -0,0 +1,46 @@ +Goals of the sql and sql/driver packages: + +* Provide a generic database API for a variety of SQL or SQL-like + databases. There currently exist Go libraries for SQLite, MySQL, + and Postgres, but all with a very different feel, and often + a non-Go-like feel. + +* Feel like Go. + +* Care mostly about the common cases. Common SQL should be portable. + SQL edge cases or db-specific extensions can be detected and + conditionally used by the application. It is a non-goal to care + about every particular db's extension or quirk. + +* Separate out the basic implementation of a database driver + (implementing the sql/driver interfaces) vs the implementation + of all the user-level types and convenience methods. + In a nutshell: + + User Code ---> sql package (concrete types) ---> sql/driver (interfaces) + Database Driver -> sql (to register) + sql/driver (implement interfaces) + +* Make type casting/conversions consistent between all drivers. To + achieve this, most of the conversions are done in the sql package, + not in each driver. The drivers then only have to deal with a + smaller set of types. + +* Be flexible with type conversions, but be paranoid about silent + truncation or other loss of precision. + +* Handle concurrency well. Users shouldn't need to care about the + database's per-connection thread safety issues (or lack thereof), + and shouldn't have to maintain their own free pools of connections. + The 'db' package should deal with that bookkeeping as needed. Given + an *sql.DB, it should be possible to share that instance between + multiple goroutines, without any extra synchronization. + +* Push complexity, where necessary, down into the sql+driver packages, + rather than exposing it to users. Said otherwise, the sql package + should expose an ideal database that's not finnicky about how it's + accessed, even if that's not true. + +* Provide optional interfaces in sql/driver for drivers to implement + for special cases or fastpaths. But the only party that knows about + those is the sql package. To user code, some stuff just might start + working or start working slightly faster. |