Introduce StatementCache

[jgallagher]

Mostly #61, with fixes for the latest merged PRs.

@gwenn I made a couple of minor changes here; the only public-facing one is removing cacheable and instead having a consuming method discard(). I think this feels a little nicer; what do you think?

[gwenn]

Typo here: prepared

[jgallagher]

👍 fixed

[gwenn]

Maybe you should wait before merging this PR.
Look at this: http://sfackler.github.io/rust-postgres/doc/v0.11.0/postgres/struct.Connection.html#method.prepare_cached

[jgallagher]

I don't think we can offer an API exactly like that. Their statement handles (the inner StatementInfo) are cloneable; it looks like they're basically just string names that are associated with some prepared query on the server side. We could modify Connection to have an internal StatementCache and then offer something like this API (leaving out lifetimes, not 100% sure what they'd be off the top of my head):

pub fn prepare_cached(&self, sql: &str) -> Result<CachedStatement>

but since we can't clone, we have to give something different than the Statement returned by prepare since we need to take the statement back when the caller is done with it.

[jgallagher]

@gwenn Pushed some fairly significant changes to this branch, trying to present an API more like the one you linked from rust-postgres. The relevant user-facing bits are in the impl Connection inside cache.rs. Do you want to take a look?

[gwenn]

The column_count cannot be saved in memory because it can be invalidated by a DDL:

db.execute("CREATE TABLE test (x TEXT)").unwrap();
// ...
let stmt = db.prepare_cached("SELECT * FROM test").unwrap();
// ...
db.execute("ALTER TABLE test ADD COLUMN y TEXT").unwrap();
// ...
stmt.stmt.query_map(&[], |row| {
            let x = row.get(0);
            let y = row.get(1); // PANIC ?
            // ...
    }).unwrap();

More precisely, only the Rows/Row can kept the column_count in memory (not the Statement).
And the one to blame for introducing this issue is me...
jgallagher@f91db1b
Sorry.

[jgallagher]

Nice catch! Added that test and a fix in 74b57ee. Notice any other issues?

[gwenn]

No other issue.
Having the cache embedded in the connection is nice.
Thanks.