Quick start

The best way to use NiceQL is to check-out library directly from github. This way you will get syncronised and up-to-date (when needed) version with sources and documentation. This tutorial is focused on using NiceQL checked-out from github.

Download NiceQL

1. Create folder for NiceQL on your PC and check-out library from git://github.com/Auxx/niceql.git
2. Import checked-out source in Eclipse. It should auto-build and you will get small JAR file inside NiceQL\bin folder called niceql.jar

Add NiceQL to your project

1. Open project properties (right click on your project in Package explorer or Navigator)
2. Go to Java Build Path, click on Libraries tab
3. Click Add JARs button if you have imported NiceQL project. Otherwise click Add External JARs
4. Select niceql.jar. Now it should appear in list of libraries
5. Expand nicel.jar entry and double click on Source attachement
6. Select NiceQL/src folder
7. Navigate to Order And Export
8. Tick a checkbox next to niceql.jar

Create a scheme

Database scheme contains tables with columns, tables may contain indices and may be prepopulated by seeds. This code example shows how to do all these tasks.

// Create table
Table table = new Table("articles");

// Add columns
table.addColumn(new Column("title", SqlColumn.TEXT, true));
table.addColumn(new Column("text", SqlColumn.TEXT));
table.addColumn(new Column("order_key", SqlColumn.INTEGER, true));

// Add indices
Index index = new Index("idx_articles_order_key", table, true);
index.addColumn("order_key");
table.addIndex(index);

// Add seeds to pre-populate table
ContentValues seed = new ContentValues();
seed.put("title", "Hello world!");
seed.put("text", "This is our first article.");
seed.put("order_key", 0);
table.addSeed(seed);

// Create scheme
Scheme scheme = new Scheme();
scheme.addTable(table);

Or you can make your life a lot easier and describe schema in [XML resource file](XML format). Creating scheme from XML is just one line of code!

// Create scheme
Scheme scheme = XmlScheme.parse(this, R.xml.sql_scheme);

Instances of Scheme class (implementors of SqlScheme actually) have getSql() method which will return SQL queries to create all tables specified in scheme. After that you can use getTables() method to iterate through tables and insert seed values by calling to getSeeds() method of Table instances. Or you can use SchemeOpenHelper (child of SQLiteOpenHelper) to open database connection and upload your scheme to database.

Use SchemeOpenHelper to establish connection

Android uses open helpers to give you access to database. Helpers check if database exists and if it does not, create a new one. SchemeOpenHelper wraps it all for you - just feed it Scheme and you are ready to go!

// Initialize SchemeOpenHelper
SchemeOpenHelper helper = new SchemeOpenHelper(this, "my_database", scheme);

// Get database connection object
// This line will check if database exists and will make sure it does
SQLiteDatabase db = helper.getWritableDatabase();

// Now you can execute queries
Cursor result = db.query("articles", null, null, null, null, null, "order_key DESC");

Extra-short version for lazy people

Put your scheme in XML and watch some magic!

SQLiteDatabase db = new SchemeOpenHelper(this, "my_database", XmlScheme.parse(this, R.xml.sql_scheme)).getWritableDatabase();