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.