...
Run Format

Text file src/database/sql/doc.txt

Documentation: database/sql

     1	Goals of the sql and sql/driver packages:
     2	
     3	* Provide a generic database API for a variety of SQL or SQL-like
     4	  databases.  There currently exist Go libraries for SQLite, MySQL,
     5	  and Postgres, but all with a very different feel, and often
     6	  a non-Go-like feel.
     7	
     8	* Feel like Go.
     9	
    10	* Care mostly about the common cases. Common SQL should be portable.
    11	  SQL edge cases or db-specific extensions can be detected and
    12	  conditionally used by the application.  It is a non-goal to care
    13	  about every particular db's extension or quirk.
    14	
    15	* Separate out the basic implementation of a database driver
    16	  (implementing the sql/driver interfaces) vs the implementation
    17	  of all the user-level types and convenience methods.
    18	  In a nutshell:
    19	
    20	  User Code ---> sql package (concrete types) ---> sql/driver (interfaces)
    21	  Database Driver -> sql (to register) + sql/driver (implement interfaces)
    22	
    23	* Make type casting/conversions consistent between all drivers. To
    24	  achieve this, most of the conversions are done in the sql package,
    25	  not in each driver. The drivers then only have to deal with a
    26	  smaller set of types.
    27	
    28	* Be flexible with type conversions, but be paranoid about silent
    29	  truncation or other loss of precision.
    30	
    31	* Handle concurrency well.  Users shouldn't need to care about the
    32	  database's per-connection thread safety issues (or lack thereof),
    33	  and shouldn't have to maintain their own free pools of connections.
    34	  The 'sql' package should deal with that bookkeeping as needed.  Given
    35	  an *sql.DB, it should be possible to share that instance between
    36	  multiple goroutines, without any extra synchronization.
    37	
    38	* Push complexity, where necessary, down into the sql+driver packages,
    39	  rather than exposing it to users. Said otherwise, the sql package
    40	  should expose an ideal database that's not finnicky about how it's
    41	  accessed, even if that's not true.
    42	
    43	* Provide optional interfaces in sql/driver for drivers to implement
    44	  for special cases or fastpaths.  But the only party that knows about
    45	  those is the sql package.  To user code, some stuff just might start
    46	  working or start working slightly faster.

View as plain text