[[SQLite]] is a lightweight SQL-compliant database. The download is about 244kb (command-line client + DLL).

SQLite implements most of the SQL92 and needs no configuration.

h3. Install SQLite

*Windows*

To use SQLite for windows you need two files:
# SQLite DLL 
# SQLite command-line client for creating tables

These can be downloaded as "precompiled binaries":http://www.sqlite.org/download.html at "SQLite's homepage":http://www.sqlite.org/

Add @sqlite.exe@ and @sqlite.dll@ to your path.

C:\ruby\bin

*Unix and Mac*

Most package managers put an *sqlite* or *sqlite3* binary in your path. 
If you built from source,  try _'/usr/local/bin/sqlite(3)'_.


h3. Get sqlite ruby gem

Use gem to install sqlite for Ruby. 

*Windows*

<code><pre>C:\work\rb\test>gem install sqlite

C:\work\rb\test>"c:\ruby\bin\ruby.exe" "c:\ruby\bin\gem" install sqlite
Attempting local installation of 'sqlite'
Local gem file not found: sqlite*.gem
Attempting remote installation of 'sqlite'
Select which gem to install for your platform (i386-mswin32)
 1. sqlite-ruby 2.2.3 (ruby)
 2. sqlite-ruby 2.2.3 (mswin32)
 3. sqlite-ruby 2.2.2 (ruby)
...
>
</pre></code>

Select option 2. 

*UNIX and Mac*

%{color:red}NOTE: _UNIX and Mac systems must have "swig":http://www.swig.org installed before installing the sqlite-ruby or sqlite3-ruby gem.  Otherwise the gem will not use the actual sqlite library, instead defaulting to a pure ruby sqlite library that doesn't work properly._%

h3. Create a database

SQLite stores databases in files. To create a new database, run the @sqlite@ command with a filename for your database, and start adding tables.

*Windows*

<code><pre>C:\work\rb\test>sqlite db\test.db
SQLite version 2.8.16
Enter ".help" for instructions
sqlite> create table articles
   ...> (id integer primary key,
   ...> title varchar(255),
   ...> text varchar(1024)
   ...> );
sqlite> .quit

C:\work\rb\test>dir db
 Volume in drive C has no label.
 Directory of C:\work\rb\test\db
14.04.2005  14:14             4 096 test.db
               1 File(s)          4 096 bytes
C:\work\rb\test>
</pre></code>

*Unix and Mac*

In a UNIX system, and provided that you have a file consisting of the SQL creation statements for this database (for example from an application you are deploying), you can shortcut the creation operation:
<code><pre>
$ mkdir ~/databases
$ cat /path/to/schema.sql | sqlite3 ~/databases/rails-app.db

SQLite version 3.1.2
Enter ".help" for instructions
sqlite> .schema
  
  # Prints the schema

sqlite> .quit
</pre></code>


h3. Configure database.yml to use sqlite

SQLite does not use authentication and needs only a pointer to the database file. 
The @adapter@ parameter tells Ruby to use SQLite for a database.

<code><pre>development:
  adapter: sqlite
  dbfile: db/test.db

test:
  adapter: sqlite
  dbfile: db/test.db

production:
  adapter: sqlite
  dbfile: db/test.db
</pre></code>

%{color:red}Please note: If you are using SQLite3 use "sqlite3" instead of "sqlite" for the value of the @adapter@ parameter.%

And you are done!

h3. Possible Gotchas

%{color:red}Q: I am experiencing strange database errors on Linux/Unix%

* "deadlock in timeoute.rb" error (usually through webrick)
*  "non-existent database or invalid SQL" error (usually through fcgi)

A: The sqlite gem is defaulting to a pure ruby version that doesn't always work.  The solution is:
# Uninstall the sqlite gem (sqlite-ruby or sqlite3-ruby).
# Install "swig":http://www.swig.org through your operating system's package manager or by downloading and compiling it. 
# Re-install the sqlite gem and now it should actually compile the 'native' extension using the actual sqlite binary dll.

%{color:red}Q: Windows version gives an error message like "Application failed to start because @sqlite.dll@ was not found. Re-installing the application may fix this problem."%

A: Make sure the @.dll@ and @.exe@ are in your path.

%{color:red}Q: SQLite::Exceptions::\DatabaseException _file is encrypted or is not a database_.%

A: It seems that sqlite databases created with version 2 do not work with sqlite version 3 and vice versa.

%{color:red}Q: SQLite returns "0.0" for values from database views.%

A: Looks like Rails thinks the field is a float? You can put numbers in the fields, but strings show up as 0.0. Try adding the field specifier (ex. TEXT) in the database definition.

%{color:red}Q: Using SQLite in Rails terminates the webrick server by throwing segfaults such as "deadlock 0xb781a95c: run:-/usr/lib/ruby/1.8/drb/drb.rb:932: [BUG] Segmentation fault". Any hints?%

A: This is likely to be a problem with sqlite-ruby. Maybe you didn't install it properly.  See the question above about strange database errors.

%{color:red}Q: It seems is that ActiveRecord's save method doesn't set the id of the inserted row after saving the record to a SQLite database. Is this an issue with SQLite or with ActiveRecord?%

A: Make sure the ID field is set as INTEGER PRIMARY KEY.  Not INT PRIMARY KEY or any other variation (and yes it is case sensitive)...

category:Howto
